Upload Attachment API
Agent'larla kullanılacak dosyaları yükleyin
Agent konuşmalarında attachment ID'leriyle referans verilebilecek dosyaları yükler.
Başlamadan önce
- API key scope:
KNOWLEDGE_FOLDER_APIkapsamına sahip bir API anahtarı gerekir. API Key'leri Workspace settings içinde oluşturabilirsiniz. - Legacy Assistants API: Bu, yerel Vercel AI SDK uyumluluğuna sahip yeni Agents API'dir. Upload attachment endpoint'i her iki API arasında paylaşılır. Eski Assistants API kullanıyorsanız migration guide sayfasına bakın.
Base URL
https://api.ajan.io/attachment/v1/uploadDedicated deployments Tüm isteklerde
api.ajan.com'u/api/publicile değiştirin.
Request Format
Bu endpoint tek dosya yüklemeli multipart/form-data isteklerini kabul eder.
| Parameter | Type | Required | Description |
|---|---|---|---|
file | File | Yes | Yüklemek istediğiniz dosya |
Response Format
API, yüklenen dosya bilgilerini döndürür:
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 | Geçersiz istek veya dosya doğrulama hatası | message, veya dosya yoksa error |
401 | Geçersiz veya eksik API anahtarı | message |
403 | API anahtarında gerekli kapsam yok | message |
406 | Engellenen dosya türü | message |
413 | Dosya boyut limitini aşıyor | message |
429 | Rate limit aşıldı | message |
500 | Beklenmeyen sunucu hatası | message |
Dosya içerik doğrulama hatası şu yanıtı döndürür:
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
Yüklenen attachment ID, Agent API'de iki şekilde kullanılabilir:
- Per-message (önerilen): Completions API çağrılırken mesajın
metadata.attachmentsdizisine attachment UUID'sini ekleyin - Agent-level: Agent oluştururken veya güncellerken
attachmentsdizisine attachment UUID'sini ekleyin
ajan, API anahtarınızı korumak ve uygulamalarınızın güvenliğini sağlamak için tarayıcı kaynaklı istekleri bilinçli olarak engeller. Daha fazla bilgi için API Key Best Practices kılavuzuna bakın.
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"