---
title: "Upload a file"
method: POST
path: "/api/files/"
tags: ["OpenAI Batch"]
---

# Upload a file

`POST /api/files/`

## Request

- Base URL: `https://api.respan.ai`
- URL: `https://api.respan.ai/api/files/`
- Auth: HTTP bearer

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

## Request body `multipart/form-data`

- object
  - `file` string, binary, required: File to upload.
  - `purpose` string, required: File purpose.
  - `provider_id` string, required: Provider route with customer-owned credentials, for example `openai` or `parasail`.

## Response `200`

Uploaded file.

- object
  - `id` string, required: File ID.
  - `object` string, required
  - `bytes` integer: File size in bytes.
  - `created_at` integer: Unix timestamp.
  - `filename` string
  - `purpose` string
  - `status` string: File status.
  - `status_details` unknown

## Other responses

- `400`: `provider_id` is missing, or the upload is invalid.
- `401`: You haven't added your own key for the provider in Settings › Providers, or the provider rejected it. Files and batches always run on your own key; Respan credits can't cover them.
- `403`: The API key is missing, invalid or expired.

## Changes

- **2026-10-21** `c30bcb383ee8`: 6 breaking, 8 info
  - request body became required
  - the response property `error/code` became nullable for the status `400`
  - the response property `error/code` became nullable for the status `401`
  - the response property `error/param` became nullable for the status `400`
  - …10 more
- **2026-10-02** `b830b79cfd52`: 2 breaking, 6 warning, 11 info
  - the `error` response's property type changed from `string` to `object` for status `400`
  - the `error` response's property type changed from `string` to `object` for status `401`
  - removed the optional property `detail` from the response with the `400` status
  - removed the optional property `detail` from the response with the `401` status
  - …15 more
- **2026-09-17** `6fa8242da8c2`: 1 warning, 1 info
  - deleted the `header` request parameter `Authorization`
  - the endpoint scheme security `RespanApiKey` was added to the API
- **2026-09-12** `22b868ef3f22`: 1 info
  - api operation id `upload-file` removed and replaced with `openAiBatch_uploadFile`
- **2026-08-13** `4e064cf81dae`: 11 info
  - added optional request body
  - added the non-success response with the status `400`
  - added the non-success response with the status `401`
  - added the optional property `bytes` to the response with the `200` status
  - …7 more

[Operation history](https://skmtc.dev/keywordsai/apis/respan-api/changes/api/files/post.md)

---

[API](https://skmtc.dev/keywordsai/apis/respan-api.md) - [All operations](https://skmtc.dev/keywordsai/apis/respan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keywordsai/apis/respan-api/revisions/900841387635?raw)