Files

Overview

The Files API lets you upload files that can be referenced by chat-completion requests, batch jobs, agents, and sessions. Files are stored in the gateway database with a purpose and a detected content type. Retrieval returns the file metadata plus the base64-encoded bytes.

Base URL

https://api.allternit.com/v1

For local development:

http://127.0.0.1:8013/v1

Endpoints

Method	Path	Description
`POST`	`/v1/files`	Upload a base64-encoded file
`GET`	`/v1/files`	List files
`GET`	`/v1/files/:id`	Retrieve a file and its content
`DELETE`	`/v1/files/:id`	Delete a file

Upload a file

Uploads use a JSON body with a base64-encoded file field so clients can upload binary content without a multipart dependency.

Request body

Field	Type	Required	Description
`file`	string	yes	Base64-encoded file bytes.
`filename`	string	no	File name. Defaults to `upload.pdf`.
`purpose`	string	no	Purpose tag. Defaults to `assistants`.

Valid purposes

Purpose	Description
`fine-tune`	Training data for fine-tuning jobs.
`assistants`	Files attached to assistant runs.
`assistants_output`	Output files from assistant runs.
`batch`	Input files for batch inference.
`batch_output`	Output files from batch jobs.
`embeddings`	Files used to generate embeddings.
`vision`	Image or video inputs for vision models.
`user_data`	General user-provided data.

Example request

curl -X POST https://api.allternit.com/v1/files \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file": "JVBERi0xLjQK...",
    "filename": "report.pdf",
    "purpose": "assistants"
  }'

Example response

{
  "id": "file_abc123",
  "object": "file",
  "bytes": 1024,
  "created_at": 1723500000,
  "filename": "report.pdf",
  "purpose": "assistants",
  "status": "processed",
  "content_type": "application/pdf"
}

List files

curl https://api.allternit.com/v1/files \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "file_abc123",
      "object": "file",
      "bytes": 1024,
      "created_at": 1723500000,
      "filename": "report.pdf",
      "purpose": "assistants",
      "status": "processed",
      "content_type": "application/pdf"
    }
  ]
}

Retrieve a file

curl https://api.allternit.com/v1/files/file_abc123 \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY"

The response includes the base64-encoded file content in the data field.

{
  "id": "file_abc123",
  "object": "file",
  "bytes": 1024,
  "created_at": 1723500000,
  "filename": "report.pdf",
  "purpose": "assistants",
  "status": "processed",
  "content_type": "application/pdf",
  "data": "JVBERi0xLjQK..."
}

Delete a file

curl -X DELETE https://api.allternit.com/v1/files/file_abc123 \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY"

{
  "id": "file_abc123",
  "object": "file",
  "deleted": true
}

Content types

The gateway detects the MIME type from the filename extension:

Extension	Content type
`.pdf`	`application/pdf`
`.json`, `.jsonl`	`application/json`
`.txt`, `.log`	`text/plain`
`.csv`	`text/csv`
`.png`	`image/png`
`.jpg`, `.jpeg`	`image/jpeg`
`.gif`	`image/gif`
`.webp`	`image/webp`
`.svg`	`image/svg+xml`
`.mp3`	`audio/mpeg`
`.wav`	`audio/wav`
`.mp4`	`video/mp4`
`.zip`	`application/zip`
other	`application/octet-stream`

Using files in completions

Reference an uploaded file by id in a chat-completion message part:

{
  "model": "auto",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Summarize this document."},
        {"type": "file_id", "file_id": "file_abc123"}
      ]
    }
  ]
}

The gateway resolves file_id references to inline data before forwarding the request to the runtime.

Error codes

HTTP status	Code	Meaning
400	`allternit.invalid_request`	Invalid base64, empty file, or invalid `purpose`.
401	`allternit.authentication_failed`	Missing or invalid API key.
404	`allternit.invalid_request`	File not found.
429	`allternit.rate_limited`	Per-key rate limit exceeded.
429	`allternit.budget_exceeded`	Monthly key or tenant budget exhausted.
500	`allternit.internal_error`	Internal gateway error.

Chat Completions — reference files in messages
Batches — use files as batch inputs
Embeddings — embed text from files

Overview

LLM Gateway

Agents & Runtime

Work Queue & Deployments

Files, Webhooks & Sandbox

Tools & Connectors

Collaboration & Workflows

Infrastructure & Platform

Canvases

Onboarding

A Labs

Playground

Users & Profiles

Overview

Base URL

Endpoints

Upload a file

Request body

Valid purposes

Example request

Example response

List files

Retrieve a file

Delete a file

Content types

Using files in completions

Error codes

​Overview

​Base URL

​Endpoints

​Upload a file

​Request body

​Valid purposes

​Example request

​Example response

​List files

​Retrieve a file

​Delete a file

​Content types

​Using files in completions

​Error codes

​Related pages

Overview

Base URL

Endpoints

Upload a file

Request body

Valid purposes

Example request

Example response

List files

Retrieve a file

Delete a file

Content types

Using files in completions

Error codes

Related pages