Langbase

Thread: Create v1

The Threads API allows you to create and manage conversation threads for building conversational applications. Threads help you organize and maintain conversation history across multiple interactions.

The Threads API supports:

  • Creating new threads with optional initial messages
  • Adding metadata to threads for organization and filtering
  • Attaching initial messages to establish conversation context

Generate a User/Org API key

You will need to generate an API key to authenticate your requests. For more information, visit the User/Org API key documentation.

POST/v1/threads

Create a new thread

Create a new thread with optional initial messages and metadata.

Headers

  • Name
    Content-Type
    Type
    string
    Required
    Required
    Description

    Request content type. Needs to be application/json

  • Name
    Authorization
    Type
    string
    Required
    Required
    Description

    Replace LANGBASE_API_KEY with your User/Org API key

Body Parameters

  • Name
    threadId
    Type
    string
    Description

    Optional custom ID for the thread. If not provided, a unique ID will be generated.

  • Name
    metadata
    Type
    Record<string, string>
    Description

    Optional key-value pairs to store with the thread for organizational purposes.

  • Name
    messages
    Type
    Array<ThreadMessage>
    Description

    Optional initial messages to populate the thread.

    ThreadMessage Object

    interface ThreadMessage extends Message {
  attachments?: any[];
  metadata?: Record<string, string>;
}

interface Message {
  role: 'user' | 'assistant' | 'system' | 'tool';
  content: string | null;
  name?: string;
  tool_call_id?: string;
  tool_calls?: ToolCall[];
}
    • Name
      role
      Type
      string
      Required
      Required
      Description

      The role of the message author: system | user | assistant | tool

    • Name
      content
      Type
      string | null
      Required
      Required
      Description

      The content of the message. Can be null for tool calls.

    • Name
      name
      Type
      string
      Description

      Optional name identifier for the message author.

    • Name
      tool_call_id
      Type
      string
      Description

      ID of the tool call this message is responding to, if applicable.

    • Name
      tool_calls
      Type
      Array<ToolCall>
      Description

      Tool calls made in this message, if any.

      ToolCall Object

      interface ToolCall {
  id: string;
  type: 'function';
  function: {
    name: string;
    arguments: string;
  };
}
    • Name
      attachments
      Type
      Array<any>
      Description

      Optional attachments for the message.

    • Name
      metadata
      Type
      Record<string, string>
      Description

      Optional metadata for the message.

Usage example

Install the SDK

npm i langbase

Environment variables

.env file

LANGBASE_API_KEY="<USER/ORG-API-KEY>"

Create a new thread

Basic thread creation

POST
/v1/threads
import { Langbase } from 'langbase';

const langbase = new Langbase({
  apiKey: process.env.LANGBASE_API_KEY // Your User/Org API key
});

async function main() {
  const thread = await langbase.threads.create({
    metadata: {
      userId: "user123",
      topic: "support"
    },
    messages: [{
      role: "user",
      content: "Hello, I need help with my order!"
    }]
  });

  console.log('Thread created:', thread.id);
  return thread;
}

main();

Response

The response is a ThreadsBaseResponse object with information about the created thread.

  • Name
    id
    Type
    string
    Description

    The unique identifier for the thread.

  • Name
    object
    Type
    string
    Description

    The type of object. Always "thread".

  • Name
    created_at
    Type
    number
    Description

    The Unix timestamp (in seconds) for when the thread was created.

  • Name
    metadata
    Type
    Record<string, string>
    Description

    The metadata associated with the thread.

Response Example

{
 "id": "thread_abc123xyz456",
 "object": "thread",
 "created_at": 1714322048,
 "metadata": {
   "userId": "user123",
   "topic": "support"
 }
}