CloudPrint Public API overview
Use this page as the map of the Public API. The task guides explain decisions and production behavior; the OpenAPI reference remains the canonical source for every schema field and response.
Base URL and API boundary
All external backend calls use https://public-api.cloudprint.me. Account owners connect agents and create client apps in https://my.cloudprint.me. The installed agent has a private protocol and is not a customer API.
Complete resource map
| Method | Path | Scope | Purpose |
|---|---|---|---|
POST | /oauth/token | — | Obtain an OAuth2 access token |
GET | /api/v1/me | authenticated | Confirm account, client app and granted scopes |
GET | /api/v1/agents | agents:read | Check agent state and version |
GET | /api/v1/printers | printers:read | Discover printers and capabilities |
POST | /api/v1/documents | documents:write | Upload PDF or RAW data |
POST | /api/v1/print-jobs | print_jobs:write | Create a job for an uploaded document |
POST | /api/v1/print-jobs/from-url | print_jobs:write | Fetch a public HTTPS document and create a job |
POST | /api/v1/print-jobs/from-base64 | print_jobs:write | Decode inline bytes and create a job |
GET | /api/v1/print-jobs | print_jobs:read | List jobs with cursor pagination |
GET | /api/v1/print-jobs/{printJobId} | print_jobs:read | Read one job and its result |
Recommended implementation order
Implement token acquisition and /me first, then printer onboarding, document upload, idempotent job creation and status polling. Add the URL and Base64 shortcuts only when the two-step flow works. Use GET /api/v1/agents for operational diagnostics and GET /api/v1/print-jobs to reconcile history.
Pagination
Agents, printers and print-job lists use cursor pagination. Send limit (1–100) and then pass the returned opaque next_cursor as the next request's cursor. Stop when next_cursor is null; do not parse or construct cursor values.
Compatibility contract
The stable path is /api/v1. Ignore unknown response fields and treat unknown job statuses as non-terminal. Use exact enum values and validation limits from OpenAPI. Breaking changes require a new major path; additive fields may appear in v1.
Which page answers which question
Use authentication for tokens and scopes, agents and printers for routing, documents for PDF/RAW input, print jobs for retries and statuses, and the OpenAPI reference for exact schemas.
Production checklist
- Keep API credentials on the backend and scope them to the owning account.
- Store the stable printer identity instead of relying only on a display name.
- Validate document format, page size and orientation before creating the job.
- Handle terminal status, retry policy and duplicate-print protection explicitly.