--- title: Upload Attachment | Luma Agents --- POST /v1/attachments Select code samplecURL (shell:curl) ```js const url = 'https://agents.lumalabs.ai/v1/attachments?session_id=example'; const options = {method: 'POST', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url 'https://agents.lumalabs.ai/v1/attachments?session_id=example' \ --header 'Authorization: Bearer ' ``` - Productionagents.lumalabs.ai/v1/attachments Upload a file and begin the artifact ingest pipeline. Returns immediately after the S3 write. Pipeline (moderation, thumbnails, embeddings) runs asynchronously. An `attachment_ready` SSE event fires on the session when the pipeline reaches a terminal state. ## Authorizations - **[BearerAuth](/api/agents/index.md#bearerauth)** ## Parameters ### Query Parameters **session\_id** required *Session Id* Session this attachment belongs to string Session this attachment belongs to ## Responses ### 201 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](#tab-panel-0-0) - [null](#tab-panel-0-1) string null **filename** Any of: - [string](#tab-panel-1-0) - [null](#tab-panel-1-1) string null **rejection\_reason** Any of: - [AttachmentRejectionReason](#tab-panel-2-0) - [null](#tab-panel-2-1) *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 null **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 ```json { "rejection_reason": "content_moderated", "state": "pipeline_running" } ``` ### 422 Validation Error Media typeapplication/json *HTTPValidationError* object **detail** *Detail* Array\ *ValidationError* object **ctx** *Context* object **input** *Input* **loc** required *Location* Array **msg** required *Message* string **type** required *Error Type* string ##### Examplegenerated ```json { "detail": [ { "ctx": {}, "input": "example", "loc": [ "example" ], "msg": "example", "type": "example" } ] } ```