Uploads — API reference

Getting bytes into Fylane without them touching the API.

POST /v1/uploads

Returns a single-use, size-capped, pre-signed URL. Upload the bytes directly to it; they never pass through the API, which is why a 5 GB file and a 5 KB file cost the same to accept. Two variants share the endpoint: multipart: true answers with one pre-signed URL per part instead of a single PUT, and from_url has the platform fetch a public URL itself — the answer is then the completed File, not a session.

Parameters

Name	In	Requirement	Description
`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
`filename`	`string`	Optional
`byte_size`	`integer`	Optional	Declared size. The signed URL enforces it; a larger body is refused.
`mime_type`	`string`	Optional	Declared type. Verified against the bytes.
`multipart`	`boolean`	Optional	Ask for a multipart session: per-part pre-signed URLs (16 MB+ parts, at most 64), finished via `POST /v1/uploads/{upload_id}/complete-parts`. Parts fail and retry individually, and `POST /v1/uploads/{upload_id}/parts` re-mints fresh URLs — the resume path.
`from_url`	`string` (uri)	Optional	A public HTTPS URL for the platform to fetch server-side. Private networks and redirects are refused; the response is the completed, validated `File` rather than an upload session.
`project_id`	`string`	Optional	Defaults to the key’s project.
`validation`	`object`	Optional	Acceptance policy for this upload, judged against the detected bytes at completion — never against the declared type. A file that fails is recorded `rejected` with the findings, and completion answers `validation_failed`.

Responses

Status	Description
`200`	The `from_url` variant only: the URL was fetched, validated and completed in one step.
`201`	Session created.
`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.
`409`	Codes: idempotency_conflict, upload_session_consumed, conflict.
`413`	Codes: payload_too_large.
`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/uploads/{upload_id}

Retrieve an upload session

Parameters

Name	In	Requirement	Description
`upload_id`	path	Required	Upload session identifier.

Responses

Status	Description
`200`	The session.
`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/uploads/{upload_id}/parts

Fresh pre-signed URLs for every part of a multipart session — the resume path. Losing a connection loses only the parts in flight: re-mint, re-upload the missing parts, and complete.

Parameters

Name	In	Requirement	Description
`upload_id`	path	Required	Upload session 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.

Responses

Status	Description
`200`	One fresh URL per part.
`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.

POST /v1/uploads/{upload_id}/complete-parts

Hand back the {part_number, etag} pairs storage answered each part with. The object is assembled, measured (the declared size was a promise; the measurement is what validation judges), and then the one standard completion runs — detection, policy, hash, duplicate detection, identical to a single PUT.

Parameters

Name	In	Requirement	Description
`upload_id`	path	Required	Upload session 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
`parts`	array of `object`	Required

Responses

Status	Description
`200`	Assembled and completed.
`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.
`422`	Codes: malware_detected, policy_violation, validation_failed, output_validation_failed, unsupported_input.
`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/uploads/{upload_id}/abort

Discards the parts uploaded so far. Sessions abandoned without an abort are swept automatically after a day.

Parameters

Name	In	Requirement	Description
`upload_id`	path	Required	Upload session 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.

Responses

Status	Description
`204`	Aborted; stored parts discarded.
`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}/complete

Tell the platform the bytes have landed. Detection, validation policy and (within the hash window) SHA-256 and duplicate detection all run here, against the bytes actually stored — never against what was declared. A file that fails its validation policy is recorded rejected and this call answers with the refusal.

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.

Responses

Status	Description
`200`	The completed file, `ready` for jobs — carrying `duplicate_of` when another ready file in the project has identical content.
`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.
`422`	Codes: malware_detected, policy_violation, validation_failed, output_validation_failed, unsupported_input.
`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.