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: https://docs.langdock.com/api-endpoints/assistant/assistant-api-guide

Endpoint POST https://api.langdock.com/assistant/v1/chat/completions

cURL example

curl

curl --request POST \
  --url https://api.langdock.com/assistant/v1/chat/completions \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "assistantId": "asst_123",
  "messages": [
    {
      "role": "user",
      "content": "Hello, how can you help me?"
    }
  ],
  "stream": false,
  "maxSteps": 10
}
'

Response (successful)

200 response example

{
  "result": [
    {
      "id": "<string>",
      "role": "tool",
      "content": [
        {
          "type": "<string>",
          "toolCallId": "<string>",
          "toolName": "<string>",
          "result": {},
          "args": {},
          "text": "<string>"
        }
      ]
    }
  ],
  "output": {}
}

---

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
maxSteps	integer	No (default: 10)	Maximum number of steps the assistant can take (1–20)

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 (use assistant instead of assistantId), 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: https://docs.langdock.com/api-endpoints/assistant/assistant-models)

• 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: https://docs.langdock.com/api-endpoints/assistant/assistant-models

---

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)

Behavior:

• 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 in enum

Tools such as easy-json-schema can help generate JSON Schema: https://easy-json-schema.github.io/

---

Streaming Responses

When stream is true, the API returns server-sent events (SSE) allowing progressive display of generated responses.

Stream format example:

SSE stream example

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

Handling streams in JavaScript:

streaming fetch (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 conversations, first upload files using the Upload Attachment API: https://docs.langdock.com/api-endpoints/assistant/upload-attachments. The upload returns attachmentId values which you can include in attachmentIds.

---

Examples

Using an existing assistant

Node (axios) - 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"]
        }
      ],
      stream: true
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
      },
    }
  );

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

Using a temporary assistant configuration

Node (axios) - temporary assistant

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"]
      },
      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 (array)

Node (axios) - structured output (array)

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",
        model: "gpt-5.1",
        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.output);
}

Using Structured Output with Object

Node (axios) - structured output (object)

const axios = require("axios");

async function extractContactInfo() {
  const response = await axios.post(
    "https://api.langdock.com/assistant/v1/chat/completions",
    {
      assistant: {
        name: "Contact Extractor",
        instructions: "You extract contact information from text",
      },
      messages: [
        {
          role: "user",
          content:
            "Extract the contact info: John Smith is our new sales lead. You can reach him at [email protected] or call [phone]."
        }
      ],
      output: {
        type: "object",
        schema: {
          type: "object",
          properties: {
            name: { type: "string" },
            email: { type: "string" },
            phone: { type: "string" },
            role: { type: "string" }
          },
          required: ["name", "email"]
        }
      }
    },
    {
      headers: { Authorization: "Bearer YOUR_API_KEY" }
    }
  );

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

Using Structured Output with Enum

Node (axios) - structured output (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.output);
}

---

Rate limits

The rate limit for the Assistant Completion endpoint is:

• 500 RPM (requests per minute)

• 60,000 TPM (tokens per minute)

Rate limits are defined at the workspace level (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.

For higher rate limits, contact: [email protected]

---

Response Format

The API returns an object containing:

Response schema

{
  "result": [
    {
      "id": "string",
      "role": "tool" | "assistant",
      "content": [
        {
          "type": "string",
          "toolCallId": "string?",
          "toolName": "string?",
          "result": {},
          "args": {},
          "text": "string?"
        }
      ]
    }
  ],
  "output": {} // optional: object | array | string (present when output parameter specified)
}

• result: Array containing the full conversation and any tool calls (always present).

• output: Present when output parameter was specified in the request. Contains formatted structured data (object, array, or enum string).

Example (weather structured output)

Response example (structured output)

{
  "result": [
    { "role": "assistant", "content": [...], "id": "..." },
    { "role": "tool", "content": [...], "id": "..." },
    { "role": "assistant", "content": "...", "id": "..." }
  ],
  "output": [
    { "weather": { "city": "Paris", "tempInCelsius": 1, "tempInFahrenheit": 33 } },
    { "weather": { "city": "Berlin", "tempInCelsius": 1, "tempInFahrenheit": 35 } },
    { "weather": { "city": "London", "tempInCelsius": 7, "tempInFahrenheit": 45 } }
  ]
}

The output field is populated automatically and can be consumed directly by your application.

---

Error Handling

Example (axios):

Error handling example

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 (required)

• Type: string

• Format: "Bearer YOUR_API_KEY"

Content-Type: application/json

---

Body (application/json)

Option 1: Provide assistantId (use existing assistant)

• assistantId (string, required when using this option)

• messages (array, required)

Option 2: Provide assistant object (temporary assistant configuration)

• assistant (object, required when using this option)

• messages (array, required)

Common body fields

• messages (array of objects) — each item:

  • role (enum: user, assistant, tool) — required

  • content (string) — required

  • attachmentIds (string[uuid]) — optional

• stream (boolean, default: false) — when true returns SSE

• output (object) — structured output spec:

  • type (enum: object | array | enum)

  • schema (object) — JSON Schema for object/array types

  • enum (string[]) — required when type: "enum"

---

Response Codes

• 200 — Successful chat completion (application/json)

• 400 — Invalid parameters

• 429 — Rate limit exceeded

• 500 — Server error

---

Related

• Sharing Assistants with API Keys: https://docs.langdock.com/api-endpoints/assistant/assistant-api-guide

• Models for Assistant API: https://docs.langdock.com/api-endpoints/assistant/assistant-models

Notes

• Responses are generated using AI and may contain mistakes.