# Upload document

> `POST /documents/document-put` · Section: Document AI — DMS · PaperOffice AI API, release `R20261020.1746`.

`POST https://api.paperoffice.ai/latest/documents/document-put`

## Overview
Upload one or more documents via **multipart/form-data** or provide a **`source_url`** (HTTPS) to fetch a file server-side.

**Workspace (required):** provide **`workspace_id`** or **`workspace_name`** (auto-creates workspace when the name is new).

On success returns **`results[]`** (one object per file with `pofid`, `documents_id`, `filename`, …) — not a top-level `pofid`.

Accepted multipart field names: `file`, `files`, `upload`, `attachment`, `document`, `UploadFiles`.

**Chaining:** On success read **results[0].pofid** (array of upload results; not top-level pofid) from the response for the next API call. Document upload/put. Optional processing_lane sets Start-SLA for AI-DMS enqueue.

**API reference:** `po-documents-upload` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file` | string | One of (`file`, `source_url`) | Multipart file field (file, files, upload, attachment, document, UploadFiles). |
| `source_url` | string | One of (`file`, `source_url`) | Alternative: HTTPS URL to download (alias: file_url, document_url). |
| `workspace_id` | integer | One of (`workspace_id`, `workspace_name`) | Target workspace ID. Required unless workspace_name is set. |
| `workspace_name` | string | One of (`workspace_id`, `workspace_name`) | Target workspace name (creates workspace if missing). Required unless workspace_id is set. Example: My Workspace. |
| `processing_mode` | string | No | Upload processing mode. |
| `ai_dms_tier` | string | No | AI-DMS processing tier: basic, premium, or ultra. (allowed: basic, premium, ultra) |
| `document_agent_enabled` | boolean | No | When true, enable document agent automation on upload. |
| `share_context` | object | No | Optional external share token JSON for uploads into a shared workspace. |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) (default: "no_sla") |

## Required alternatives

Provide **at least one** of: `file` **or** `source_url`.

Provide **at least one** of: `workspace_id` **or** `workspace_name`.

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

## Responses

Returns JSON with `status: "success"`; key fields: `results[]` with per-file `pofid` (not a top-level `pofid`); `results[].ai_dms` (accepted order) or `results[].ai_dms_billing` (refused, file still stored) and top-level `ai_dms_refused_count`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

## Essentials (all endpoints)

- **Base URL:** `https://api.paperoffice.ai/latest` · **Auth:** `Authorization: Bearer po_sk_…` or `po_ut_…` (server-side only); browser code uses `po_pk_…` with an allowlisted `Origin`. No Bearer at all on a product API returns HTTP 403 `TIER_RESTRICTED`.
- **Errors:** HTTP 4xx/5xx with `status: "error"`, `code` and `message`. Retry 429 (`Retry-After`) and 5xx with exponential backoff; do not retry validation errors.
- **Jobs:** `client_wait=true` (default) holds the connection. HTTP 202 means the job is still running — poll `GET /job/get/{job_id}` every 5–10 s until `job_status` is `completed`, then read `result ?? job_result`. `processing_lane` sets the Start-SLA; legacy `priority` is not part of the public contract.
- **Billing:** every billable product call costs at least 5 credits; read `_billing.job.credits_billed` on billed responses.
- **Mutations** use `POST` with action paths (e.g. `POST /documents/document-delete`), not HTTP `DELETE`.

---

All endpoints: [llms.txt](https://api.paperoffice.ai/latest/docs/llms.txt) · Everything in one file: [llms-full.txt](https://api.paperoffice.ai/latest/docs/llms-full.txt) · [OpenAPI 3.1](https://api.paperoffice.ai/latest/docs/openapi.json) · This page: https://api.paperoffice.ai/latest/docs/endpoints/po-documents-upload.md

*Generated 2026-10-20 from live API documentation (release `R20261020.1746`).*