---
title: "Mint a single-use upload token"
method: POST
path: "/upload-tokens"
tags: ["Documents"]
---

# Mint a single-use upload token

`POST /upload-tokens`

## Request

- Base URL: `https://api.bankstatemently.com/v1`
- URL: `https://api.bankstatemently.com/v1/upload-tokens`
- Auth: API key in header `X-API-Key`

Mints a single-use, expiring upload token for hosts with no direct byte-upload equivalent (e.g. an agent sandbox with outbound-only network access). PUT the PDF to the returned upload_url, then POST /v1/documents with `{ "upload_id": "..." }` to convert it by reference. Tokens expire after ~2 hours and are single-use — PUTting a second file overwrites the first, but converting consumes the token. No credit is deducted on mint; credits are charged only at conversion. Rate limit: 20 requests per minute.

## Response `201`

Upload token minted.

- object
  - `upload_id` string, required: Pass this to POST /v1/documents as { "upload_id": ... } to convert the uploaded file.
  - `upload_url` string, uri, required: PUT the raw PDF bytes here, with Content-Type: application/pdf.
  - `expires_at` string, date-time, required: When this token expires (~2 hours from mint).
  - `max_bytes` integer, required: Maximum PDF size in bytes this token accepts, derived from the caller's plan.

## Other responses

- `401`: Authentication failed, API key revoked, or API key expired.
- `429`: Too many requests. Wait the number of seconds indicated by the `Retry-After` header.
- `500`: An unexpected server error occurred.

---

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