{ "openapi": "3.1.0", "info": { "title": "CloudPrint Public API", "version": "latest", "description": "CloudPrint lets backend systems print PDF documents, receipts and labels on printers\nthat stay inside a customer's office, store, branch or warehouse.\n\n## Quick start\n\n1. Create a client app in the CloudPrint account UI and store the `client_id`\n and one-time `client_secret` on your backend.\n2. Request an OAuth2 Client Credentials token from `POST /oauth/token`.\n3. Call `GET /api/v1/agents` and `GET /api/v1/printers` to confirm the local agent and target printer are online.\n4. Save the stable `printer_id` selected for each business workflow.\n5. Upload a PDF or explicit RAW printer-language payload with `POST /api/v1/documents`.\n6. Create the print job with `POST /api/v1/print-jobs`.\n If uploading first is awkward, use `POST /api/v1/print-jobs/from-url` or\n `POST /api/v1/print-jobs/from-base64`; both shortcuts create a normal document\n and print job in one request.\n7. Poll `GET /api/v1/print-jobs/{printJobId}` until the job is `printed` or `failed`.\n\n## Authentication\n\nUse `Authorization: Bearer ` on every endpoint except `POST /oauth/token`.\nTokens are short-lived, so cache them until shortly before `expires_in` instead\nof requesting a new token for every print job.\n\n## Requests and errors\n\nSend JSON for print jobs, `multipart/form-data` for document uploads and\n`application/x-www-form-urlencoded` for token requests.\nEvery response includes `X-Request-Id`; log it with your own order or shipment\nid so support can trace the same request.\nErrors use `error`, `error_code`, `message` and optional structured `details`.\n\n## Versioning\n\n`latest` points to the current public API reference. The stable contract is still pinned in the URL as `/api/v1`.\nAdditive changes can appear in `v1`; breaking changes will use a new major path such as `/api/v2`." }, "servers": [ { "url": "https://public-api.cloudprint.me", "description": "Production" } ], "paths": { "/api/v1/me": { "get": { "tags": [ "Auth" ], "summary": "Get current API client context", "operationId": "getApiClientContext", "responses": { "200": { "description": "Current API client context", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientContext" } } } }, "401": { "description": "OAuth bearer token is invalid" }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "description": "Use this endpoint during setup checks to confirm which account, client app and scopes the current token represents.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.me/api/v1/me \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"" } ] } }, "/api/v1/agents": { "get": { "tags": [ "Agents" ], "summary": "List account print agents", "operationId": "listAgents", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of agents to return.", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100, "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Cursor from the previous response next_cursor field.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Account print agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentList" } } } }, "401": { "description": "OAuth bearer token is invalid" }, "403": { "description": "OAuth bearer token does not include agents:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected error" } }, "security": [ { "BearerAuth": [] } ], "description": "List local print agents connected to the account. Use `status`, `version` and `update` to show operators whether the desktop agent is online and whether it should be updated before printing.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS 'https://public-api.cloudprint.me/api/v1/agents?limit=50' \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"" } ] } }, "/oauth/token": { "post": { "tags": [ "Auth" ], "summary": "Issue OAuth2 access token using client credentials", "operationId": "issueOAuthToken", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "required": [ "grant_type", "client_id", "client_secret" ], "properties": { "grant_type": { "type": "string", "example": "client_credentials" }, "client_id": { "type": "string", "format": "uuid" }, "client_secret": { "type": "string" }, "scope": { "description": "Space-separated scopes. The token request is rejected when any requested scope is unknown or not granted to the client app.", "type": "string", "example": "agents:read printers:read documents:write print_jobs:write print_jobs:read" } }, "type": "object" } } } }, "responses": { "200": { "description": "Access token issued", "content": { "application/json": { "schema": { "type": "object", "required": [ "token_type", "expires_in", "access_token" ], "properties": { "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "type": "integer", "example": 900 }, "access_token": { "type": "string", "example": "eyJ..." } } } } } }, "400": { "description": "Invalid OAuth2 request" }, "401": { "description": "Invalid OAuth2 client credentials" }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Exchange a client app id and secret for a short-lived Bearer token. Request only the scopes needed by the current integration. Unknown or ungranted scopes are rejected.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.me/oauth/token \\\n -H 'Content-Type: application/x-www-form-urlencoded' \\\n --data-urlencode 'grant_type=client_credentials' \\\n --data-urlencode 'client_id=33333333-3333-4333-8333-333333333333' \\\n --data-urlencode 'client_secret=cpsec_...' \\\n --data-urlencode 'scope=agents:read printers:read documents:write print_jobs:write print_jobs:read'" }, { "lang": "PHP", "source": " [\n 'method' => 'POST',\n 'header' => \"Content-Type: application/x-www-form-urlencoded\\r\\n\",\n 'content' => http_build_query([\n 'grant_type' => 'client_credentials',\n 'client_id' => getenv('CLOUDPRINT_CLIENT_ID'),\n 'client_secret' => getenv('CLOUDPRINT_CLIENT_SECRET'),\n 'scope' => 'agents:read printers:read documents:write print_jobs:write print_jobs:read',\n ]),\n ],\n]));\n\n$token = json_decode((string) $response, true, flags: JSON_THROW_ON_ERROR)['access_token'];" } ] } }, "/api/v1/documents": { "post": { "tags": [ "Documents" ], "summary": "Upload document for printing", "operationId": "uploadDocument", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "description": "Supported file types: PDF and explicit RAW printer payloads. Convert DOC and DOCX files to PDF before uploading.", "type": "string", "format": "binary" }, "document_format": { "type": [ "string", "null" ], "enum": [ "pdf", "raw" ], "example": "raw" }, "document_raw_language": { "type": [ "string", "null" ], "enum": [ "tspl", "zpl", "cpcl", "escpos" ], "example": "zpl" } }, "type": "object" } } } }, "responses": { "201": { "description": "Document uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadedDocument" } } } }, "400": { "description": "Invalid upload request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Uploaded file is too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Uploaded file type is not supported by the Public API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Document validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected error" } }, "security": [ { "BearerAuth": [] } ], "description": "Upload the file before creating a print job. PDF is the default document format. For RAW printing, send `document_format=raw` and an explicit `document_raw_language` such as `zpl`.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.me/api/v1/documents \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n -F \"file=@shipping-label.pdf\"" } ] } }, "/api/v1/print-jobs": { "get": { "tags": [ "Print jobs" ], "summary": "List print jobs", "operationId": "listPrintJobs", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of print jobs to return.", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Cursor from the previous response next_cursor field.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Print jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJobList" } } } }, "401": { "description": "OAuth bearer token is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "OAuth bearer token does not include print_jobs:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "description": "List recent print jobs with cursor pagination. Use this for operational screens and support tools.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS 'https://public-api.cloudprint.me/api/v1/print-jobs?limit=20' \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"" } ] }, "post": { "tags": [ "Print jobs" ], "summary": "Create print job", "operationId": "createPrintJob", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional key that prevents duplicate print jobs for the same account and payload.", "required": false, "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePrintJobRequest" } } } }, "responses": { "201": { "description": "Print job created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJob" } } } }, "409": { "description": "Idempotency key conflict or unsupported print route. Unsupported routes include details.reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Print job validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected error" } }, "security": [ { "BearerAuth": [] } ], "description": "Create a print job for an uploaded document and a selected printer. Send an `Idempotency-Key` when retrying after network failures to avoid duplicate prints.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.me/api/v1/print-jobs \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n -H 'Content-Type: application/json' \\\n -H 'Idempotency-Key: order-100045-label' \\\n -d '{\n \"document_id\": \"44444444-4444-4444-8444-444444444444\",\n \"printer_id\": \"11111111-1111-4111-8111-111111111111\",\n \"copies\": 1,\n \"intent\": \"shipping_label\",\n \"media_width_mm\": 58,\n \"media_height_mm\": 40,\n \"dpi\": 203\n }'" }, { "lang": "PHP", "source": " '44444444-4444-4444-8444-444444444444',\n 'printer_id' => '11111111-1111-4111-8111-111111111111',\n 'copies' => 1,\n 'intent' => 'shipping_label',\n 'media_width_mm' => 58,\n 'media_height_mm' => 40,\n 'dpi' => 203,\n], JSON_THROW_ON_ERROR);\n\n$response = file_get_contents('https://public-api.cloudprint.me/api/v1/print-jobs', false, stream_context_create([\n 'http' => [\n 'method' => 'POST',\n 'header' => [\n 'Authorization: Bearer ' . getenv('CLOUDPRINT_ACCESS_TOKEN'),\n 'Content-Type: application/json',\n 'Idempotency-Key: order-100045-label',\n ],\n 'content' => $payload,\n ],\n]));\n\n$printJob = json_decode((string) $response, true, flags: JSON_THROW_ON_ERROR);" } ] } }, "/api/v1/print-jobs/from-base64": { "post": { "tags": [ "Print jobs" ], "summary": "Create print job from base64 document", "operationId": "createPrintJobFromBase64", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional key that prevents duplicate print jobs for the same account and payload.", "required": false, "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePrintJobFromBase64Request" } } } }, "responses": { "201": { "description": "Print job created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJob" } } } }, "400": { "description": "Invalid base64 request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Idempotency key conflict or unsupported print route. Unsupported routes include details.reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Document is too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Document type is not supported by the Public API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Print job validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected error" } }, "security": [ { "BearerAuth": [] } ], "description": "Decode a base64 document, store it as a normal CloudPrint document and create the print job in one request. Use this only when direct multipart upload or HTTPS URL download is not practical, because base64 increases request size.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.me/api/v1/print-jobs/from-base64 \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n -H 'Content-Type: application/json' \\\n -H 'Idempotency-Key: order-100045-label' \\\n -d '{\n \"document_base64\": \"JVBERi0xLjQK...\",\n \"document_filename\": \"order-100045.pdf\",\n \"printer_id\": \"11111111-1111-4111-8111-111111111111\",\n \"copies\": 1,\n \"intent\": \"shipping_label\",\n \"media_width_mm\": 58,\n \"media_height_mm\": 40,\n \"dpi\": 203\n }'" } ] } }, "/api/v1/print-jobs/from-url": { "post": { "tags": [ "Print jobs" ], "summary": "Create print job from document URL", "operationId": "createPrintJobFromUrl", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional key that prevents duplicate print jobs for the same account and payload.", "required": false, "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePrintJobFromUrlRequest" } } } }, "responses": { "201": { "description": "Print job created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJob" } } } }, "400": { "description": "Invalid URL request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Idempotency key conflict or unsupported print route. Unsupported routes include details.reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Remote document is too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Document type is not supported by the Public API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Remote document or print job validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected error" } }, "security": [ { "BearerAuth": [] } ], "description": "Download a document from a public HTTPS URL, store it as a normal CloudPrint document and create the print job in one request. Local, private-network and credentialed URLs are rejected.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.me/api/v1/print-jobs/from-url \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n -H 'Content-Type: application/json' \\\n -H 'Idempotency-Key: order-100045-label' \\\n -d '{\n \"document_url\": \"https://files.example.com/labels/order-100045.pdf\",\n \"document_filename\": \"order-100045.pdf\",\n \"printer_id\": \"11111111-1111-4111-8111-111111111111\",\n \"copies\": 1,\n \"intent\": \"shipping_label\",\n \"media_width_mm\": 58,\n \"media_height_mm\": 40,\n \"dpi\": 203\n }'" } ] } }, "/api/v1/print-jobs/{printJobId}": { "get": { "tags": [ "Print jobs" ], "summary": "Get print job status", "operationId": "getPrintJob", "parameters": [ { "name": "printJobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Print job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJob" } } } }, "404": { "description": "Print job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected error" } }, "security": [ { "BearerAuth": [] } ], "description": "Poll a single print job until it reaches a terminal status. Treat `printed` as success and `failed` as an operator-visible failure that may need support action.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.me/api/v1/print-jobs/55555555-5555-4555-8555-555555555555 \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"" } ] } }, "/api/v1/printers": { "get": { "tags": [ "Printers" ], "summary": "List account printers", "operationId": "listPrinters", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of printers to return.", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 100, "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Cursor from the previous response next_cursor field.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Account printers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrinterList" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected error" } }, "security": [ { "BearerAuth": [] } ], "description": "List printers visible to the account. Store `printer_id` rather than local printer names. Use `status`, `capabilities` and `endpoint` to decide whether a printer can be offered for a workflow.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS 'https://public-api.cloudprint.me/api/v1/printers?limit=100' \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"" } ] } } }, "components": { "schemas": { "ApiClientContext": { "required": [ "account_id", "account_name", "client_app_id", "client_app_name", "scopes" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "account_name": { "type": "string", "example": "Acme Print Ops" }, "client_app_id": { "type": "string", "format": "uuid" }, "client_app_name": { "type": "string", "example": "Warehouse integration" }, "scopes": { "type": "array", "items": { "type": "string" }, "example": [ "agents:read", "printers:read", "documents:write", "print_jobs:write", "print_jobs:read" ] } }, "type": "object" }, "UploadedDocument": { "required": [ "document_id", "original_filename", "mime_type", "document_format", "document_raw_language", "size_bytes" ], "properties": { "document_id": { "type": "string", "format": "uuid" }, "original_filename": { "type": "string", "example": "invoice.pdf" }, "mime_type": { "type": "string", "example": "application/pdf" }, "document_format": { "type": "string", "enum": [ "pdf", "raw" ], "example": "pdf" }, "document_raw_language": { "type": [ "string", "null" ], "enum": [ "tspl", "zpl", "cpcl", "escpos" ], "example": null }, "size_bytes": { "type": "integer", "example": 1024 } }, "type": "object" }, "CreatePrintJobRequest": { "required": [ "document_id", "printer_id" ], "properties": { "document_id": { "type": "string", "format": "uuid" }, "printer_id": { "type": "string", "format": "uuid" }, "copies": { "type": "integer", "minimum": 1, "example": 1 }, "intent": { "type": "string", "enum": [ "document", "shipping_label", "product_label", "invoice", "packing_slip", "a4_document", "receipt" ], "example": "shipping_label" }, "color_mode": { "type": "string", "enum": [ "default", "monochrome", "color" ], "example": "default" }, "duplex_mode": { "type": "string", "enum": [ "default", "simplex", "duplex_long_edge", "duplex_short_edge" ], "example": "default" }, "media_width_mm": { "type": [ "number", "null" ], "example": 58 }, "media_height_mm": { "type": [ "number", "null" ], "example": 40 }, "dpi": { "type": [ "integer", "null" ], "example": 203 }, "scale_mode": { "type": "string", "enum": [ "none", "fit" ], "example": "none" }, "orientation": { "type": "string", "enum": [ "default", "portrait", "landscape" ], "example": "default" }, "offset_x_mm": { "type": "number", "example": 0 }, "offset_y_mm": { "type": "number", "example": 0 }, "margin_top_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_right_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_bottom_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_left_mm": { "type": "number", "minimum": 0, "example": 0 } }, "type": "object" }, "CreatePrintJobFromUrlRequest": { "required": [ "document_url", "printer_id" ], "properties": { "document_url": { "description": "HTTPS URL of the document to download. Local and private network hosts are rejected.", "type": "string", "format": "uri", "example": "https://files.example.com/labels/order-100045.pdf" }, "document_filename": { "description": "Optional filename used for diagnostics and document metadata.", "type": [ "string", "null" ], "example": "order-100045.pdf" }, "document_format": { "type": [ "string", "null" ], "enum": [ "pdf", "raw" ], "example": "pdf" }, "document_raw_language": { "type": [ "string", "null" ], "enum": [ "tspl", "zpl", "cpcl", "escpos" ], "example": null }, "printer_id": { "type": "string", "format": "uuid" }, "copies": { "type": "integer", "minimum": 1, "example": 1 }, "intent": { "type": "string", "enum": [ "document", "shipping_label", "product_label", "invoice", "packing_slip", "a4_document", "receipt" ], "example": "shipping_label" }, "color_mode": { "type": "string", "enum": [ "default", "monochrome", "color" ], "example": "default" }, "duplex_mode": { "type": "string", "enum": [ "default", "simplex", "duplex_long_edge", "duplex_short_edge" ], "example": "default" }, "media_width_mm": { "type": [ "number", "null" ], "example": 58 }, "media_height_mm": { "type": [ "number", "null" ], "example": 40 }, "dpi": { "type": [ "integer", "null" ], "example": 203 }, "scale_mode": { "type": "string", "enum": [ "none", "fit" ], "example": "none" }, "orientation": { "type": "string", "enum": [ "default", "portrait", "landscape" ], "example": "default" }, "offset_x_mm": { "type": "number", "example": 0 }, "offset_y_mm": { "type": "number", "example": 0 }, "margin_top_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_right_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_bottom_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_left_mm": { "type": "number", "minimum": 0, "example": 0 } }, "type": "object" }, "CreatePrintJobFromBase64Request": { "required": [ "document_base64", "printer_id" ], "properties": { "document_base64": { "description": "Base64-encoded document bytes.", "type": "string", "format": "byte" }, "document_filename": { "description": "Optional filename used for diagnostics and document metadata.", "type": [ "string", "null" ], "example": "order-100045.pdf" }, "document_format": { "type": [ "string", "null" ], "enum": [ "pdf", "raw" ], "example": "pdf" }, "document_raw_language": { "type": [ "string", "null" ], "enum": [ "tspl", "zpl", "cpcl", "escpos" ], "example": null }, "printer_id": { "type": "string", "format": "uuid" }, "copies": { "type": "integer", "minimum": 1, "example": 1 }, "intent": { "type": "string", "enum": [ "document", "shipping_label", "product_label", "invoice", "packing_slip", "a4_document", "receipt" ], "example": "shipping_label" }, "color_mode": { "type": "string", "enum": [ "default", "monochrome", "color" ], "example": "default" }, "duplex_mode": { "type": "string", "enum": [ "default", "simplex", "duplex_long_edge", "duplex_short_edge" ], "example": "default" }, "media_width_mm": { "type": [ "number", "null" ], "example": 58 }, "media_height_mm": { "type": [ "number", "null" ], "example": 40 }, "dpi": { "type": [ "integer", "null" ], "example": 203 }, "scale_mode": { "type": "string", "enum": [ "none", "fit" ], "example": "none" }, "orientation": { "type": "string", "enum": [ "default", "portrait", "landscape" ], "example": "default" }, "offset_x_mm": { "type": "number", "example": 0 }, "offset_y_mm": { "type": "number", "example": 0 }, "margin_top_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_right_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_bottom_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_left_mm": { "type": "number", "minimum": 0, "example": 0 } }, "type": "object" }, "PrintJob": { "required": [ "print_job_id", "document_id", "document_mime_type", "document_format", "document_raw_language", "printer_id", "status", "copies", "intent", "color_mode", "duplex_mode", "scale_mode", "orientation", "offset_x_mm", "offset_y_mm", "margin_top_mm", "margin_right_mm", "margin_bottom_mm", "margin_left_mm" ], "properties": { "print_job_id": { "type": "string", "format": "uuid" }, "document_id": { "type": "string", "format": "uuid" }, "document_mime_type": { "type": "string", "example": "application/pdf" }, "document_format": { "type": "string", "enum": [ "pdf", "raw" ], "example": "pdf" }, "document_raw_language": { "type": [ "string", "null" ], "enum": [ "tspl", "zpl", "cpcl", "escpos" ], "example": null }, "printer_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "pending" }, "copies": { "type": "integer", "example": 1 }, "intent": { "type": "string", "enum": [ "document", "shipping_label", "product_label", "invoice", "packing_slip", "a4_document", "receipt" ], "example": "shipping_label" }, "color_mode": { "type": "string", "enum": [ "default", "monochrome", "color" ], "example": "default" }, "duplex_mode": { "type": "string", "enum": [ "default", "simplex", "duplex_long_edge", "duplex_short_edge" ], "example": "default" }, "media_width_mm": { "type": [ "number", "null" ], "example": 58 }, "media_height_mm": { "type": [ "number", "null" ], "example": 40 }, "dpi": { "type": [ "integer", "null" ], "example": 203 }, "scale_mode": { "type": "string", "enum": [ "none", "fit" ], "example": "none" }, "orientation": { "type": "string", "enum": [ "default", "portrait", "landscape" ], "example": "default" }, "offset_x_mm": { "type": "number", "example": 0 }, "offset_y_mm": { "type": "number", "example": 0 }, "margin_top_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_right_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_bottom_mm": { "type": "number", "minimum": 0, "example": 0 }, "margin_left_mm": { "type": "number", "minimum": 0, "example": 0 }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "reserved_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "failure_reason": { "type": [ "string", "null" ] } }, "type": "object" }, "PrintJobList": { "required": [ "print_jobs", "next_cursor" ], "properties": { "print_jobs": { "type": "array", "items": { "$ref": "#/components/schemas/PrintJob" } }, "next_cursor": { "type": [ "string", "null" ] } }, "type": "object" }, "PrinterCapabilities": { "required": [ "backend", "language_profiles", "supports_custom_media", "supports_orientation", "supports_copies", "supports_duplex", "supports_color", "supports_scaling", "supports_offsets", "supports_printable_area", "supported_dpi", "supported_media_sizes", "supported_feed_types", "darkness_min", "darkness_max", "speed_min", "speed_max" ], "properties": { "backend": { "type": "string", "enum": [ "cups", "windows_native", "custom_command", "simulate" ], "example": "windows_native" }, "language_profiles": { "type": "array", "items": { "required": [ "language", "supported_commands", "compression_modes" ], "properties": { "language": { "type": "string", "enum": [ "tspl", "zpl", "cpcl", "escpos" ], "example": "zpl" }, "version": { "type": [ "string", "null" ], "example": "zpl2" }, "supported_commands": { "type": "array", "items": { "type": "string", "example": "gf" } }, "max_bitmap_width_dots": { "type": [ "integer", "null" ], "minimum": 1, "example": 812 }, "max_bitmap_height_dots": { "type": [ "integer", "null" ], "minimum": 1, "example": 1199 }, "compression_modes": { "type": "array", "items": { "type": "string", "example": "ascii-hex" } }, "codepage": { "type": [ "string", "null" ], "example": "utf-8" } }, "type": "object" } }, "supports_custom_media": { "type": "boolean" }, "supports_orientation": { "type": "boolean" }, "supports_copies": { "type": "boolean" }, "supports_duplex": { "type": "boolean" }, "supports_color": { "type": "boolean" }, "supports_scaling": { "type": "boolean" }, "supports_offsets": { "type": "boolean" }, "supports_printable_area": { "type": "boolean" }, "supported_dpi": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "supported_media_sizes": { "type": "array", "items": { "required": [ "width_mm", "height_mm" ], "properties": { "width_mm": { "type": "number", "format": "float" }, "height_mm": { "type": "number", "format": "float" } }, "type": "object" } }, "supported_feed_types": { "type": "array", "items": { "type": "string", "example": "gap" } }, "darkness_min": { "type": [ "integer", "null" ], "example": 0 }, "darkness_max": { "type": [ "integer", "null" ], "example": 30 }, "speed_min": { "type": [ "integer", "null" ], "example": 1 }, "speed_max": { "type": [ "integer", "null" ], "example": 14 } }, "type": "object" }, "PrinterEndpoint": { "required": [ "system_print_available", "raw_passthrough_available", "os", "driver_name", "port_name", "print_processor", "data_type", "connection_type", "default_media_profile_id", "default_media_profile" ], "properties": { "system_print_available": { "type": "boolean" }, "raw_passthrough_available": { "type": "boolean" }, "configuration_issue": { "type": [ "string", "null" ], "enum": [ "interactive_output_port" ] }, "os": { "type": [ "string", "null" ], "example": "linux" }, "driver_name": { "type": [ "string", "null" ], "example": "CUPS" }, "port_name": { "type": [ "string", "null" ], "example": "ipp://printer.local/ipp/print" }, "print_processor": { "type": [ "string", "null" ], "example": "cups" }, "data_type": { "type": [ "string", "null" ], "example": "RAW" }, "connection_type": { "type": [ "string", "null" ], "example": "cups" }, "default_media_profile_id": { "type": [ "string", "null" ] }, "default_media_profile": { "properties": { "width_mm": { "type": "number", "format": "float", "example": 100 }, "height_mm": { "type": "number", "format": "float", "example": 150 }, "dpi": { "type": "integer", "example": 203 }, "orientation": { "type": "string", "enum": [ "default", "portrait", "landscape" ] }, "feed_type": { "type": [ "string", "null" ], "example": "gap" }, "darkness": { "type": [ "integer", "null" ], "example": 15 }, "speed": { "type": [ "integer", "null" ], "example": 4 } }, "type": [ "object", "null" ] } }, "type": "object" }, "Printer": { "required": [ "printer_id", "agent_id", "local_identifier", "name", "status", "last_seen_at", "agent_name", "agent_hostname", "agent_status", "agent_last_seen_at", "capabilities", "endpoint" ], "properties": { "printer_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "local_identifier": { "type": "string", "example": "zebra-zd421-usb-001" }, "name": { "type": "string", "example": "Warehouse Label Printer" }, "status": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "agent_name": { "type": [ "string", "null" ], "example": "Warehouse PC agent" }, "agent_hostname": { "type": [ "string", "null" ], "example": "warehouse-pc" }, "agent_status": { "type": [ "string", "null" ], "example": "online" }, "agent_last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "capabilities": { "$ref": "#/components/schemas/PrinterCapabilities" }, "endpoint": { "$ref": "#/components/schemas/PrinterEndpoint" } }, "type": "object" }, "PrinterList": { "required": [ "printers", "next_cursor" ], "properties": { "printers": { "type": "array", "items": { "$ref": "#/components/schemas/Printer" } }, "next_cursor": { "type": [ "string", "null" ] } }, "type": "object" }, "AgentUpdate": { "required": [ "status", "current_version", "latest_version", "minimum_supported_version", "channel", "required" ], "properties": { "status": { "type": "string", "enum": [ "up_to_date", "available", "required", "unknown" ], "example": "available" }, "current_version": { "type": [ "string", "null" ], "example": "0.1.0" }, "latest_version": { "type": [ "string", "null" ], "example": "0.1.1" }, "minimum_supported_version": { "type": [ "string", "null" ], "example": "0.1.0" }, "channel": { "type": "string", "example": "stable" }, "required": { "type": "boolean", "example": false } }, "type": "object" }, "Agent": { "required": [ "agent_id", "name", "status", "update" ], "properties": { "agent_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Warehouse PC agent" }, "status": { "type": "string", "example": "online" }, "installation_id": { "type": [ "string", "null" ] }, "hostname": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "update": { "$ref": "#/components/schemas/AgentUpdate" }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "AgentList": { "required": [ "agents", "next_cursor" ], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "next_cursor": { "type": [ "string", "null" ] } }, "type": "object" }, "ErrorResponse": { "required": [ "error", "message" ], "properties": { "error": { "description": "Stable machine-readable error code.", "type": "string" }, "error_code": { "type": [ "string", "null" ] }, "message": { "description": "Safe human-readable error message. The message is localized by Accept-Language when a supported translation exists.", "type": "string" }, "details": { "description": "Optional machine-readable diagnostics for errors that have structured context.", "type": [ "object", "null" ], "example": { "reason": "missing_pdf_renderer" }, "additionalProperties": true } }, "type": "object" } }, "securitySchemes": { "BearerAuth": { "type": "http", "description": "OAuth2 client credentials access token.", "bearerFormat": "JWT", "scheme": "bearer" } } }, "tags": [ { "name": "Auth", "description": "Get an OAuth2 token and inspect the current client app context." }, { "name": "Printers", "description": "Discover customer printers that are visible through connected local agents." }, { "name": "Agents", "description": "Inspect connected local print agents, their status and update state." }, { "name": "Documents", "description": "Upload PDF or explicit RAW printer-language documents before creating print jobs." }, { "name": "Print jobs", "description": "Create, list and poll print jobs until they are printed or failed." } ], "externalDocs": { "description": "Step-by-step public API integration guide", "url": "https://cloudprint.me/docs/getting-started/" }, "x-tagGroups": [ { "name": "Start here", "tags": [ "Auth" ] }, { "name": "Printing workflow", "tags": [ "Agents", "Printers", "Documents", "Print jobs" ] } ] }