---
title: "Store a document once for reuse across signings"
method: POST
path: "/v1/files"
tags: ["Files"]
---

# Store a document once for reuse across signings

`POST /v1/files`

## Request

- Base URL: `https://sign-api.tvarka.pro`
- URL: `https://sign-api.tvarka.pro/v1/files`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`
  - OAuth 2 (authorization code, authorization URL `https://sign-api.tvarka.pro/oauth/authorize`, token URL `https://sign-api.tvarka.pro/oauth/token`, scopes: `sign.read`, `sign.signings`)

Returns a `fileToken` a later signing may reference instead of
carrying base64 again. Multipart accepts one binary part named file,
up to 100,000,000 bytes; JSON accepts up to 15 MiB decoded. Format
validation is identical for both transports. Office files and
images are converted to PDF/A-2b on upload (v1.9.0), so the stored
file and its `name` are the PDF.

The bytes are **copied** into each signing that uses the token, never
shared by reference: deleting a file, or letting it expire, can never
reach backwards into a signing that already used it.

## Request body

- object
  - `name` string, required
  - `content` string, byte, required

## Response `201`

The stored file.

- StoredFile
  - `fileToken` string, uuid
  - `name` string
  - `mediaType` string
  - `sha256` string
  - `bytes` integer
  - `createdAt` string, date-time
  - `expiresAt` string, date-time: An unreferenced upload is not kept forever just because nobody deleted it. Re-upload after this, or post the bytes inline.
  - `usedCount` integer: How many signings have copied these bytes.

## Other responses

- `400`: An RFC 9457 problem document.
- `401`: An RFC 9457 problem document.
- `402`: An RFC 9457 problem document.
- `403`: An RFC 9457 problem document.
- `413`: An RFC 9457 problem document.
- `429`: An RFC 9457 problem document.
- `503`: An RFC 9457 problem document.

---

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