Generate a presigned URL for file upload

Generate a presigned PUT URL so the SDK can upload a file directly to S3.

Optional Idempotency-Key header. Replay returns the same URL (and document_id / dataset_id) so a client retrying after a network blip can still complete its upload to the original S3 path. Note: presigned URLs expire after ~1 h regardless of the 24 h idempotency TTL — clients whose cached URL has expired should retry with a fresh key.

post/v1/uploads/presign

Request

  • Base URL: https://api.clichefactory.com (the document declares no server; this is the origin it was published from)
  • URL: https://api.clichefactory.com/v1/uploads/presign
  • Auth: none declared

Headers

Idempotency-Keystring nullable
X-API-KEYstring nullable

Request body

tenant_idstring
project_idstring
task_idstring
environmentstring

Logical environment tag (dev / prod / staging). Recorded as metadata on the canonical envelope and the document control-plane row, and echoed back on the response scope. Does NOT drive bucket selection — that is server-owned via S3_BUCKET_NAME. Kept on the request body for backwards compatibility and for logical scoping; clients can omit it and accept the default.

upload_kind'document' | 'training_input' | 'training_ground_truth' required
filenamestring required

Original filename (e.g. example.pdf, invoice_001.json)

content_lengthinteger nullable

File size in bytes (for validation)

content_typestring nullable

MIME type (can be derived)

dataset_idstring nullable

Training dataset ID. Required for training kinds. Server generates if omitted.

document_idstring nullable

Document ID for extraction uploads. Server generates if omitted.

artifact_idstring nullable

Artifact ID. When provided, server resolves scope from the artifact record.

Response

Successful Response

upload_urlstring required

Presigned PUT URL

methodstring
headersobject
expires_in_sinteger

URL validity in seconds

file_uristring required

Canonical s3:// URI of the uploaded file

dataset_idstring nullable

Dataset ID (for training kinds)

document_idstring nullable

Document ID (for document kind)

scopeobject

Echoed scope for debugging

Changes

No recorded changes to this operation across all 1 revision of this API.