Skip to main content
POST
/
attachment
/
v1
/
upload
Upload an attachment
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'
{
  "attachmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "file": {
    "name": "<string>",
    "mimeType": "<string>",
    "sizeInBytes": 123
  }
}
⚠️ Using our API via a dedicated deployment? Just replace api.langdock.com with your deployment’s base URL: <deployment-url>/api/public
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.
Upload files that can be referenced in Agent conversations using their attachment IDs.
Requires an API key with the KNOWLEDGE_FOLDER_API scope. You can create API Keys in your Workspace settings.

​
Request Format

This endpoint accepts multipart/form-data requests with a single file upload.
ParameterTypeRequiredDescription
fileFileYesThe 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) {
    switch (error.response.status) {
      case 400:
        console.error('No file provided');
        break;
      case 401:
        console.error('Invalid API key');
        break;
      case 500:
        console.error('Server error');
        break;
    }
  }
}
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

Successfully uploaded file

​
attachmentId
string<uuid>
required

Unique identifier for the uploaded attachment

​
file
object
required