Assistant API

Creates a model response for a given assistant id, or pass in an Assistant configuration that should be used for your request.

To share an assistant with an API key, follow this guide

Request Parameters

Parameter	Type	Required	Description
`assistantId`	string	One of assistantId/assistant required	ID of an existing assistant to use
`assistant`	object	One of assistantId/assistant required	Configuration for a new assistant
`messages`	array	Yes	Array of message objects with role and content
`stream`	boolean	No	Enable streaming responses (default: false)
`output`	object	No	Structured output format specification

Message Format

Each message in the messages array should contain:

role (required) - One of: “user”, “assistant”, or “tool”
content (required) - The message content as a string
attachmentIds (optional) - Array of UUID strings identifying attachments for this message

Assistant Configuration

When creating a temporary assistant, you can specify:

name (required) - Name of the assistant (max 64 chars)
instructions (required) - System instructions (max 16384 chars)
description - Optional description (max 256 chars)
temperature - Temperature between 0-1
model - Model ID to use (see Available Models for options)
capabilities - Enable features like web search, data analysis, image generation
actions - Custom API integrations
vectorDb - Vector database connections
knowledgeFolderIds - IDs of knowledge folders to use
attachmentIds - Array of UUID strings identifying attachments to use

You can retrieve a list of available models using the Models API. This is useful when you want to see which models you can use in your assistant configuration.

Structured Output

You can specify a structured output format using the optional output parameter:

Field	Type	Description
`type`	”object” \| “array” \| “enum”	The type of structured output
`schema`	object	JSON Schema definition for the output (for object/array types)
`enum`	string[]	Array of allowed values (for enum type)

The output parameter behavior depends on the specified type:

type: "object" with no schema: Forces the response to be a single JSON object (no specific structure)
type: "object" with schema: Forces the response to match the provided JSON Schema
type: "array" with schema: Forces the response to be an array of objects matching the provided schema
type: "enum": Forces the response to be one of the values specified in the enum array

You can use tools like easy-json-schema to generate JSON Schemas from example JSON objects.

Streaming Responses

When stream is set to true, the API will return a stream of server-sent events (SSE) instead of waiting for the complete response. This allows you to display responses to users progressively as they are generated.

Stream Format

Each event in the stream follows the SSE format with JSON data:

data: {"type":"message","content":"Hello"}
data: {"type":"message","content":" world"}
data: {"type":"done"}

Handling Streams in JavaScript

const response = await fetch('https://api.langdock.com/assistant/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    assistantId: 'asst_123',
    messages: [{ role: 'user', content: 'Hello' }],
    stream: true
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      if (data.type === 'message') {
        process.stdout.write(data.content);
      }
    }
  }
}

Obtaining Attachment IDs

To use attachments in your assistant conversations, you first need to upload the files using the Upload Attachment API. This will return an attachmentId for each file, which you can then include in the attachmentIds array in your assistant or message configuration.

Examples

Using an Existing Assistant

const axios = require("axios");

async function chatWithAssistant() {
  const response = await axios.post(
    "https://api.langdock.com/assistant/v1/chat/completions",
    {
      assistantId: "asst_123",
      messages: [
        {
          role: "user",
          content: "Can you analyze this document for me?",
          attachmentIds: ["550e8400-e29b-41d4-a716-446655440000"], // Obtain attachmentIds from upload attachment endpoint
        },
      ],
      stream: true, // Enable streaming responses
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
      },
    }
  );

  console.log(response.data.result);
}

Using a temporary Assistant configuration

const axios = require("axios");

async function chatWithNewAssistant() {
  const response = await axios.post(
    "https://api.langdock.com/assistant/v1/chat/completions",
    {
      assistant: {
        name: "Document Analyzer",
        instructions:
          "You are a helpful assistant who analyzes documents and answers questions about them",
        temperature: 0.7,
        model: "gpt-4",
        capabilities: {
          webSearch: true,
          dataAnalyst: true,
        },
        attachmentIds: ["550e8400-e29b-41d4-a716-446655440000"], // Obtain attachmentIds from upload attachment endpoint
      },
      messages: [
        {
          role: "user",
          content: "What are the key points in the document?",
        },
      ],
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
      },
    }
  );

  console.log(response.data.result);
}

Using Structured Output with Schema

const axios = require("axios");

async function getStructuredWeather() {
  const response = await axios.post(
    "https://api.langdock.com/assistant/v1/chat/completions",
    {
      assistant: {
        name: "Weather Assistant",
        instructions: "You are a helpful weather assistant",
        capabilities: {
          webSearch: true,
        },
      },
      messages: [
        {
          role: "user",
          content: "What's the weather in paris, berlin and london today?",
        },
      ],
      output: {
        type: "array",
        schema: {
          type: "object",
          properties: {
            weather: {
              type: "object",
              properties: {
                city: {
                  type: "string",
                },
                tempInCelsius: {
                  type: "number",
                },
                tempInFahrenheit: {
                  type: "number",
                },
              },
              required: ["city", "tempInCelsius", "tempInFahrenheit"],
            },
          },
        },
      },
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
      },
    }
  );

  console.log(response.data);
}

