AXaxilioai
files

Get a file

Changed on

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.

get/files/{file_id}

Request

Path parameters

file_idstring uuid required

file identifier

Response

OK

$schemastring uri

A URL to the JSON Schema for this object.

attachment_urlstring

Short-lived signed URL that downloads the file as an attachment under its name. Present only for ready files.

bytes_transferredinteger

Bytes moved so far for an in-flight phone transfer. Absent until the phone reports progress.

capture_errorstring

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.

checksumstring

SHA-256 of the bytes, computed on the phone while uploading. Present for captures and message attachments.

created_atstring date-time required

When the file was registered: upload registration, or capture detection.

display_urlstring

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_urlstring

Short-lived signed URL to read the file's bytes. Present only for ready files; re-list to refresh an expired one.

duration_secondsinteger

Video duration in seconds.

filenamestring required

Original filename; used as the display name when the file lands on a phone.

heightinteger

Intrinsic pixel height of the source.

idstring required

File identifier. Unique across the whole library; deliverable to a phone regardless of source.

message_idstring

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_typestring required

Declared MIME type, pinned by the presigned upload.

on_phone_countinteger required

Distinct phones currently holding or receiving a delivered copy. Informational: deleting the file from the library does not remove these.

phone_idstring

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_urlstring

Short-lived signed URL for the animated hover preview. Videos only; absent until generated.

session_idstring

Session that produced the file. Present only for captures.

size_bytesinteger 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_urlstring

Short-lived signed URL for the generated preview image. Absent while generation is pending, and permanently absent for formats without a preview.

widthinteger

Intrinsic pixel width of the source.

Example response

{
  "$schema": "/api/v1/FileSummary.json"
}

Changes