# Files — API reference

Stored files and the artifacts derived from them.

## GET /v1/files

List files

Parameters

| Name | In | Requirement | Description |
| --- | --- | --- | --- |
| `limit` | query | Optional | Page size. |

Responses

| Status | Description |
| --- | --- |
| `200` | A page of files, newest first. |
| `400` | Codes: invalid_request, unsupported_file, file_too_large, corrupted_file, encrypted_file, unsupported_operation. |
| `401` | Codes: missing_credentials, invalid_api_key, expired_api_key, revoked_api_key, api_key_in_query. |
| `403` | Codes: insufficient_scope, ip_not_allowed, environment_mismatch, organization_suspended, forbidden, key_restricted. |
| `429` | Rate limited or out of credits. Retry after the interval in `Retry-After`. Codes: key_spend_limit, rate_limited, concurrency_limit, credits_exhausted. |
| `500` | Codes: internal_error. |
| `503` | Codes: processing_unavailable, dependency_unavailable. |
| `504` | Codes: timeout. |

## GET /v1/files/{file_id}

Retrieve a file

Parameters

| Name | In | Requirement | Description |
| --- | --- | --- | --- |
| `file_id` | path | Required | File identifier. |

Responses

| Status | Description |
| --- | --- |
| `200` | The file and its artifacts. |
| `401` | Codes: missing_credentials, invalid_api_key, expired_api_key, revoked_api_key, api_key_in_query. |
| `403` | Codes: insufficient_scope, ip_not_allowed, environment_mismatch, organization_suspended, forbidden, key_restricted. |
| `404` | Not found. A resource belonging to another organization returns 404, never 403 — a 403 would confirm it exists. Codes: not_found. |
| `429` | Rate limited or out of credits. Retry after the interval in `Retry-After`. Codes: key_spend_limit, rate_limited, concurrency_limit, credits_exhausted. |
| `500` | Codes: internal_error. |
| `503` | Codes: processing_unavailable, dependency_unavailable. |
| `504` | Codes: timeout. |

## DELETE /v1/files/{file_id}

Deletes the file and every artifact derived from it. Not reversible.

Parameters

| Name | In | Requirement | Description |
| --- | --- | --- | --- |
| `file_id` | path | Required | File identifier. |

Responses

| Status | Description |
| --- | --- |
| `204` | Deleted, along with every artifact derived from it. |
| `401` | Codes: missing_credentials, invalid_api_key, expired_api_key, revoked_api_key, api_key_in_query. |
| `403` | Codes: insufficient_scope, ip_not_allowed, environment_mismatch, organization_suspended, forbidden, key_restricted. |
| `404` | Not found. A resource belonging to another organization returns 404, never 403 — a 403 would confirm it exists. Codes: not_found. |
| `429` | Rate limited or out of credits. Retry after the interval in `Retry-After`. Codes: key_spend_limit, rate_limited, concurrency_limit, credits_exhausted. |
| `500` | Codes: internal_error. |
| `503` | Codes: processing_unavailable, dependency_unavailable. |
| `504` | Codes: timeout. |

## GET /v1/files/{file_id}/history

The file’s own story, in order: upload opened, validated or rejected, every job created and how each finished — assembled from the records the platform already keeps, never a second ledger that could disagree with the first.

Parameters

| Name | In | Requirement | Description |
| --- | --- | --- | --- |
| `file_id` | path | Required | File identifier. |

Responses

| Status | Description |
| --- | --- |
| `200` | The events, oldest first. |
| `401` | Codes: missing_credentials, invalid_api_key, expired_api_key, revoked_api_key, api_key_in_query. |
| `403` | Codes: insufficient_scope, ip_not_allowed, environment_mismatch, organization_suspended, forbidden, key_restricted. |
| `404` | Not found. A resource belonging to another organization returns 404, never 403 — a 403 would confirm it exists. Codes: not_found. |
| `429` | Rate limited or out of credits. Retry after the interval in `Retry-After`. Codes: key_spend_limit, rate_limited, concurrency_limit, credits_exhausted. |
| `500` | Codes: internal_error. |
| `503` | Codes: processing_unavailable, dependency_unavailable. |
| `504` | Codes: timeout. |

## POST /v1/files/{file_id}/download-url

Authorises first, then mints a short-lived URL on `cdn.fylane.dev`. The authorisation decision happens before the URL exists, so possession of a URL is never itself the permission.

Parameters

| Name | In | Requirement | Description |
| --- | --- | --- | --- |
| `file_id` | path | Required | File identifier. |
| `Idempotency-Key` | header | Required | Client-generated key, scoped to (organization, endpoint) and retained 24 hours. A replay with the same body returns the stored response without re-executing or re-billing; a replay with a different body returns 409. |

Request body

| Field | Type | Requirement | Description |
| --- | --- | --- | --- |
| `artifact_id` | `string` | Optional | Defaults to the original file. |
| `expires_in` | `integer` | Optional | Lifetime in seconds. |

Responses

| Status | Description |
| --- | --- |
| `201` | A short-lived URL. |
| `400` | Codes: invalid_request, unsupported_file, file_too_large, corrupted_file, encrypted_file, unsupported_operation. |
| `401` | Codes: missing_credentials, invalid_api_key, expired_api_key, revoked_api_key, api_key_in_query. |
| `403` | Codes: insufficient_scope, ip_not_allowed, environment_mismatch, organization_suspended, forbidden, key_restricted. |
| `404` | Not found. A resource belonging to another organization returns 404, never 403 — a 403 would confirm it exists. Codes: not_found. |
| `409` | Codes: idempotency_conflict, upload_session_consumed, conflict. |
| `429` | Rate limited or out of credits. Retry after the interval in `Retry-After`. Codes: key_spend_limit, rate_limited, concurrency_limit, credits_exhausted. |
| `500` | Codes: internal_error. |
| `503` | Codes: processing_unavailable, dependency_unavailable. |
| `504` | Codes: timeout. |