Upload a file

POST

https://api.respan.ai/api/files/

Upload a file to the upstream OpenAI Files API. Batch jobs use JSONL files with purpose=batch.

Authentication

AuthorizationBearer

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

Request

This endpoint expects a multipart form containing a file.

filefileRequired

File to upload.

purposestringRequired

File purpose.

provider_idstringRequired

Provider route with customer-owned credentials, for example openai or parasail.

Response

Uploaded file.

idstring

File ID.

objectstring

bytesintegerOptional

File size in bytes.

created_atintegerOptional

Unix timestamp.

filenamestringOptional

purposestringOptional

statusstringOptional

File status.

status_detailsany or nullOptional

Provider status details, when available.

Errors

400

Bad Request Error

401

Unauthorized Error

$	curl --request POST 'https://api.respan.ai/api/files/' \
>	--header 'Authorization: Bearer YOUR_RESPAN_API_KEY' \
>	--form 'file=@batch_input.jsonl' \
>	--form 'purpose=batch' \
>	--form 'provider_id=openai'

1	{
2	"id": "file-abc123",
3	"object": "file",
4	"bytes": 12345,
5	"created_at": 1710000000,
6	"filename": "batch_input.jsonl",
7	"purpose": "batch",
8	"status": "processed",
9	"status_details": null
10	}