---
title: "Files API"
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."
url: https://www.unitpost.com/docs/platform/files
section: "Platform API reference"
updated: 2026-11-11
---
# Files API

> 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))