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

# Create a file

`POST /files`

## Request

- Base URL: `https://api.ando.so/v1`
- URL: `https://api.ando.so/v1/files`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Creates a file upload intent for a message attachment. The response returns temporary direct storage upload instructions; send the bytes to that URL, then complete the file before using its id in create-message file_ids. Replay the same request with the same Idempotency-Key and body to refresh an active upload URL.

## Headers

- `Idempotency-Key` string, required: Idempotency key.

## Request body

- CreatePublicFileBody: Create a public file upload intent. The response returns a storage upload URL; send the file bytes to that URL, then complete the upload before attaching the returned file id to a message.
  - `client_upload_id` string, nullable: Optional caller-generated identifier for correlating this file with the integration's local upload.
  - `content_type` string, required: Declared MIME content type.
  - `filename` string, required: Original filename.
  - `purpose` 'message_attachment': File purpose.
  - `sha256` string, nullable: Optional lowercase hex-encoded SHA-256 digest of the file bytes. SHA-256 verification is supported only when size_bytes is less than or equal to 67108864.
  - `size_bytes` integer, required: Declared file size in bytes.

## Response `200`

Existing file upload intent for a matching idempotency key.

- PublicFileResponse: Public file response envelope.
  - `data` PublicFileResult, required: Public file lifecycle state. Ready readable files include short-lived download instructions and can be attached to message creation with file_ids.
    - `content_type` string, required: Declared MIME content type.
    - `created_at` string, date-time, required: File upload intent creation timestamp.
    - `file_id` string, required: File identifier. Matches id for message file_ids.
    - `filename` string, required: Original filename.
    - `id` string, required: File identifier.
    - `object` 'file', required: Object type.
    - `purpose` 'message_attachment', required: File purpose.
    - `size_bytes` integer, required: File size in bytes.
    - `status` 'waiting_for_upload' | 'uploaded' | 'processing' | 'ready' | 'aborted' | 'expired' | 'failed', required: File lifecycle status.
    - `updated_at` string, date-time, required: Last file lifecycle update timestamp.
    - `upload` PublicFileUploadInstructions, required: Temporary storage upload instructions.
      - `expires_at` string, date-time, required: Upload URL expiration timestamp.
      - `headers` object, required: Headers that must be sent exactly with the direct storage upload.
      - `kind` 'single_part_presigned_put', required: Upload strategy.
      - `method` 'PUT', required: Upload HTTP method.
      - `url` string, uri, required: Temporary direct upload URL.
    - `download` PublicFileDownloadInstructions: Temporary storage download instructions.
      - `expires_at` string, date-time, nullable, required: Download URL expiration timestamp.
      - `method` 'GET', required: Download HTTP method.
      - `url` string, uri, required: Temporary direct download URL.
  - `file_id` string, required: File identifier. Matches data.id.

## Other responses

- `201`: Created file upload intent.
- `400`: Bad request.
- `401`: Missing or invalid API key.
- `403`: Forbidden.
- `404`: Not found.
- `409`: Conflict.
- `429`: Rate limit or quota exceeded.
- `500`: Internal server error.

## Changes

- **2026-10-18** `aaceae49c08d`: 12 info
  - added the optional property `request_id` to the response with the `400` status
  - added the optional property `request_id` to the response with the `401` status
  - added the optional property `request_id` to the response with the `403` status
  - added the optional property `request_id` to the response with the `404` status
  - …8 more
- **2026-09-06** `a9b29e0cf8fd`: 2 info
  - added the optional property `data/download` to the response with the `200` status
  - added the optional property `data/download` to the response with the `201` status
- **2026-09-04** `2da0b5c6e637`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ando/apis/ando-public-api/changes/files/post.md)

---

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