API ReferenceFiles

Get File

Beta

Read a file’s metadata. A file past its expires_at answers 404. Dark launch: requires the durable_runs_access entitlement (402 durable_runs_not_in_plan otherwise).

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Path parameters

file_idstringRequired

File id (prefixed external id, file_...).

Headers

Speechify-VersionstringOptional

Response headers

Speechify-Request-IdstringOptional
Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a `Speechify-Request-Id` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope. The legacy alias `X-Request-ID` carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Response

OK
idstringformat: "^file_[0-9a-hjkmnp-tv-z]{26}$"
filenamestring
content_typestring

The file’s media type, normalised from the upload. An agent can read application/pdf, text/plain, text/markdown, text/html and image/* inside a run; any other type is stored and served but reports itself unreadable to the agent.

size_bytesinteger>=0
kindenum

The file’s lifetime, declared at upload. ephemeral is working material for a run and is deleted 14 days after upload; kept survives until you delete it and carries no expires_at at all. Only a kept file can be published at a path.

content_pathstring

The API path the bytes stream from (prepend the API host).

created_atdatetime
project_idstringOptionalformat: "^proj_[0-9a-hjkmnp-tv-z]{26}$"

The project the file belongs to; absent for the Default project.

user_identitystringOptional

The person this file was uploaded for. Only a run acting for that same person can read it. Absent means workspace-wide: any run in the workspace can.

pathstringOptionalformat: "^[A-Za-z0-9][A-Za-z0-9._~-]*(/[A-Za-z0-9][A-Za-z0-9._~-]*)*$"<=512 characters

The name a serving layer addresses this file by, unique among the workspace’s live files. Slash-separated segments of letters, digits and . _ ~ -; no leading slash and no ... Absent on a file nothing publishes.

sourceobjectOptional
The run whose tool call produced this file. Present only on a file Speechify captured from a tool's response, absent on a customer upload.
expires_atdatetimeOptional

When an ephemeral file is deleted automatically, 14 days after upload; after it passes, every read answers 404 and the bytes are collected. Absent on a kept file, which does not expire - rather than a far-future date you would have to recognise as “never”.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
404
Not Found Error