rest-api-reference/files/public-urls.md +0 −75 deleted
File Deleted View Diff
1#### Files API
2
3# Public URLs
4
5See the [Public URLs guide](/developers/files/public-urls) for expiry behaviour, idempotency, and end-to-end examples.
6
7***
8
9## POST /v1/files/\{file\_id}/public-url
10
11Create a permanent, unauthenticated public URL for an existing file. The
12underlying file is unaffected and can still be fetched through the
13authenticated content endpoint. Use this when you want to share a stored
14asset (image, video, PDF) outside your API-keyed environment. Public URLs
15can be revoked at any time via \`POST /v1/files/\{file\_id}/public-url/revoke\`.
16
17### Path Parameters
18
19* `file_id` (string, required) — The file's \`id\`.
20
21### Request Body
22
23* `expires_after` (integer | null) — Seconds from now until the public URL expires. Must be between \`3600\` (1
24 hour) and \`2592000\` (30 days). Omit to inherit the file's expiry (if it
25 has one) or to make the URL valid indefinitely.
26
27### Response Body
28
29* `expires_at` (integer | null) — Unix timestamp (seconds) when the public URL expires. Present when
30 the public URL has an expiry, either from an explicit \`expires\_after\`
31 in the request or inherited from the file's TTL. Absent when the
32 public URL is valid indefinitely.
33
34* `public_url` (string, required) — The full public URL.
35
36\*\*Response example:\*\*
37
38```json
39{
40 "public_url": "https://files-cdn.x.ai/ZsqeMtdcSYWPPHTQdxXDKQ/file_a128090d-f0c9-4873-bd84-e499777e7417.png",
41 "expires_at": 1755600000
42}
43```
44
45***
46
47## POST /v1/files/\{file\_id}/public-url/revoke
48
49Revoke the active public URL for a file. The underlying file remains
50available through the authenticated content endpoint. Revoke is idempotent
51— calling it on a file without an active public URL returns
52\`revoked: false\` without an error.
53
54### Path Parameters
55
56* `file_id` (string, required) — The file's \`id\`.
57
58### Response Body
59
60* `id` (string, required) — The file ID whose public URL was revoked.
61
62* `public_url` (string | null) — The full public URL that was revoked. Only present when \`revoked\` is \`true\`.
63
64* `revoked` (boolean, required) — Whether a public URL was actually revoked. \`false\` if the file had no
65 active public URL (no-op).
66
67\*\*Response example:\*\*
68
69```json
70{
71 "id": "file_a128090d-f0c9-4873-bd84-e499777e7417",
72 "revoked": true,
73 "public_url": "https://files-cdn.x.ai/ZsqeMtdcSYWPPHTQdxXDKQ/file_a128090d-f0c9-4873-bd84-e499777e7417.png"
74}
75```