Upload Attachment API

Upload files to be used with Assistants

The Assistants API will be deprecated on 30 April.

For new projects, we recommend using the Agents API. The upload attachments endpoint remains the same, but you should reference it from the Agents API documentation.

See the migration guide to learn about the differences.

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

To use the API you need an API key. You can create API Keys in your Workspace settings.

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:

{
  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.odeus.ai/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.odeus.ai/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

Odeus 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.

OpenAPI

openapi: 3.0.0
info:
  title: Odeus API
  version: 3.0.0
servers:
  - url: https://api.odeus.ai
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"