--- title: "Files and file links" description: "7 operations, with parameters and examples." url: https://docs.fluveo.com/api/files/ --- > Index of every page: https://docs.fluveo.com/llms.txt. Integrating Fluveo? Read https://docs.fluveo.com/agents/integrate.md first. > Too long? This page with code in one language only: https://docs.fluveo.com/api/files.curl.md (cURL), https://docs.fluveo.com/api/files.node.md (Node.js), https://docs.fluveo.com/api/files.python.md (Python), https://docs.fluveo.com/api/files.php.md (PHP). # Files and file links 7 operations, with parameters and examples. Files hold documents the store uploads, such as dispute evidence. A file link gives a time-limited URL to a file's contents. Both answer to test and live keys, each mode with its own files. Send every request to `https://api.fluveo.com/v1` with your secret key as a Bearer token. This page lists only what Fluveo serves; [the OpenAPI file](https://docs.fluveo.com/openapi.json) holds the same operations. An operation or a parameter marked **Preview** works, but it is not locked yet and may change: [what Preview means](https://docs.fluveo.com/api.md#preview). > **For AI agents:** > > Use plain HTTP; install no payments SDK. Send `Authorization: Bearer sk_test_...` and a fresh `Idempotency-Key` on every POST; reuse the same key only when you retry that same POST. Send only the documented parameters. An operation or a parameter marked Preview may change: prefer the ones without the mark. ## Creates a link to a file's contents (Preview) `POST /v1/file_links` Permission: [`rak_file_write`](https://docs.fluveo.com/permissions.md#file). **Preview:** this operation works, but it is not locked yet; it may change. **Headers** - `Idempotency-Key` (string, optional): Send a unique key, 1 to 255 characters, on every POST. A retry with the same key and the same body returns the first answer instead of acting twice (with Idempotent-Replayed: true); the same key with another body is refused. Keys are kept 7 days, except on POST /v1/checkout/sessions, POST /v1/checkout/sessions/{session} and POST /v1/webhook_endpoints, where a key holds 24 hours; webhook endpoint keys are also capped at the newest 32 per store and mode. Do not rely on a replay after that window. GET and DELETE ignore it. - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. **Body parameters** - `expires_at` (integer, optional): When the link stops working, a Unix timestamp. Leave it out for a link that does not expire. - `file` (string, required): The file to share (file_...). - `metadata` (object, optional): Up to 50 key-value pairs of your own, sent as metadata[key]=value: keys of 1 to 40 characters, values up to 500. Keys starting with fluveo_ are reserved. On an update, an empty value removes a key. Use only the documented body parameters. Send a new `Idempotency-Key` with each new request, and the same key again only to retry that request. Returns a [`file_link`](https://docs.fluveo.com/api/files.md#object-file_link) object. **Request** cURL: ```bash curl https://api.fluveo.com/v1/file_links \ -H "Authorization: Bearer sk_test_..." \ -H "Idempotency-Key: $(uuidgen)" \ --data-urlencode "file=file_123" ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/file_links", { method: "POST", headers: { "Authorization": "Bearer sk_test_...", "Idempotency-Key": crypto.randomUUID(), }, body: new URLSearchParams([["file","file_123"]]), }); console.log(await response.json()); ``` Python: ```python import uuid import requests response = requests.post( "https://api.fluveo.com/v1/file_links", headers={"Authorization": "Bearer sk_test_...", "Idempotency-Key": str(uuid.uuid4())}, data=[("file", "file_123")], ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", "Idempotency-Key: " . bin2hex(random_bytes(16)), ], CURLOPT_POSTFIELDS => "file=file_123", ]); echo curl_exec($ch); ``` ## Lists the store's file links (Preview) `GET /v1/file_links` Permission: [`rak_file_read`](https://docs.fluveo.com/permissions.md#file). **Preview:** this operation works, but it is not locked yet; it may change. **Query parameters** - `created` (object, optional): Filter on the creation time, a Unix timestamp: created= for an exact match, or created[gt], created[gte], created[lt], created[lte]. - `ending_before` (string, optional): Cursor: the id of the first object of the current page, to get the previous page. Do not send it with starting_after. - `expired` (boolean, optional): true for links that already expired, false for live ones. - `file` (string, optional): Only the links of this file. - `limit` (integer, optional): How many objects to return, from 1 to 100. Default 10. - `starting_after` (string, optional): Cursor: the id of the last object of the previous page, to get the next page. Do not send it with ending_before. **Headers** - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. Returns a list of [`file_link`](https://docs.fluveo.com/api/files.md#object-file_link) objects. **Request** cURL: ```bash curl https://api.fluveo.com/v1/file_links \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/file_links", { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/file_links", headers={"Authorization": "Bearer sk_test_..."}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## Lists the store's files (Preview) `GET /v1/files` Permission: [`rak_file_read`](https://docs.fluveo.com/permissions.md#file). **Preview:** this operation works, but it is not locked yet; it may change. **Query parameters** - `created` (object, optional): Filter on the creation time, a Unix timestamp: created= for an exact match, or created[gt], created[gte], created[lt], created[lte]. - `ending_before` (string, optional): Cursor: the id of the first object of the current page, to get the previous page. Do not send it with starting_after. - `limit` (integer, optional): How many objects to return, from 1 to 100. Default 10. - `purpose` (enum, optional): Only the files uploaded for this purpose, such as dispute_evidence. One of: `account_requirement`, `additional_verification`, `business_icon`, `business_logo`, `customer_signature`, `dispute_evidence`, `document_provider_identity_document`, `finance_report_run`, `financial_account_statement`, `identity_document`, `identity_document_downloadable`, `issuing_regulatory_reporting`, `pci_document`, `platform_terms_of_service`, `selfie`, `sigma_scheduled_query`, `tax_document_user_upload`, `terminal_android_apk`, `terminal_reader_splashscreen`, `terminal_wifi_certificate`, `terminal_wifi_private_key`. - `starting_after` (string, optional): Cursor: the id of the last object of the previous page, to get the next page. Do not send it with ending_before. **Headers** - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. Returns a list of [`file`](https://docs.fluveo.com/api/files.md#object-file) objects. **Request** cURL: ```bash curl https://api.fluveo.com/v1/files \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/files", { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/files", headers={"Authorization": "Bearer sk_test_..."}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## Updates a file link's expiry or metadata (Preview) `POST /v1/file_links/{link}` Permission: [`rak_file_write`](https://docs.fluveo.com/permissions.md#file). **Preview:** this operation works, but it is not locked yet; it may change. **Path parameters** - `link` (string, required): The file link's id. **Headers** - `Idempotency-Key` (string, optional): Send a unique key, 1 to 255 characters, on every POST. A retry with the same key and the same body returns the first answer instead of acting twice (with Idempotent-Replayed: true); the same key with another body is refused. Keys are kept 7 days, except on POST /v1/checkout/sessions, POST /v1/checkout/sessions/{session} and POST /v1/webhook_endpoints, where a key holds 24 hours; webhook endpoint keys are also capped at the newest 32 per store and mode. Do not rely on a replay after that window. GET and DELETE ignore it. - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. **Body parameters** - `expires_at` (integer, optional): A new expiry time, a Unix timestamp. - `metadata` (object, optional): Up to 50 key-value pairs of your own, sent as metadata[key]=value: keys of 1 to 40 characters, values up to 500. Keys starting with fluveo_ are reserved. On an update, an empty value removes a key. Use only the documented body parameters. Send a new `Idempotency-Key` with each new request, and the same key again only to retry that request. Returns a [`file_link`](https://docs.fluveo.com/api/files.md#object-file_link) object. **Request** cURL: ```bash curl https://api.fluveo.com/v1/file_links/link_123 \ -H "Authorization: Bearer sk_test_..." \ -H "Idempotency-Key: $(uuidgen)" \ --data-urlencode "metadata[case]=du_123" ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/file_links/link_123", { method: "POST", headers: { "Authorization": "Bearer sk_test_...", "Idempotency-Key": crypto.randomUUID(), }, body: new URLSearchParams([["metadata[case]","du_123"]]), }); console.log(await response.json()); ``` Python: ```python import uuid import requests response = requests.post( "https://api.fluveo.com/v1/file_links/link_123", headers={"Authorization": "Bearer sk_test_...", "Idempotency-Key": str(uuid.uuid4())}, data=[("metadata[case]", "du_123")], ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", "Idempotency-Key: " . bin2hex(random_bytes(16)), ], CURLOPT_POSTFIELDS => "metadata%5Bcase%5D=du_123", ]); echo curl_exec($ch); ``` ## Retrieves a file link (Preview) `GET /v1/file_links/{link}` Permission: [`rak_file_read`](https://docs.fluveo.com/permissions.md#file). **Preview:** this operation works, but it is not locked yet; it may change. **Path parameters** - `link` (string, required): The file link's id. **Headers** - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. Returns a [`file_link`](https://docs.fluveo.com/api/files.md#object-file_link) object. **Request** cURL: ```bash curl https://api.fluveo.com/v1/file_links/link_123 \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/file_links/link_123", { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/file_links/link_123", headers={"Authorization": "Bearer sk_test_..."}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## Retrieves a file's details (Preview) `GET /v1/files/{file}` Permission: [`rak_file_read`](https://docs.fluveo.com/permissions.md#file). **Preview:** this operation works, but it is not locked yet; it may change. **Path parameters** - `file` (string, required): The file's id. **Headers** - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. Returns a [`file`](https://docs.fluveo.com/api/files.md#object-file) object. **Request** cURL: ```bash curl https://api.fluveo.com/v1/files/file_123 \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/files/file_123", { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/files/file_123", headers={"Authorization": "Bearer sk_test_..."}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## Downloads a file's contents with the API key: the file's url, for a purpose that allows downloading. It is served on the host the url names; when the url names a files host, the API host answers 404 not_found (Preview) `GET /v1/files/{file}/contents` Permission: [`rak_file_read`](https://docs.fluveo.com/permissions.md#file). **Preview:** this operation works, but it is not locked yet; it may change. **Headers** - `Fluveo-Version` (enum, optional): Optional. The only version Fluveo serves is 2026-05-27.dahlia; any other value is refused with a 400. Every answer names that version in its own Fluveo-Version header, except the refusals Fluveo gives before it reads the request (no key, an unknown key, an unknown URL, a body that is not a form) and a file's bytes, which name no version and no Request-Id. One of: `2026-05-27.dahlia`. Returns the file's bytes. **Request** cURL: ```bash curl https://api.fluveo.com/v1/files/file_123/contents \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.fluveo.com/v1/files/file_123/contents", { method: "GET", headers: { "Authorization": "Bearer sk_test_...", }, }); console.log(await response.json()); ``` Python: ```python import requests response = requests.get( "https://api.fluveo.com/v1/files/file_123/contents", headers={"Authorization": "Bearer sk_test_..."}, ) print(response.json()) ``` PHP: ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer sk_test_...", ], ]); echo curl_exec($ch); ``` ## The file_link object Ids start with `link_`. **Attributes** - `created` (integer) - `expired` (boolean) - `expires_at` (integer, nullable) - `file` (string, expandable): An id by default; send `expand[]=file` to get the full file object. - `id` (string) - `livemode` (boolean) - `metadata` (object) - `object` (enum): One of: `file_link`. - `url` (string, nullable) ## The file object Ids start with `file_`. **Attributes** - `created` (integer) - `expires_at` (integer, nullable) - `filename` (string, nullable) - `id` (string) - `links` (object, nullable) - `object` (enum): One of: `file`. - `purpose` (enum): One of: `account_requirement`, `additional_verification`, `business_icon`, `business_logo`, `customer_signature`, `dispute_evidence`, `document_provider_identity_document`, `finance_report_run`, `financial_account_statement`, `identity_document`, `identity_document_downloadable`, `issuing_regulatory_reporting`, `pci_document`, `platform_terms_of_service`, `selfie`, `sigma_scheduled_query`, `tax_document_user_upload`, `terminal_android_apk`, `terminal_reader_splashscreen`, `terminal_wifi_certificate`, `terminal_wifi_private_key`. - `size` (integer) - `title` (string, nullable) - `type` (string, nullable) - `url` (string, nullable)