---
title: "Upload files into a workspace (the single ingest verb)"
method: POST
path: "/workspaces/{workspaceId}/documents"
tags: ["Workspace"]
---

# Upload files into a workspace (the single ingest verb)

`POST /workspaces/{workspaceId}/documents`

The one ingest path for every file type — base64 file bytes inside
JSON (no multipart). CSVs become new tables (`mode: "table"`, the
default for `.csv`), append into an existing table (`mode: "append"`
+ `tableId`), or store as documents (`mode: "document"`); any other
extension is stored as a document. Preflight validation is
all-or-nothing: the whole request is rejected (count cap, per-file
mode/extension/append-target) before any file is ingested. Per-file
ingestion can still fail after preflight — the response is `201` when
at least one file landed and `422 UPLOAD_FAILED` when every file
errored. Replaces the deprecated
`POST /workspaces/{workspaceId}/uploads` spelling (same contract).

## Headers

- `Idempotency-Key` string

## Request body

- UploadFilesRequest
  - `files` object[], required — Per-request file cap enforced (over it → 413 TOO_MANY_FILES).
    - `filename` string, required
    - `content` string, required — Base64-encoded file bytes.
    - `mode` 'table' | 'append' | 'document' — `table` (CSV → new table; the default for `.csv`), `append` (CSV → existing table; requires `tableId`), or `document` (force document storage).
    - `tableId` string, uuid — Required when mode is `append` — the table to append CSV rows to.

## Response `201`

Per-file ingest results ({ results: [...] }); individual entries may be kind: "error".

## Other responses

- `400` — VALIDATION_ERROR / INVALID_UPLOAD_MODE.
- `404` — WORKSPACE_NOT_FOUND / TABLE_NOT_FOUND (append target).
- `413` — TOO_MANY_FILES — over the per-request file cap.
- `422` — UPLOAD_FAILED — every file errored; details carry the per-file results.

---

[API](https://skmtc.net/origami/apis/origami-agent-api.md) · [All operations](https://skmtc.net/origami/apis/origami-agent-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/origami/origami-agent-api/versions/8083ad7fe081/schema)