---
title: "Upload a file (deprecated)"
method: POST
path: "/v1/files/"
tags: ["Files"]
deprecated: true
---

# Upload a file (deprecated)

`POST /v1/files/`

> **Deprecated.**

**Deprecated** — use the v2 upload endpoints for new integrations: `POST /v2/files/upload` for files up to 5 GB and `POST /v2/files/large-upload` for files up to 10 GB. This endpoint is capped at 100 MB.

Existing callers keep working. Each response carries a `Deprecation: true` header and a `Link` header pointing at the successor. A sunset date will be announced once v2 adoption is broad.

---

Upload a file for embedding in docs, data entries, or insights. The request must use `multipart/form-data` encoding with a single `file` field containing the file data.

After uploading, use the returned file ID to reference the file in document content (e.g. as a cover image via `cover_image_file_id` on the **Create doc** or **Patch doc** endpoints).

**Limits:** Maximum file size is 100 MB. Orphaned files that are not embedded in any document within 24 hours are automatically cleaned up.

Returns the file metadata including its processing status.

## Response `201`

201

- object
  - `data` object, required
    - `id` string, required — Unique identifier of the file.
    - `name` string, required — The file's original name.
    - `type` string, nullable, required — The file's MIME type (e.g. 'image/png', 'video/mp4'). Null if unknown.
    - `size` number, nullable, required — Size of the file in bytes. Null if unknown.
    - `status` 'completed' | 'pending' | 'failed', required — Processing status of the file. 'pending' while being processed, 'completed' when ready, or 'failed' if processing encountered an error.
    - `author` union, required — The user who uploaded the file, or null if the author is unknown.
      - object
        - `id` string, required
        - `name` string
      - string, null, nullable
    - `created_at` union, required — ISO 8601 timestamp when the file was created.
      - string
      - string, null, nullable
    - `url` string, nullable, required — Permanent URL pointing at the **Download a file** endpoint. Safe to cache and store — the URL itself never expires, but calling it requires the same authentication as other API endpoints and returns a short-lived presigned URL each time. The endpoint performs its own readiness and access checks.

## Other responses

- `400` — 400
- `401` — 401
- `403` — 403
- `404` — 404
- `422` — 422
- `429` — 429
- `500` — 500

---

[API](https://skmtc.net/dovetail/apis/dovetail-public-api.md) · [All operations](https://skmtc.net/dovetail/apis/dovetail-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/dovetail/dovetail-public-api/versions/4107f5fdf8b2/schema)