See the Public URLs guide for expiry behaviour, idempotency, and end-to-end examples.

Create a public URL

/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_idstring

The file's `id`.

Request Body

Response Body

public_urlstring

The full public URL.

No parameters.

{
  "public_url": "https://files-cdn.x.ai/ZsqeMtdcSYWPPHTQdxXDKQ/file_a128090d-f0c9-4873-bd84-e499777e7417.png",
  "expires_at": 1755600000
}

Revoke a public URL

/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_idstring

The file's `id`.

Response Body

idstring

The file ID whose public URL was revoked.

revokedboolean

Whether a public URL was actually revoked. `false` if the file had no active public URL (no-op).

No parameters.

{
  "id": "file_a128090d-f0c9-4873-bd84-e499777e7417",
  "revoked": true,
  "public_url": "https://files-cdn.x.ai/ZsqeMtdcSYWPPHTQdxXDKQ/file_a128090d-f0c9-4873-bd84-e499777e7417.png"
}