Upload Attachment API

Upload files to be used with Agents

POST /attachment/v1/upload

Upload an attachment

cURL

curl --request POST \
  --url https://api.langdock.com/attachment/v1/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file'

200

Example

{
  "attachmentId": "550e8400-e29b-41d4-a716-446655440000",
  "file": {
    "name": "example.pdf",
    "mimeType": "application/pdf",
    "sizeInBytes": 1234567
  }
}

Upload files that can be referenced in Agent conversations using their attachment IDs.

Before You Start

• API key scope: Requires an API key with the KNOWLEDGE_FOLDER_API scope. You can create API Keys in your Workspace settings.
• Legacy Assistants API: This is the new Agents API with native Vercel AI SDK compatibility. The upload attachment endpoint is shared across both APIs. If you’re using the legacy Assistants API, see the migration guide.

Base URL

https://api.langdock.com/attachment/v1/upload

Dedicated deployments

Replace api.langdock.com with <your-deployment-url>/api/public in all requests.

Request Format

This endpoint accepts multipart/form-data requests with a single file upload.

Parameter	Type	Required	Description
file	File	Yes	The file you want to upload

Response Format

The API returns the uploaded file information:

{
  attachmentId: string;
  file: {
    name: string;
    mimeType: string;
    sizeInBytes: number;
  }
}

Example

const axios = require("axios");
const FormData = require("form-data");
const fs = require("fs");

async function uploadAttachment() {
  const form = new FormData();
  form.append("file", fs.createReadStream("example.pdf"));

  const response = await axios.post(
    "https://api.langdock.com/attachment/v1/upload",
    form,
    {
      headers: {
        ...form.getHeaders(),
        Authorization: "Bearer YOUR_API_KEY",
      },
    }
  );

  console.log(response.data);
  // {
  //   attachmentId: "550e8400-e29b-41d4-a716-446655440000",
  //   file: {
  //     name: "example.pdf",
  //     mimeType: "application/pdf",
  //     sizeInBytes: 1234567
  //   }
  // }
}

Error Handling

try {
  const response = await axios.post('https://api.langdock.com/attachment/v1/upload', ...);
} catch (error) {
  if (error.response) {
    const { data } = error.response;
    console.error(data.message ?? data.error ?? "Upload failed");
  }
}

Upload errors

Status	Meaning	Reason field
400	Invalid request or failed file validation	message, or error if no file was provided
401	Invalid or missing API key	message
403	API key is missing the required scope	message
406	Blocked file type	message
413	File exceeds the size limit	message
429	Rate limit exceeded	message
500	Unexpected server error	message

A file content validation error returns:

{
  "message": "The file \"example.pdf\" is declared as a PDF but its content does not start with the expected PDF header.",
  "code": "BAD_REQUEST"
}

Use the attachment

The uploaded attachment ID can be used in the Agent API in two ways:

1. Per-message (recommended): Include the attachment UUID in the message’s metadata.attachments array when calling the Completions API
2. Agent-level: Include the attachment UUID in the attachments array when creating or updating an agent

Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on API Key Best Practices.

Authorizations

Authorization · string · header · required

API key as Bearer token. Format "Bearer YOUR_API_KEY"

Body

multipart/form-data

file · file · required

The file to upload

Response

200

application/json

Successfully uploaded file

attachmentId · string<uuid> · required

Unique identifier for the uploaded attachment

Example:

"550e8400-e29b-41d4-a716-446655440000"

file · object · required

Show child attributes