Using Structured Output with Enum

const axios = require("axios");

async function getSentimentAnalysis() {
  const response = await axios.post(
    "https://api.langdock.com/assistant/v1/chat/completions",
    {
      assistant: {
        name: "Sentiment Analyzer",
        instructions: "You analyze the sentiment of text",
      },
      messages: [
        {
          role: "user",
          content:
            "How would you rate this review: 'This product exceeded my expectations!'",
        },
      ],
      output: {
        type: "enum",
        enum: ["positive", "neutral", "negative"],
      },
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
      },
    }
  );

  console.log(response.data);
}

Rate limits

The rate limit for the Assistant Completion endpoint is 500 RPM (requests per minute) and 60.000 TPM (tokens per minute). Rate limits are defined at the workspace level - and not at an API key level. Each model has its own rate limit. If you exceed your rate limit, you will receive a 429 Too Many Requests response. Please note that the rate limits are subject to change, refer to this documentation for the most up-to-date information. In case you need a higher rate limit, please contact us at support@langdock.com.

Response Format

The API returns an object containing:

{
  // Standard message results - always present
  result: Array<{
    id: string;
    role: "tool" | "assistant";
    content: Array<{
      type: string;
      toolCallId?: string;
      toolName?: string;
      result?: object;
      args?: object;
      text?: string;
    }>;
  }>;

  // Structured output - present when output parameter was specified
  output?: object | array | string;
}

Standard Result

The result array contains the message exchange between user and assistant, including any tool calls that were made. This is always present in the response.

Structured Output

When the request includes an output parameter, the response will also include an output field. The type of this field depends on the requested output format:

If output.type was “object”: Returns a JSON object (with schema validation if schema was provided)
If output.type was “array”: Returns an array (with schema validation if schema was provided)
If output.type was “enum”: Returns a string matching one of the provided enum values

For example, when requesting weather data with structured output:

// Request
{
  "output": {
    "type": "array",
    "schema": {
      "type": "object",
      "properties": {
        "weather": {
          "type": "object",
          "properties": {
            "city": { "type": "string" },
            "tempInCelsius": { "type": "number" }
          }
        }
      }
    }
  }
}

// Response
{
  "result": [ /* standard message results */ ],
  "output": [
    {
      "weather": {
        "city": "Paris",
        "tempInCelsius": 22
      }
    },
    {
      "weather": {
        "city": "London",
        "tempInCelsius": 18
      }
    }
  ]
}

Error Handling

try {
  const response = await axios.post('https://api.langdock.com/assistant/v1/chat/completions', ...);
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 400:
        console.error('Invalid parameters:', error.response.data.message);
        break;
      case 429:
        console.error('Rate limit exceeded');
        break;
      case 500:
        console.error('Server error');
        break;
    }
  }
}

Headers

Authorization

string

required

API key as Bearer token. Format "Bearer YOUR_API_KEY"

Body

application/json

Option 1
Option 2

assistantId

string

required

ID of an existing assistant to use

messages

object[]

required

Show child attributes

stream

boolean

default:false

Enable or disable streaming responses. When true, returns server-sent events. When false, returns complete JSON response.

Example:

true

output

object

Specification for structured output format. When type is object/array and no schema is provided, the response will be JSON but can have any structure. When the type is enum, you must provide an enum parameter with an array of strings as options.

Option 1
Option 2
Option 3

Show child attributes

maxSteps

integer

default:10

Maximum number of steps the assistant can take during the conversation

Required range: 1 <= x <= 20

Response

Successful chat completion

result

object[]

required

Show child attributes

output

Present when output parameter was specified in the request When output.type is "object"

Overview

Completion API

Embedding API

Knowledge Folder API

Usage Export API

Assistant API

Request Parameters

Message Format

Assistant Configuration

Structured Output

Streaming Responses

Stream Format

Handling Streams in JavaScript

Obtaining Attachment IDs

Examples

Using an Existing Assistant

Using a temporary Assistant configuration

Using Structured Output with Schema

Using Structured Output with Enum

Rate limits

Response Format

Standard Result

Structured Output

Error Handling

Headers

Body

Response

Overview

Completion API

Embedding API

Assistant API

Knowledge Folder API

Usage Export API

​Request Parameters

​Message Format

​Assistant Configuration

​Structured Output

​Streaming Responses

​Stream Format

​Handling Streams in JavaScript

​Obtaining Attachment IDs

​Examples

​Using an Existing Assistant

​Using a temporary Assistant configuration

​Using Structured Output with Schema

​Using Structured Output with Enum

​Rate limits

​Response Format

​Standard Result

​Structured Output

​Error Handling

Headers

Body

Response

Request Parameters

Message Format

Assistant Configuration

Structured Output

Streaming Responses

Stream Format

Handling Streams in JavaScript

Obtaining Attachment IDs

Examples

Using an Existing Assistant

Using a temporary Assistant configuration

Using Structured Output with Schema

Using Structured Output with Enum

Rate limits

Response Format

Standard Result

Structured Output

Error Handling