Upload Attachment API
Upload files to be used with Agents
Upload files that can be referenced in Agent conversations using their attachment IDs.
Before You Start
- API key scope: Requires an API key with the
KNOWLEDGE_FOLDER_APIscope. You can create API Keys in your Workspace settings. - Legacy Assistants API: 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.
Base URL
https://api.ajan.io/attachment/v1/uploadRequest 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
{
attachmentId: string;
file: {
name: string;
mimeType: string;
sizeInBytes: number;
}
}Example
javascript
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.ajan.io/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
try {
const response = await axios.post('https://api.ajan.io/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
{
"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:
- Per-message (recommended): Include the attachment UUID in the message's
metadata.attachmentsarray when calling the Completions API - Agent-level: Include the attachment UUID in the
attachmentsarray when creating or updating an agent
OpenAPI
openapi: 3.0.0
info:
title: ajan API
version: 3.0.0
servers:
- url: https://api.ajan.io
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"