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

> Dateien hochladen, die mit Agents verwendet werden können

<Info>
  **⚠️ Du nutzt unsere API in einem Dedicated Deployment?** Ersetze einfach `api.langdock.com` durch die Base URL deines Deployments: **`<deployment-url>/api/public`**
</Info>

<Info>
  Dies ist die neue Agents API mit nativer Vercel AI SDK Kompatibilität. Der Upload-Attachment-Endpunkt wird von beiden APIs gemeinsam genutzt. Wenn du die veraltete Assistants API verwendest, siehe den [Migrations-Guide](/de/developer/assistants-api/assistant-to-agent-migration).
</Info>

Lade Dateien hoch, auf die in Agent-Konversationen über ihre Anhangs-IDs verwiesen werden kann.

<Info>
  Erfordert einen API-Schlüssel mit dem `KNOWLEDGE_FOLDER_API` Scope. Du kannst API-Schlüssel in deinen [Workspace
  Einstellungen](https://app.langdock.com/settings/workspace/products/api) erstellen.
</Info>

## Anforderungsformat

Dieser Endpunkt akzeptiert `multipart/form-data` Anfragen mit einem einzelnen Datei-Upload.

| Parameter | Typ   | Erforderlich | Beschreibung                         |
| --------- | ----- | ------------ | ------------------------------------ |
| `file`    | Datei | Ja           | Die Datei, die du hochladen möchtest |

## Antwortformat

Die API gibt die Informationen zur hochgeladenen Datei zurück:

```typescript theme={null}
{
  attachmentId: string;
  file: {
    name: string;
    mimeType: string;
    sizeInBytes: number;
  }
}
```

## Beispiel

```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
  //   }
  // }
}
```

## Fehlerbehandlung

```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('Keine Datei angegeben');
        break;
      case 401:
        console.error('Ungültiger API-Schlüssel');
        break;
      case 500:
        console.error('Server-Fehler');
        break;
    }
  }
}
```

Die hochgeladene Anhangs-ID kann in der Agent-API auf zwei Arten verwendet werden:

1. **Pro Nachricht** (empfohlen): Füge die Anhangs-UUID in das `metadata.attachments` Array der Nachricht ein, wenn du die [Completions API](/de/developer/agents-api/agent) aufrufst
2. **Auf Agent-Ebene**: Füge die Anhangs-UUID in das `attachments` Array ein, wenn du einen Agenten [erstellst](/de/developer/agents-api/agent-create) oder [aktualisierst](/de/developer/agents-api/agent-update)

<Info>
  Langdock blockiert bewusst Browser-basierte Anfragen, um deinen API-Schlüssel zu schützen und die Sicherheit deiner Anwendungen zu gewährleisten. Weitere Informationen findest du in unserem Guide zu [Best Practices für API-Schlüssel](/de/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
    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
                  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"

````