---
title: "Reserve an upload"
method: POST
path: "/v1/files"
tags: ["files"]
---

# Reserve an upload

`POST /v1/files`

## Request

- Base URL: `https://api.niubai.vip` (the document declares no server; this is the origin it was published from)
- URL: `https://api.niubai.vip/v1/files`
- Auth: HTTP bearer

For documents you would rather not send inline: returns a `file_id` and a presigned `upload_url`. `PUT` the bytes there with the given `headers`, then pass `source.file_id` to `/v1/edit`. Uploads expire with the retention window.

## Response `200`

Successful Response

- FileCreateOut
  - `file_id` string, required: Pass as `source.file_id` once the bytes are uploaded.
  - `upload_url` string, required: PUT the document here.
  - `headers` object: Headers the PUT must carry.
  - `expires_at` string, nullable: ISO 8601; the upload slot and the file expire then.

## Other responses

- `401`: error.code is one of: unauthorized
- `429`: error.code is one of: rate_limited

---

[API](https://skmtc.dev/niubai/apis/pdf-edit-api-gateway.md) · [All operations](https://skmtc.dev/niubai/apis/pdf-edit-api-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/niubai/apis/pdf-edit-api-gateway/revisions/1ad0ce16ca04?raw)