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.