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

<Warning>
  **The Assistants API will be deprecated on 30 April.**

  For new projects, we recommend using the [Agents API](/en/developer/agents-api/upload-attachments). The upload attachments endpoint remains the same, but you should reference it from the Agents API documentation.

  See the [migration guide](/en/developer/assistants-api/assistant-to-agent-migration) to learn about the differences.
</Warning>

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

<Info>
  To use the API you need an API key. 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 Assistant API by including it in the `attachmentIds` array either at the assistant level or message level.

## Migrating to Agents API

The upload attachment endpoint remains the same across both APIs. For new projects, reference the Agents API documentation:

* [Agent Upload Attachments API](/en/developer/agents-api/upload-attachments)

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

````