Skip to content
Agents
Attachments

Get Attachment Status

GET
/v1/attachments/{attachment_id}
curl --request GET \
--url 'https://agents.lumalabs.ai/v1/attachments/example?session_id=example' \
--header 'Authorization: Bearer <token>'

Get current pipeline state for an uploaded attachment.

attachment_id
required
Attachment Id
string
session_id
required
Session Id

Session the attachment belongs to.

string

Session the attachment belongs to.

Successful Response

Media typeapplication/json
AttachmentResponse
object
attachment_id
required
Attachment Id

Attachment id to pass in a user.message's attachment_ids.

string
content_type
required
Content Type

MIME type of the uploaded file.

string
failure_code
Any of:
string
filename
Any of:
string
rejection_reason
Any of:
AttachmentRejectionReason

Why an attachment came back rejected — a coarse bucket, not a code.

Stable vocabulary a partner can branch on: a policy refusal is theirs to explain to their user, a corrupt file is theirs to re-encode, and an internal error or a timeout is ours. The human copy behind each of these is operator-tunable and deliberately NOT part of the contract.

This is a BUCKET over AttachmentResponse.failure_code, standing to it as failure_category stands to JobView.failure_code — several taxonomy codes collapse onto one member here (six onto internal_error alone), so it deliberately cannot be spelled as a dotted code and is not a second spelling of one. The dotted code travels beside it for a partner who wants the precise cause, which is what keeps /v1/sessions/* on one failure vocabulary.

string
Allowed values: content_moderated file_too_large video_too_long corrupt_input empty mime_mismatch unsupported_format processing_timeout internal_error
session_id
required
Session Id
string
size_bytes
required
Size Bytes
integer
state
required
AttachmentState

Pipeline_running = ingest in progress; ready = passed the pipeline; rejected = refused — see rejection_reason for which refusal it was.

string
Allowed values: pipeline_running ready rejected
url
required
Url

Presigned GET URL for immediate preview. Expires in 1 hour. Do not persist — use attachment_id to generate fresh URLs.

string
Example
{
"rejection_reason": "content_moderated",
"state": "pipeline_running"
}

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examplegenerated
{
"detail": [
{
"ctx": {},
"input": "example",
"loc": [
"example"
],
"msg": "example",
"type": "example"
}
]
}