---
title: "Upload a file"
method: POST
path: "/v1/files"
tags: ["files"]
---

# Upload a file

`POST /v1/files`

## Request

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

Create a file for a run's input and get a one-time upload URL.

- PUT the bytes to upload_url, then pass the file's ID as the file field's value in a run's input.
- A file can be at most 25 MiB unless the deployment sets otherwise. Executables are refused, and the first bytes must match media_type.
- A file serves one run. It is erased when that run's job ends, or after an hour if unused.
- A run's file field also takes an https URL, or a data: URI of at most 512 KB.

## Request body

- object
  - `name` string, required: The file's name, as the website will see it, for example receipt.pdf
  - `media_type` string, required: The file's media type, such as application/pdf; its first bytes must match it
  - `size` integer: an integer

## Response `201`

The new file, awaiting its upload

- FileUpload
  - `id` string, required: a file ID: file_ and 32 lowercase hex digits
  - `name` string, required: The file's name, as given
  - `media_type` string, required: The file's media type, as checked
  - `size` number, nullable, required: Bytes: the declared size until the upload arrives, then the size received; null when none was declared
  - `sha256` string, nullable, required: The SHA-256 of the bytes, lowercase hex, once they arrived
  - `status` 'awaiting_upload' | 'ready' | 'in_use', required: awaiting_upload until its bytes arrive at upload_url, ready to pass to a run, in_use once a run took it
  - `direction` 'input' | 'output', required: input for a file sent to a run, output for one a run collected
  - `job_id` string, required: a job ID: job_ and 32 lowercase hex digits
  - `created_at` string, required: a string to be decoded into a Date
  - `expires_at` string, required: a string to be decoded into a Date
  - `upload_url` string, required: PUT the file's bytes here once, with Content-Type and Content-Length and no Authorization header. Valid until expires_at.

## Other responses

- `400`: invalid_request
- `401`: sign_in_required, unauthorized, reauthentication_required
- `403`: forbidden
- `413`: file_too_large, request_too_large
- `415`: file_type_refused
- `500`: internal_error
- `501`: not_configured
- `503`: temporarily_unavailable

---

[API](https://skmtc.dev/pomerado/apis/pomerado-api.md) · [All operations](https://skmtc.dev/pomerado/apis/pomerado-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pomerado/apis/pomerado-api/revisions/48dac2a3143e?raw)