Sign in

v2

latestOpenAPI 3.1.02026-08-0382170235.8 KB
context-attachments

Create a context_attachment from an inline text payload (≤16KB)

Create a context_attachment on the given document using a JSON body. For payloads larger than 16 KB use the multipart /upload variant of this endpoint.

Channel vs type: any type value (author_note or json_schema) can be created via either channel — the channel is a function of payload size, not attachment kind.

Note on the 16 KB cap: byte-size enforcement happens at the Pydantic validator layer (before the route handler runs), so oversized content_text surfaces as a 422 with the Pydantic error detail, not the route's stable {code, ...} shape. The multipart /upload path emits 413 ATTACHMENT_FILE_TOO_LARGE in-handler when its 80 KB cap is exceeded — that's the dedicated stable code for oversize payloads. Inline >16KB is a 422.

post/documents/{document_id}/context-attachments

Path parameters

document_idstring uuid required

Request body

type'author_note' | 'json_schema' required

Vocabulary label for the attachment. scipot-core does NOT interpret the payload by type — both kinds are opaque typed strings to the extraction pipeline. The label flows into the prompt framing ('=== [json_schema: Eightfold v3] ===').

namestring required

Human-readable label shown to curators ('Eightfold schema v3').

content_textstring required

Inline UTF-8 text payload. Max 16 KB by encoded byte size. Payloads larger than 16 KB are rejected by this schema's validator and surface as a 422 with the Pydantic error detail — use the multipart /upload variant of the endpoint for larger payloads (it returns 413 ATTACHMENT_FILE_TOO_LARGE for files > 80 KB).

mime_type'text/plain' | 'application/json' | 'application/schema+json' nullable

Optional MIME type. Defaults to 'text/plain' for author_note and 'application/schema+json' for json_schema when omitted.

Response

Attachment created

attachment_idstring uuid

UUIDv7 — chronologically sortable. Stable order for prompt assembly.

workspace_idstring uuid required

Owning workspace; multi-tenant isolation key.

document_idstring uuid required

Document this attachment travels with.

type'author_note' | 'json_schema' required

Vocabulary label (see CreateRequest).

namestring required
content_textstring nullable

Set for inline (≤16KB) attachments. Mutually exclusive with s3_key — see the model_validator below.

s3_keystring nullable

Set for >16KB attachments stored on the FileStorageBackend. Mutually exclusive with content_text. The repository computes this; callers never set it via the create endpoint.

mime_type'text/plain' | 'application/json' | 'application/schema+json' required

MIME type of the payload (text/plain | application/json | application/schema+json).

byte_sizeinteger required

Encoded UTF-8 byte size of the payload. Used for cap math at extract time.

created_atstring date-time