Where the specification lives
The endpoint specification is generated live from the API catalog. Use these files instead of copying endpoint lists from articles:
- Compact index for AI clients:
https://api.paperoffice.ai/latest/docs/llms.txt - Full reference:
https://api.paperoffice.ai/latest/docs/llms-full.txt - OpenAPI 3.1:
https://api.paperoffice.ai/latest/docs/openapi.json - Agent skill:
https://api.paperoffice.ai/latest/docs/skill.md - Postman collection:
https://api.paperoffice.ai/latest/docs/postman
The documentation routes are public and need no token. Import the Postman URL into Postman, VS Code or Bruno, and download it again when the documentation release changes. The production base address is https://api.paperoffice.ai/latest; use /dev only for development.
A quick start with an AI coding assistant: give it the address of llms-full.txt and describe the function you need, for example a function that sends an image and returns the recognized text.
Authentication and token types
Most product endpoints require a bearer token in the Authorization header. You create tokens in the PaperOffice app under Account → API.
- System key (po_sk_): server-to-server integration with full API access. Never use it in a browser.
- User token (po_ut_): the scope of one user, for example for MCP. Rights follow the user and the licence.
- Group token (po_gt_): inherits the rights and the workspace whitelist of a user group.
- Publishable key (po_pk_): for use in a browser. Every request needs an origin that the key owner entered, a lifetime budget caps consumption, and deleting, account administration, key management and payment changes stay blocked. It is not allowed for MCP.
Without a token, only infrastructure endpoints such as the specification, the health check and the connectivity test are reachable. A product request without a token is answered with HTTP 403 and the code TIER_RESTRICTED, not with HTTP 401.
Jobs: waiting, polling and results
Processing runs as jobs. Job paths use the pattern handler___command with three underscores, for example POST /job/add/paperoffice_aiocr___generate for text recognition. Dot notation is rejected with JOB_CONFIG_INVALID.
- By default, the request holds the connection for a while. If the job finishes in time, you get the result directly. Otherwise you get HTTP 202 with a job ID and a poll address, and the job keeps running.
- HTTP 202 is a success, not an error. Poll
GET /job/get/{job_id}every 5 to 10 seconds until the status is completed. The result is then in job_result. - With client_wait=false, you get the job ID immediately and poll from the start.
- All responses are JSON. Clients should read the stable code field, not the localized message text.
You see queued, running and completed API jobs in the app under Account → API → Job queue. The full list of error codes is in the specification; typical cases are missing or invalid parameters (400), a missing or invalid token (401), not enough Credits (402), a forbidden action (403) and too many requests (429, honour Retry-After).
Start SLA: when a job starts
The optional field processing_lane controls when a job starts in the queue, not when it finishes. client_wait controls whether the connection waits for the result; the two fields are independent.
Without processing_lane, the default of the workspace applies, otherwise best effort. Every plan includes best effort without surcharge. Faster start lanes are optional and cost more. The current lanes and their prices are available live through the API price list; details are in the API documentation.
Webhooks
Webhook endpoints receive job and account events, for example job.completed, job.failed, job.progress and events for documents, workspaces and tasks. Account notices such as an empty wallet or a revoked key are not webhook events.
- Payloads are signed with HMAC-SHA256 in the X-Paperoffice-Signature header. Compute the signature over the raw request body with your webhook secret and reject the request if it does not match.
- Webhooks are registered, listed, updated, tested and deleted through the API.
Billing and usage
API calls consume Credits from the shared pool of the organization, the same pool as the app. Some status and health queries are not charged; details are in the API documentation. Calls that are rejected because of invalid input are charged as well; rate-limited calls are not.
You see the calls with their Credits under API & Developer → API Usage: the live log shows each request, the history shows usage by date, handler and action. When Credits run out, calls are rejected until the balance is topped up or auto-refill takes effect. Rate limits depend on your plan; the current limits and the response headers are described in the API documentation. More about Credits: Billing and Credits in PaperOffice AI.
MCP: connect AI assistants
MCP connects AI assistants such as Claude, ChatGPT, Grok and Cursor directly to PaperOffice. Authentication is OAuth 2.1 or a user or group token; system keys and publishable keys are blocked for MCP. The production host is https://mcp.paperoffice.ai, with profiles such as /claude, /chatgpt, /grok, /cursor and /dms. Setup, permissions and data flow: Using PaperOffice with Claude, ChatGPT, Grok and Cursor.
Frequently asked questions
- Where do I find all endpoints? In llms.txt, llms-full.txt and the OpenAPI file. They are generated live.
- Which token should my server use? A system key, never in a browser. For a browser, use a publishable key with an origin and a budget.
- Is HTTP 202 an error? No. The job is still running; poll for the result.
- Do faster start lanes cost more? Yes. Best effort has no surcharge; the current prices are in the API price list.
- Are rejected calls charged? Calls rejected because of invalid input are charged; rate-limited calls are not.