---
title: "Files"
description: "Hand the API a file for one purpose, then use it by `file_id`: SMS opt-in evidence and company documents, images for templates and branding. From a URL, as base64, or with an upload session (a presigned PUT) for a local file an agent can't put in a request. Checked by their bytes, private, kept 24 hours."
url: https://www.unitpost.com/docs/api/files
section: API reference
updated: 2026-11-11
---
# Files

## Files

> Hand the API a file for one purpose, then use it by `file_id`: SMS opt-in evidence and company documents, images for templates and branding. From a URL, as base64, or with an upload session (a presigned PUT) for a local file an agent can't put in a request. Checked by their bytes, private, kept 24 hours.

Full schemas: [OpenAPI 3.1](https://www.unitpost.com/api/v1/openapi.json). HTML reference: https://www.unitpost.com/docs/platform/files.

## Operations

### `GET /api/v1/files`

List files

The workspace's unexpired files, newest first, of the purposes this credential may use (`sms:manage`: the SMS purposes; `templates:write` or `branding:write`: `image`). `purpose` narrows it. Requires the `sms:manage` or `templates:write` or `branding:write` capability.

Reference: https://www.unitpost.com/docs/platform/get-files ([Markdown](https://www.unitpost.com/docs/platform/get-files.md))

### `POST /api/v1/files`

Create a file

Hand the API a file for one `purpose`, then pass its id as `file_id` (or the field an operation names) to what uses it: a brand document, a toll-free number's opt-in evidence, a 10DLC campaign's screenshot, a library image, the logo. Three ways in, one per call: a public https `url` (fetched once, no redirects, no private addresses); base64 `data` with `content_type` (small files: a request over ~6 MB is refused); or an upload session, for a local file: send `content_type` and `size_bytes` without `url` or `data`, then PUT the bytes to `upload.url` with `upload.headers` within 15 minutes (`curl -T file -H "Content-Type: image/png" "<upload.url>"`). The bytes are checked by their contents against the purpose (`sms_opt_in_evidence`: PNG up to 400 KB; `sms_document`: PDF, PNG or JPEG up to 3 MB; `image`: PNG, JPEG, GIF or WebP up to 5 MB), never by the label. Files are private, never served back, and expire 24 hours after they're made: what uses one keeps its own copy. Send an `Idempotency-Key` so a retry makes one file. Requires the `sms:manage` or `templates:write` or `branding:write` capability.

Reference: https://www.unitpost.com/docs/platform/post-files ([Markdown](https://www.unitpost.com/docs/platform/post-files.md))

### `GET /api/v1/files/{id}`

Retrieve a file

One file's metadata (the bytes are never served back). For an upload session this checks whether the bytes arrived and pass the purpose's checks: `ready`, `failed` (`failure_reason`), or still `awaiting_upload`. Requires the `sms:manage` or `templates:write` or `branding:write` capability.

Reference: https://www.unitpost.com/docs/platform/get-files-id ([Markdown](https://www.unitpost.com/docs/platform/get-files-id.md))

### `DELETE /api/v1/files/{id}`

Delete a file

Delete a file and its bytes before its 24 hours are up. What already used it keeps its copy. Requires the `sms:manage` or `templates:write` or `branding:write` capability.

Reference: https://www.unitpost.com/docs/platform/delete-files-id ([Markdown](https://www.unitpost.com/docs/platform/delete-files-id.md))

## Related

- [Branding](https://www.unitpost.com/docs/api/branding): The look marketing emails' footer and the hosted unsubscribe page share, with the same options as Settings → Brand, and the logo. Writes need `branding:write`, which no key preset includes.
- [Workspace](https://www.unitpost.com/docs/api/workspace): The workspace's name and image (writes need `branding:write`), who is calling (`GET /whoami`, any credential), and the activity log (`GET /activity`, `activity:read`: no key preset includes it).
- [Segments](https://www.unitpost.com/docs/api/segments): Named groups of contacts used to target campaigns. Segments decide who a campaign goes to; topics (below) decide what recipients can opt out of.