---
title: "Upload a file"
method: POST
path: "/api/v1/files"
---

# Upload a file

`POST /api/v1/files`

Creates a new file from base64-encoded content and returns the resulting file object,
including a signed download URL. Use this endpoint to store images, documents, or
other binary assets that can then be referenced by agents, teams, or users.

App scope is derived from the authenticated viewer's bearer token or publishable key.
You may optionally associate the file with an organization, team, user, or agent by
passing the corresponding ID. If no owner is specified and the viewer is a user, the
file is automatically attributed to that user.

Returns `422` when the `data` field is not valid base64 or the changeset is invalid.
Returns `403` when the request lacks the required app scope.

## Request body

- object
  - `agent` string — Agent ID (`agi_...`) to associate with this file. When provided, the file's organization is derived from the agent.
  - `content_type` string, required — MIME type of the file, e.g. `"image/png"` or `"application/pdf"`.
  - `data` string, required — Base64-encoded binary content of the file to upload.
  - `filename` string, required — Original filename including extension, e.g. `"avatar.png"`.
  - `org` string — Organization ID (`org_...`) to associate with this file. Optional; defaults to the viewer's organization when omitted.
  - `team` string — Team ID (`tem_...`) that owns this file. Takes precedence over `user` when both are provided.
  - `user` string — User ID (`usr_...`) that owns this file. Defaults to the authenticated user when neither `user` nor `team` is specified.

## Response `201`

Successful response

- StorageFile — A file stored in the platform's object storage, with metadata and a signed URL for downloading its contents.
  - `content_type` string — MIME type of the file, e.g. `"image/png"` or `"application/pdf"`.
  - `created_at` string, date-time — When the file was uploaded (ISO 8601).
  - `filename` string — Original filename as provided at upload time.
  - `id` string, required — File ID (`fil_...`).
  - `image_source` ImageSource — Resolved metadata for an image, including its delivery URL, dimensions, and optional references to the underlying storage file or media record.
    - `file` string — ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.
    - `height` integer — Height of the image in pixels. `null` if not known.
    - `media` string — ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.
    - `mime_type` string — MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.
    - `refresh_url` string — Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.
    - `url` string — Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.
    - `width` integer — Width of the image in pixels. `null` if not known.
  - `org` string — ID of the organization that owns this file (`org_...`).
  - `sandbox` string — ID of the sandbox this file is scoped to (`sbx_...`). `null` for files not associated with a sandbox.
  - `size` integer — Size of the file in bytes.
  - `updated_at` string, date-time — When the file record was last modified (ISO 8601).
  - `url` string — Short-lived signed URL for downloading the file. `null` if a URL could not be generated.

## Other responses

- `401` — Unauthorized
- `403` — Forbidden - app scope required
- `422` — Validation failed or invalid base64

---

[API](https://skmtc.net/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.net/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/versions/a8772b442f86/schema)