---
title: "Get a file"
method: GET
path: "/files/{file_id}"
tags: ["Files"]
---

# Get a file

`GET /files/{file_id}`

## Request

- Base URL: `https://api.axilio.ai/api/v1`
- URL: `https://api.axilio.ai/api/v1/files/{file_id}`
- Auth: API key in header `X-Axilio-Api-Key`
- TypeScript: <https://skmtc.dev/axilioai/apis/axilio-api-2/docs/files/:file_id/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns one file from the org's library, with a short-lived read URL once its bytes are ready. A message's media part names its file by id; this is where that id resolves. Another org's file id reads as not found.

## Path parameters

- `file_id` string, uuid, required: file identifier

## Response `200`

OK

- FileSummary: One file in the org's library.
  - `attachment_url` string: Short-lived signed URL that downloads the file as an attachment under its name. Present only for ready files.
  - `bytes_transferred` integer: Bytes moved so far for an in-flight phone transfer. Absent until the phone reports progress.
  - `capture_error` string: Reason the phone's upload failed, when it did. Present for captures and message attachments.
  - `capture_state` 'detected' | 'uploading' | 'ready' | 'skipped_size' | 'skipped_quota' | 'skipped_type' | 'dropped_teardown' | 'failed': Upload lifecycle of a file the phone sends itself: detected/uploading while in flight, ready when usable, or a terminal skip/failure with its reason. Present for captures and message attachments.
  - `checksum` string: SHA-256 of the bytes, computed on the phone while uploading. Present for captures and message attachments.
  - `created_at` string, date-time, required: When the file was registered: upload registration, or capture detection.
  - `display_url` string: Short-lived signed URL for a full-resolution JPEG of a HEIC or HEIF original, for display where a browser cannot draw the original. Absent for other types and until generated.
  - `download_url` string: Short-lived signed URL to read the file's bytes. Present only for ready files; re-list to refresh an expired one.
  - `duration_seconds` integer: Video duration in seconds.
  - `filename` string, required: Original filename; used as the display name when the file lands on a phone.
  - `height` integer: Intrinsic pixel height of the source.
  - `id` string, required: File identifier. Unique across the whole library; deliverable to a phone regardless of source.
  - `message_id` string: The message this file was attached to. Present for message attachments once the message is stored; a file whose message never arrived still names its phone.
  - `mime_type` string, required: Declared MIME type, pinned by the presigned upload.
  - `on_phone_count` integer, required: Distinct phones currently holding or receiving a delivered copy. Informational: deleting the file from the library does not remove these.
  - `phone_id` string: The phone that received the message this file was attached to. Present for message attachments.
  - `preview_state` 'processing' | 'ready' | 'unavailable', required: Whether the preview exists, is still being generated, or will never be available for this format.
  - `reel_url` string: Short-lived signed URL for the animated hover preview. Videos only; absent until generated.
  - `session_id` string: Session that produced the file. Present only for captures.
  - `size_bytes` integer, required: Declared size in bytes, pinned by the presigned upload.
  - `source` 'upload' | 'capture' | 'message', required: How the file entered the library: upload (put in directly), capture (lifted off a session), or message (attached to a message one of the org's dedicated phones received).
  - `status` 'uploading' | 'ready', required: uploading until the object is verified in storage, then ready. For a capture, read capture_state for the fuller lifecycle.
  - `surface` 'phone': Which surface a capture or message attachment came off (phone today). Absent for a direct upload.
  - `thumbnail_url` string: Short-lived signed URL for the generated preview image. Absent while generation is pending, and permanently absent for formats without a preview.
  - `width` integer: Intrinsic pixel width of the source.

## Other responses

- `404`: Not Found
- `422`: Unprocessable Entity
- `500`: Internal Server Error

## Changes

- **2026-10-24** `ecca093572e0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/axilioai/apis/axilio-api-2/changes/files/:file_id/get.md)

---

[API](https://skmtc.dev/axilioai/apis/axilio-api-2.md) - [All operations](https://skmtc.dev/axilioai/apis/axilio-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/axilioai/apis/axilio-api-2/revisions/62aa324803a7?raw)