---
title: "Upload With Token"
method: PUT
path: "/v1/attachments/upload/{raw_token}"
tags: ["attachments"]
---

# Upload With Token

`PUT /v1/attachments/upload/{raw_token}`

## Request

- Base URL: `https://api.heirmos.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.heirmos.com/v1/attachments/upload/{raw_token}`
- Auth: none declared

Spend an upload token and store the raw body as an attachment.

**This route carries no Bearer header** — the token in the path is the whole
credential, and ``resolve_upload_token`` restores the owner by DB lookup, so
§14.6 tenant isolation holds for an anonymous request.

The token is consumed FIRST, before a single byte of the body is read: the
credential must be dead the moment it is presented, whatever happens next.
Everything after that is the ordinary path — magic-byte mime sniffing, the
size cap, upload-before-INSERT ordering and the background vision pass are
the same code the dashboard uses.

The limit is looser than the 20/min on the authenticated routes because
slowapi keys an anonymous request by IP, which one office NAT would share.
The real control here is the token itself: opaque, single-use, 10-minute TTL.

## Path parameters

- `raw_token` string, required

## Response `201`

Successful Response

- AttachmentUploadResult: PUT /v1/attachments/upload/{token} — deliberately narrower than ``AttachmentRead``. This response is served to an **unauthenticated** request (the token is the whole credential), so it carries only what the uploader needs to reference the image: the vision fields are all still empty at this point anyway, and are fetched later through the authenticated ``GET /v1/attachments/{id}``.
  - `id` string, uuid, required
  - `mime` string, required
  - `size_bytes` integer, required
  - `vision_status` string, required

## Other responses

- `422`: Validation Error

---

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