> ## 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

<Info>
  **⚠️ Using our API via a dedicated deployment?** Just replace `api.langdock.com` with your deployment's base URL: **`<deployment-url>/api/public`**
</Info>

<Info>
  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).
</Info>

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

<Info>
  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).
</Info>

## 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) {
    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](/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

<Info>
  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).
</Info>


## OpenAPI

````yaml POST /attachment/v1/upload
openapi: 3.0.0
info:
  title: Langdock API
  version: 3.0.0
servers:
  - url: https://api.langdock.com
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
                  file:
                    type: object
                    required:
                      - name
                      - mimeType
                      - sizeInBytes
                    properties:
                      name:
                        type: string
                        description: Original filename
                      mimeType:
                        type: string
                        description: MIME type of the file
                      sizeInBytes:
                        type: integer
                        description: Size of the file in bytes
        '400':
          description: No file provided
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"

````