> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Upload Attachment API
> Upload files to be used with Agents
**⚠️ Using our API via a dedicated deployment?** Just replace `api.langdock.com` with your deployment's base 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](/en/developer/assistants-api/assistant-to-agent-migration).
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](https://app.langdock.com/settings/workspace/products/api).
## 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:
```typescript theme={null}
{
attachmentId: string;
file: {
name: string;
mimeType: string;
sizeInBytes: number;
}
}
```
## Example
```javascript theme={null}
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
```javascript theme={null}
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:
```json theme={null}
{
"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](/en/developer/agents-api/agent)
2. **Agent-level**: Include the attachment UUID in the `attachments` array when [creating](/en/developer/agents-api/agent-create) or [updating](/en/developer/agents-api/agent-update) 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](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
## OpenAPI
````yaml POST /attachment/v1/upload
openapi: 3.0.0
info:
title: Langdock API
version: 3.0.0
servers:
- url: https://api.langdock.com
description: Production
security:
- bearerAuth: []
paths:
/attachment/v1/upload:
post:
tags:
- Attachments
summary: Upload an attachment
description: Upload a file that can be referenced in Agent conversations.
operationId: uploadAttachment
parameters: []
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
description: The file to upload
responses:
'200':
description: Successfully uploaded file
content:
application/json:
schema:
type: object
required:
- attachmentId
- file
properties:
attachmentId:
type: string
format: uuid
description: Unique identifier for the uploaded attachment
example: 550e8400-e29b-41d4-a716-446655440000
file:
type: object
required:
- name
- mimeType
- sizeInBytes
properties:
name:
type: string
description: Original filename
example: example.pdf
mimeType:
type: string
description: MIME type of the file
example: application/pdf
sizeInBytes:
type: integer
description: Size of the file in bytes
example: 1234567
example:
attachmentId: 550e8400-e29b-41d4-a716-446655440000
file:
name: example.pdf
mimeType: application/pdf
sizeInBytes: 1234567
'400':
description: Invalid upload request or file validation failed
content:
application/json:
schema:
oneOf:
- type: object
additionalProperties: false
required:
- message
- code
properties:
message:
type: string
description: The reason the file failed validation
example: >-
The file "example.pdf" is declared as a PDF but its
content does not start with the expected PDF header.
code:
type: string
enum:
- BAD_REQUEST
- type: object
additionalProperties: false
required:
- error
properties:
error:
type: string
example: No file provided
- type: object
additionalProperties: false
required:
- message
properties:
message:
type: string
example: File name or mime type not found
examples:
fileValidation:
summary: File validation failed
value:
message: >-
The file "example.pdf" is declared as a PDF but its
content does not start with the expected PDF header.
code: BAD_REQUEST
missingFile:
summary: No file provided
value:
error: No file provided
missingMetadata:
summary: File metadata missing
value:
message: File name or mime type not found
'401':
description: Invalid API key
content:
application/json:
schema:
type: object
required:
- message
properties:
message:
type: string
example: The provided API key is invalid.
example:
message: The provided API key is invalid.
'403':
description: API key does not have the required scope
content:
application/json:
schema:
type: object
required:
- message
properties:
message:
type: string
example: Insufficient API key permissions.
error:
type: string
example: INSUFFICIENT_SCOPES
details:
type: object
required:
- required
- missing
properties:
required:
type: array
items:
type: string
example: KNOWLEDGE_FOLDER_API
missing:
type: array
items:
type: string
example: KNOWLEDGE_FOLDER_API
example:
message: Insufficient API key permissions.
error: INSUFFICIENT_SCOPES
details:
required:
- KNOWLEDGE_FOLDER_API
missing:
- KNOWLEDGE_FOLDER_API
'406':
description: File type not allowed
content:
application/json:
schema:
type: object
required:
- message
properties:
message:
type: string
description: The reason the file type was blocked
example: File type not allowed. Detected executable content.
example:
message: File type not allowed. Detected executable content.
'413':
description: File exceeds the size limit
content:
application/json:
schema:
type: object
required:
- message
properties:
message:
type: string
description: The file size limit that was exceeded
example: >-
File size exceeds the limit. Max size for this file type
is 256MB
example:
message: >-
File size exceeds the limit. Max size for this file type is
256MB
'429':
description: Rate limit exceeded
content:
application/json:
schema:
type: object
required:
- message
properties:
message:
type: string
example: >-
You have exceeded the maximum number of requests per
minute (500)
example:
message: >-
You have exceeded the maximum number of requests per minute
(500)
'500':
description: Internal server error
content:
application/json:
schema:
type: object
required:
- message
properties:
message:
type: string
example: Internal server error
example:
message: Internal server error
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: API key as Bearer token. Format "Bearer YOUR_API_KEY"
````