File Upload API

The File Upload API provides a comprehensive solution for managing file uploads with secure pre-signed URLs for direct S3 uploads, file status tracking, organization by parent entities, and public/private file access control.

Generate Upload URL

GET /generate-upload-url

This endpoint creates file records and generates pre-signed URLs for uploading directly to S3.

curl https://management-api.useproteus.ai/api/generate-upload-url \
-X GET \
-H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
-H "Content-Type: application/json" \
-d '{
        "files": [
            {
                "fileName": "example.pdf",
                "contentType": "application/pdf",
                "fileSize": 1024000,
                "isPublic": false
            }
        ],
        "folder": "documents/users",
        "parentId": "6501db8bb89d5189b64acf79",
        "parentType": "KNOWLEDGE"
    }'

The request allows for 1-10 files per request. Each file object requires:

fileName: String (required, max 255 chars, no special characters)
contentType: String (optional)
fileSize: Number (optional, max 100MB)
isPublic: Boolean (default: false)

Additional parameters:

folder: String (optional, max 100 chars)
parentId: String (must be provided with parentType)
parentType: Enum (one of: "ORG", "CHARACTER", "KNOWLEDGE", "AGENT")

Update File Status

PATCH /status

This endpoint updates the status of a file after upload completion or failure.

curl https://management-api.useproteus.ai/api/status \
-X PATCH \
-H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
-H "Content-Type: application/json" \
-d '{
        "fileId": "64a82f3b1234567890abcdef",
        "status": "UPLOADED"
    }'

Required parameters:

fileId: String (required)
status: Enum (required, one of: "UPLOADED", "FAILED", "PROCESSING", "COMPLETED")
errorMessage: String (optional, required if status is "FAILED")

Get Files By Parent

GET /

This endpoint gets all files associated with a specific parent entity.

curl "https://management-api.useproteus.ai/api/?parentId=64a82f3b1234567890abcdef&parentType=ORG" \
-H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

Query parameters:

parentId: String (optional)
parentType: Enum (optional, one of: "ORG", "CHARACTER", "KNOWLEDGE", "AGENT")

Get File Access URL

GET /access/:fileId

This endpoint generates a URL for accessing a file. It returns a signed URL for private files or a direct URL for public files.

curl "https://management-api.useproteus.ai/api/access/64a82f3b1234567890abcdef?expiresIn=7200" \
-H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

curl "https://management-api.useproteus.ai/api/access/64a82f4b1234567890abcdee" \
-H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

Path parameters:

fileId: String (required)

Query parameters:

expiresIn: Number (optional, default: 3600 seconds)

Complete Upload Flow Example

const response = await fetch('/generate-upload-url', {
    method: 'GET',
    headers: {
        'Content-Type': 'application/json'
     },
    body: JSON.stringify({
        files: [
            {
                fileName: 'document.pdf',
                contentType: 'application/pdf',
                fileSize: 2048000,
                isPublic: false
            }
        ],
        folder: 'organization-documents',
        parentId: '64a82f3b1234567890abcdef',
        parentType: 'ORG'
    })
 });
 
const result = await response.json();
const fileInfo = result.data.files[0];
const { signedUrl, fileRecord } = fileInfo;

Error Handling

⚠️

The API returns standardized error responses with appropriate status codes.

{
  "ok": false,
  "error": {
    "message": "Error message description",
    "error": "ERROR_TYPE"
  }
}

Common error types:

SERVER_ERROR: General server errors
NOT_FOUND: Resource not found
Validation errors from Zod validation

Tokens Orgs