Files API
Public URLs
See the Public URLs guide for expiry behaviour, idempotency, and end-to-end examples.
POST /v1/files/{file_id}/public-url
Create a permanent, unauthenticated public URL for an existing file. The underlying file is unaffected and can still be fetched through the authenticated content endpoint. Use this when you want to share a stored asset (image, video, PDF) outside your API-keyed environment. Public URLs can be revoked at any time via `POST /v1/files/{file_id}/public-url/revoke`.
Path Parameters
file_id(string, required) — The file's `id`.
Request Body
expires_after(integer | null) — Seconds from now until the public URL expires. Must be between `3600` (1 hour) and `2592000` (30 days). Omit to inherit the file's expiry (if it has one) or to make the URL valid indefinitely.
Response Body
-
expires_at(integer | null) — Unix timestamp (seconds) when the public URL expires. Present when the public URL has an expiry, either from an explicit `expires_after` in the request or inherited from the file's TTL. Absent when the public URL is valid indefinitely. -
public_url(string, required) — The full public URL.
**Response example:**
{
"public_url": "https://files-cdn.x.ai/ZsqeMtdcSYWPPHTQdxXDKQ/file_a128090d-f0c9-4873-bd84-e499777e7417.png",
"expires_at": 1755600000
}
POST /v1/files/{file_id}/public-url/revoke
Revoke the active public URL for a file. The underlying file remains available through the authenticated content endpoint. Revoke is idempotent — calling it on a file without an active public URL returns `revoked: false` without an error.
Path Parameters
file_id(string, required) — The file's `id`.
Response Body
-
id(string, required) — The file ID whose public URL was revoked. -
public_url(string | null) — The full public URL that was revoked. Only present when `revoked` is `true`. -
revoked(boolean, required) — Whether a public URL was actually revoked. `false` if the file had no active public URL (no-op).
**Response example:**
{
"id": "file_a128090d-f0c9-4873-bd84-e499777e7417",
"revoked": true,
"public_url": "https://files-cdn.x.ai/ZsqeMtdcSYWPPHTQdxXDKQ/file_a128090d-f0c9-4873-bd84-e499777e7417.png"
}