---
title: "List files"
description: "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). `GET /api/v1/files`"
url: https://www.unitpost.com/docs/platform/get-files
section: "Platform API reference"
updated: 2026-11-11
---
# List files

`GET /api/v1/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.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Max rows to return (default 20, max 100). |
| `after` | query | string | no | Return rows after this id (forward paging). |
| `before` | query | string | no | Return rows before this id (backward paging). |
| `purpose` | query | string | no | Only files of this purpose. One of: `sms_opt_in_evidence`, `sms_document`, `image`. |

## Response fields (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | — |
| `id` | string | yes | — |
| `purpose` | enum | yes | What the file is for: `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). One of: `sms_opt_in_evidence`, `sms_document`, `image`. |
| `status` | enum | yes | `ready`: checked and usable by `file_id`. `awaiting_upload`: an upload session whose bytes haven't been PUT yet (reading the file checks again). `failed`: the uploaded bytes were refused (`failure_reason` says why). One of: `awaiting_upload`, `ready`, `failed`. |
| `filename` | string | yes | — |
| `content_type` | string | yes | The type the file's bytes carry (checked by their contents), or, before an upload session's bytes arrive, the type declared. |
| `size_bytes` | integer | yes | — |
| `sha256` | string \| null | yes | The hex SHA-256 of the bytes once `ready`. |
| `failure_reason` | string \| null | yes | — |
| `upload` | object \| null | yes | An upload session's PUT, in the create response only (null otherwise). |
| `created_at` | string | yes | — |
| `expires_at` | string | yes | The file is deleted at this time, 24 hours after it was created, whether or not it was used. An operation that used it keeps its own copy. |

## Responses

| Status | Description |
| --- | --- |
| 200 | A page of files. |
| 401 | Missing or invalid API key. |
| 403 | Insufficient scope (none of the purposes' capabilities, or not the one for `purpose`). |
| 422 | A bad `purpose` or pagination param, or an unknown query key. |

## Example request

```bash
curl -X GET 'https://www.unitpost.com/api/v1/files' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
```

## Example response (200)

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "file",
      "id": "id_123",
      "purpose": "sms_opt_in_evidence",
      "status": "awaiting_upload",
      "filename": "string",
      "content_type": "string",
      "size_bytes": 1,
      "sha256": "string",
      "failure_reason": "string",
      "upload": {
        "url": "https://example.com",
        "method": "PUT",
        "headers": {},
        "expires_at": "2026-01-01T00:00:00.000Z"
      },
      "created_at": "2026-01-01T00:00:00.000Z",
      "expires_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}
```

## Links

- HTML reference (with Node.js, Python, Ruby, PHP, Laravel, Go, Java, Rust, .NET and CLI examples): https://www.unitpost.com/docs/platform/get-files
- OpenAPI 3.1 (full schemas): https://www.unitpost.com/api/v1/openapi.json