---
title: "Upload a file"
method: POST
path: "/files"
tags: ["Files"]
---

# Upload a file

`POST /files`

## Request

- Base URL: `https://www.happyscribe.com/api/v1`
- URL: `https://www.happyscribe.com/api/v1/files`
- Auth: API key in header `Authorization`

Uploads an image to a workspace, as `multipart/form-data`, and returns a file with a
`file_` id. The key must be an owner or admin of the workspace, and the workspace's
plan must include notetaker customization. A workspace takes 60 uploads a minute.

The image is a PNG, JPEG, GIF, WebP or SVG of at most 10 MB. Its type is read from its
bytes, not from its name or declared type.

## Request body `multipart/form-data`

- FileCreate
  - `file` string, binary, required: The image, a PNG, JPEG, GIF, WebP or SVG of at most 10 MB.
  - `purpose` 'brand_kit', required: What the file is for. `brand_kit`: an image for a brand kit.
  - `workspace_id` string: The workspace the file belongs to. Optional when the key belongs to exactly one workspace, which is then used. A `wks_` id; integer workspace ids are still accepted.

## Response `201`

File uploaded.

- File
  - `id` string, required: File ID, beginning with `file_`.
  - `object` string, required: Always `file`.
  - `purpose` 'brand_kit', required: What the file is for. `brand_kit`: an image for a brand kit.
  - `workspace_id` string, required: The workspace the file belongs to, a `wks_` id.
  - `filename` string, required: The name the file was uploaded with. Its extension is replaced when it does not match the image type.
  - `content_type` 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp' | 'image/svg+xml', required: The image type, read from the file's bytes. - `image/png`: PNG. - `image/jpeg`: JPEG. - `image/gif`: GIF. - `image/webp`: WebP. - `image/svg+xml`: SVG.
  - `size` integer, required: Size in bytes.
  - `url` string, uri, required: A signed URL to download the file, valid for one year. Every read returns a fresh one. An SVG is served as a download, never inline.
  - `created_at` string, date-time, required: When the file was uploaded, in ISO 8601.

## Other responses

- `400`: The request names no workspace and the key does not belong to exactly one (`missing`, on `workspace_id`).
- `401`: Your API key is missing (`missing_api_key`) or wrong (`invalid_api_key`), or it may not access this resource (`unauthorized`).
- `403`: The key is not an owner or admin of the workspace (`workspace_update_not_allowed`), or its plan does not include notetaker customization (`plan_upgrade_required`). Nothing is uploaded.
- `404`: `workspace_id` is not a workspace the key belongs to.
- `422`: A field failed validation: `file` or `purpose` is missing (`missing`), `file` is not sent as a multipart file, is not one of the five image types or is over 10 MB (`invalid`), or `purpose` is not one of its values (`inclusion`).
- `429`: Rate limit reached (`rate_limited`). Wait `retry_in_seconds`, also sent as `Retry-After`, before retrying.

---

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