---
title: "Create a context_attachment from a file upload (≤80KB)"
method: POST
path: "/documents/{document_id}/context-attachments/upload"
tags: ["context-attachments"]
---

# Create a context_attachment from a file upload (≤80KB)

`POST /documents/{document_id}/context-attachments/upload`

Create a context_attachment on the given document via multipart form-data. Use this when the payload exceeds 16 KB; for smaller inline text payloads use the JSON-body variant of this endpoint.

The uploaded file MUST be valid UTF-8 text — extraction injects the raw bytes into the LLM prompt, so non-UTF-8 binaries cannot be decoded.

## Path parameters

- `document_id` string, uuid, required

## Response `201`

Attachment created and stored

- ContextAttachment — Persisted attachment item — used as both repository row shape and response body for create/list endpoints. DynamoDB key layout: PK = WORKSPACE#{workspace_id} SK = CONTEXTATTACH#{document_id}#{attachment_id} Listing all attachments for a document is a single ``Query(PK = WORKSPACE#..., SK begins_with CONTEXTATTACH#{document_id}#)``. Deletion by attachment_id reconstructs the SK from the path (``/documents/{document_id}/context-attachments/{attachment_id}``) — no GSI lookup required.
  - `attachment_id` string, uuid — UUIDv7 — chronologically sortable. Stable order for prompt assembly.
  - `workspace_id` string, uuid, required — Owning workspace; multi-tenant isolation key.
  - `document_id` string, uuid, required — Document this attachment travels with.
  - `type` 'author_note' | 'json_schema', required — Vocabulary label (see CreateRequest).
  - `name` string, required
  - `content_text` string, nullable — Set for inline (≤16KB) attachments. Mutually exclusive with s3_key — see the model_validator below.
  - `s3_key` string, 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_size` integer, required — Encoded UTF-8 byte size of the payload. Used for cap math at extract time.
  - `created_at` string, date-time

## Other responses

- `404` — Document not found in workspace
- `413` — File exceeds 80 KB
- `422` — Validation error (cap exceeded, invalid UTF-8, unknown mime_type or type, etc.)

---

[API](https://skmtc.dev/scipot/apis/scipot-core-api.md) · [All operations](https://skmtc.dev/scipot/apis/scipot-core-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/scipot/scipot-core-api/revisions/e8712e9ffeae/schema)