Files · Docs

Upload a file in one request: send the bytes with a purpose, and get a file ID back.

Terminal

curl -X POST "https://api.onlucra.com/v1/files?purpose=product_image&name=hero.jpg" \
  -H "Authorization: Bearer $LUCRA_API_KEY" \
  -H "Lucra-Version: 2026-10-01" \
  --data-binary @hero.jpg

Purposes

`purpose`	What
`submission`	A creator's video
`product_image`	A product image
`profile_picture`	A logo or profile photo
`program_brief`	A PDF brief
`program_reference_video`	An example video for creators
`agreement`	A PDF agreement

Processing

Images are ready at once. Videos are processing until Lucra finishes with them; poll GET /v1/files/:id. Using a file before it's ready returns 409 file_processing.

Endpoints

POST/v1/files

As creatorwrite

Upload a file

SDKlucra.files.create({ query, body })

Query parameters

purposeenumrequired
submissionproduct_imageprofile_pictureprogram_briefprogram_reference_videoagreementchat_attachmentad_creativeprofile_referenceprofile_reference_thumbnail
namestring
sizeinteger
Reserve instead of streaming: the file's size in bytes. The body stays empty.
contentTypestring
With `size`: the file's MIME type.
ownerstring
With purpose=profile_picture: the signed-in person's own photo, for PATCH /v1/me.
me

Body

The file's raw bytes.

Response20115 fieldsShow

idfile_…
purposeenum
submissionproduct_imageprofile_pictureprogram_briefprogram_reference_videoagreementchat_attachmentad_creativeprofile_referenceprofile_reference_thumbnail
statusenum
awaiting_upload: reserved, waiting for the bytes at `upload.url`; processing: being verified or prepared; failed carries why.
awaiting_uploadprocessingreadyfaileddeleted
fileNamestringnullable
contentTypestringnullable
sizenumbernullable
urlstringnullable
A signed link to the file, valid for about 10 minutes; null until it's ready.
widthnumbernullable
heightnumbernullable
blurHashstringnullable
An image's blur-hash placeholder, once computed.
errorobjectnullable
Why it failed; `upload_incomplete` when the upload was cut off.
Show 2 child fieldsHide child fields
- codestring
- messagestring
uploadobject
Where to PUT the bytes, with these headers, before `expiresAt`; only on a reservation.
Show 3 child fieldsHide child fields
- urlstring
- headersobject
- expiresAtstring
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

GET/v1/files

As creatorread

List files

SDKlucra.files.list({ query })

Query parameters

limitinteger
cursorstring
createdAfterstring
Only items created at or after this time.
createdBeforestring
Only items created before this time.
purposestring
One or more, comma-separated: submission, product_image, profile_picture, program_brief, program_reference_video, agreement, chat_attachment, ad_creative, profile_reference, profile_reference_thumbnail.
statusstring
One or more, comma-separated: awaiting_upload, processing, ready, failed, deleted.

Response200A page of items, 15 fields each, and nextCursorShow

idfile_…
purposeenum
submissionproduct_imageprofile_pictureprogram_briefprogram_reference_videoagreementchat_attachmentad_creativeprofile_referenceprofile_reference_thumbnail
statusenum
awaiting_upload: reserved, waiting for the bytes at `upload.url`; processing: being verified or prepared; failed carries why.
awaiting_uploadprocessingreadyfaileddeleted
fileNamestringnullable
contentTypestringnullable
sizenumbernullable
urlstringnullable
A signed link to the file, valid for about 10 minutes; null until it's ready.
widthnumbernullable
heightnumbernullable
blurHashstringnullable
An image's blur-hash placeholder, once computed.
errorobjectnullable
Why it failed; `upload_incomplete` when the upload was cut off.
Show 2 child fieldsHide child fields
- codestring
- messagestring
uploadobject
Where to PUT the bytes, with these headers, before `expiresAt`; only on a reservation.
Show 3 child fieldsHide child fields
- urlstring
- headersobject
- expiresAtstring
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

GET/v1/files/:id

As creatorread

Get a file

SDKlucra.files.retrieve({ path: { id } })

Path parameters

idstringrequired

Response20015 fieldsShow

idfile_…
purposeenum
submissionproduct_imageprofile_pictureprogram_briefprogram_reference_videoagreementchat_attachmentad_creativeprofile_referenceprofile_reference_thumbnail
statusenum
awaiting_upload: reserved, waiting for the bytes at `upload.url`; processing: being verified or prepared; failed carries why.
awaiting_uploadprocessingreadyfaileddeleted
fileNamestringnullable
contentTypestringnullable
sizenumbernullable
urlstringnullable
A signed link to the file, valid for about 10 minutes; null until it's ready.
widthnumbernullable
heightnumbernullable
blurHashstringnullable
An image's blur-hash placeholder, once computed.
errorobjectnullable
Why it failed; `upload_incomplete` when the upload was cut off.
Show 2 child fieldsHide child fields
- codestring
- messagestring
uploadobject
Where to PUT the bytes, with these headers, before `expiresAt`; only on a reservation.
Show 3 child fieldsHide child fields
- urlstring
- headersobject
- expiresAtstring
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

PATCH/v1/files/:id

As creatorwrite

Finish or delete an upload

SDKlucra.files.update({ path: { id }, body })

Path parameters

idstringrequired

Body

statusenumrequired
processing: the bytes are at `upload.url`, so verify and store them (images are then ready at once); deleted: cancel the upload, or delete a file nothing uses.
processingdeleted

Response20015 fieldsShow

idfile_…
purposeenum
submissionproduct_imageprofile_pictureprogram_briefprogram_reference_videoagreementchat_attachmentad_creativeprofile_referenceprofile_reference_thumbnail
statusenum
awaiting_upload: reserved, waiting for the bytes at `upload.url`; processing: being verified or prepared; failed carries why.
awaiting_uploadprocessingreadyfaileddeleted
fileNamestringnullable
contentTypestringnullable
sizenumbernullable
urlstringnullable
A signed link to the file, valid for about 10 minutes; null until it's ready.
widthnumbernullable
heightnumbernullable
blurHashstringnullable
An image's blur-hash placeholder, once computed.
errorobjectnullable
Why it failed; `upload_incomplete` when the upload was cut off.
Show 2 child fieldsHide child fields
- codestring
- messagestring
uploadobject
Where to PUT the bytes, with these headers, before `expiresAt`; only on a reservation.
Show 3 child fieldsHide child fields
- urlstring
- headersobject
- expiresAtstring
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring