Skip to main content
POST
Reserve an attachment for a direct upload

Behavior

Reserve is step one of three. PUT the file’s bytes to upload_url (no Authorization header; the URL expires in 15 minutes and can write only this one file), then call finalize. The record stays storing until finalize and becomes eligible for removal one hour after reserve if never finalized; the daily cleanup pass removes it. See Attachments.

Authorizations

Authorization
string
header
required

Send the key as Authorization: Bearer <key>. Two kinds of key exist.

Organization keys are issued in the portal (Settings, then API keys), each bound to one environment, shaped nx_<environment slug>_<64 hex>. They carry no capabilities and pass every capability check, with one exception: routes under /api/v1/records, /api/v1/engines/{id}/opportunities, /api/v1/graph and /api/v1/catalog/documents accept an organization key only when its environment is live, and refuse any other with 403 scoped_key_required. Revocation takes effect within 60 seconds.

Scoped keys are issued by Nexio on request, shaped nxsk_v1_<24 hex key id>_<43 character secret>. Each is bound to one org, one environment, a set of engines and a set of capabilities. A malformed, unknown or revoked nxsk_ key fails with 401 and is never retried as an organization key. Revocation takes effect on the next request. A scoped key without a route's capability gets 403 insufficient_capability; a scoped key not bound to the engine gets 403 engine_binding_forbidden.

Key-grantable capabilities: engines:read, runs:write, runs:read, runs:defensibility:read, runs:test, catalog:read, catalog:documents:read, webhooks:manage, conversations:use, conversations:export, records:read, records:opportunities:run, actions:write, actions:read, graph:read, records:analyze.

Routes that accept organization keys only (every scoped key gets 403 insufficient_capability): environment management, engine create, update, configuration and publish, and conversation instance authoring. Each operation description names the capability a scoped key needs.

Path Parameters

instance_slug
string
required

Conversation instance identifier slug (e.g. platform-assistant).

conversation_id
string<uuid>
required

Body

application/json
end_user
string
required

The asserted end-user identity the conversation must belong to.

filename
string
required

File name. May carry directories; each segment is cleaned and traversal segments are dropped. The extension decides the media type.

size_bytes
integer<int64>
required

Declared size in bytes. Zero or less is refused as an empty file.

Required range: x >= 1
content_type
string

Declared media type. Used only when the name has no extension.

Response

The reserved record and its upload URL.

One reserved attachment record plus the write grant for its bytes.

attachment
object
required

One file attached to a conversation. There is no text field: the platform does not parse the document, it hands the bytes to the model.

upload_url
string<uri>
required

Presigned PUT URL for this one file. Send the raw bytes with no Authorization header. It cannot read and cannot reach any other file.

upload_url_expires_at
string<date-time>
required

When upload_url stops working, 15 minutes after it was issued.

source_path
string

For a folder member, the path your request sent for it, echoed verbatim. Absent on a standalone reservation.

Last modified on September 25, 2026