---
title: "Create upload URL"
method: POST
path: "/v1/files/uploads"
tags: ["narrador files"]
---

# Create upload URL

`POST /v1/files/uploads`

## Request

- Base URL: `https://api.narrador.io`
- URL: `https://api.narrador.io/v1/files/uploads`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Creates a storage file record and returns a signed URL to `PUT` the document bytes. Requires a `nrd_files_` key.

## Request body

- object
  - `fileName` string, required
  - `fileSizeBytes` integer, required: Size of the file you will PUT to the signed URL, in bytes (max 50 MB).

## Response `201`

Upload URL created

- FilesUploadUrl
  - `signedUrl` string, uri
  - `token` string
  - `path` string
  - `fileId` string, uuid

## Other responses

- `400`: Missing `fileName` or `fileSizeBytes`, file too large, or invalid JSON.
- `401`: Unauthorized — missing or invalid API key (wrong prefix, revoked, or expired).
- `403`: Forbidden — API key scope does not match the endpoint (e.g. `nrd_x_` key on a narrador files route), insufficient narrador credits for a synchronous operation (e.g. narrador X generate), or other entitlement failure. narrador files jobs that run out of credits finish asynchronously with job status `not-enough-credits` instead of HTTP 403.
- `413`: JSON request body larger than **2mb** (Express body-parser limit on `/v1/files`). Response is the default HTML error page (`PayloadTooLargeError: request entity too large`), not `{ "error": "…" }`. Multipart `POST /v1/files/generate` uses separate file-size limits.
- `429`: Too many requests — API key verification rate limit exceeded (60 requests per 60 seconds per key).

---

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