Files · Docs

Upload a file by sending its bytes with a purpose, and use the file ID it returns, like a submission's file or an account's profilePicture.

Upload

Send the raw bytes as the request body. purpose and name go in the query:

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

With the SDK, pass a Blob or File as the body:

TypeScript

import { readFile } from "node:fs/promises"

const { data: file } = await lucra.files.create({
  query: { purpose: "product_image", name: "hero.jpg" },
  body: new Blob([await readFile("hero.jpg")]),
})

Upload as the account that will use the file. A creator's video is uploaded acting as the creator (Lucra-Account: crtr_…).

Purposes

`purpose`	What
`submission`	A creator's video for a program
`ad_creative`	A brand's own video for its library
`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
`chat_attachment`	A file attached to a message

For a large video, reserve the upload instead: send size and contentType (and optionally checksum, its SHA-256) with an empty body. The response's upload says where to PUT the bytes. Then finish with PATCH /v1/files/:id and { "status": "processing" }.

Processing

Images are ready at once. Videos stay processing while Lucra checks and prepares them; poll GET /v1/files/:id, or wait for the file.ready webhook. Using a file before it's ready returns 409 file_processing.

Endpoints

POST/v1/files

As creatorwrite

Upload a file

const { data } = await lucra.files.create({
  query: { purpose: "submission" },
  body: file,
})

Query parameters

purposeenum· required
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.
checksumstring
With size: the file's SHA-256 (lowercase hex). Storage then checks the bytes as they arrive, so finishing a video is quicker.
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

const { data } = await lucra.files.list({
  query: { purpose: "…" },
})

Query parameters

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.

Plus paging: limit, cursor, createdAfter and createdBefore.

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

const { data } = await lucra.files.retrieve({
  path: { id: "file_…" },
})

Path parameters

idfile_…· required

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

const { data } = await lucra.files.update({
  path: { id: "file_…" },
  body: { status: "processing" },
})

Path parameters

idfile_…· required

Body

statusenum· required
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

Upload

Purposes

Large files

Processing

Endpoints

Query parameters

Body

Query parameters

Path parameters

Path parameters

Body