Presign a Document File Upload

post/v1/graphs/{graph_id}/operations/create-document-upload

Start uploading a document file: a PDF (a bank statement kept as evidence for a recorded balance, an invoice) or a PNG or JPEG photo (a receipt). Returns an upload id and a presigned URL: PUT the file there with the same Content-Type (and Content-Length, if declared), then call complete-document-upload, which creates the document. Nothing is recorded until then, and an upload never completed expires. A stored file is not indexed for search, does not count toward the plan's document limit, and never changes once stored.

Idempotency: supply an Idempotency-Key header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.

Authentication

Authenticate in any one of these ways — not all of them:

API key in the X-API-Key header.
Bearer token in the Authorization header.

Path parameters

Name	Type	Description
`graph_id`required	string	Graph Id

Header parameters

Name	Type	Description
`Idempotency-Key`optional	string	Idempotency-Key

Request body

Required, application/json.

Field Type Description

Field	Type	Description
`file_name`required	string	The file's name, ending in its type's extension (`.pdf`, `.png`, `.jpg` or `.jpeg`). Constraints: 1–255 characters
`content_type`optional	string	The file's media type. One of: `application/pdf`, `image/png`, `image/jpeg` Default: `application/pdf`
`file_size_bytes`optional	integer	The file's exact size in bytes, at most 25 MB. When given it is signed into the upload URL, so an upload of any other size fails. Completing the upload checks the size either way. Constraints: at most 26214400; greater than 0

file_namerequired

string

The file's name, ending in its type's extension (.pdf, .png, .jpg or .jpeg).

Constraints: 1–255 characters

content_typeoptional

string

The file's media type.

One of: application/pdf, image/png, image/jpeg

Default: application/pdf

file_size_bytesoptional

integer

The file's exact size in bytes, at most 25 MB. When given it is signed into the upload URL, so an upload of any other size fails. Completing the upload checks the size either way.

Constraints: at most 26214400; greater than 0

Example request

curl

curl -X POST "https://api.robosystems.ai/v1/graphs/{graph_id}/operations/create-document-upload" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "file_name": "string"
}'

Responses

200 Successful Response

Field	Type	Description
`operation`required	string	Kebab-case operation name
`operationId`required	string	op_-prefixed ULID for audit and SSE correlation
`status`required	string	Operation lifecycle state One of: `completed`, `pending`, `failed`
`result`optional	any	Command-specific result payload
`at`required	string	ISO-8601 UTC timestamp
`createdBy`optional	string	User ID that initiated the operation
`idempotentReplay`optional	boolean	True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions. Default: `false`

Status	Meaning
400	Invalid request
401	Authentication required
403	Access denied
404	Resource not found
409	Idempotency-Key conflict — key reused with different body
422	Validation error
429	Rate limit exceeded
500	Internal server error