{ "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`.\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" }, { "url": "https://public-api.staging.cloudprint.me", "description": "Staging" }, { "url": "http://localhost:8080", "description": "Local development" } ], "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" } } } }, "422": { "description": "Print job validation failed", "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" } } } }, "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/{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" }, "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" }, "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/" }, "x-tagGroups": [ { "name": "Start here", "tags": [ "Auth" ] }, { "name": "Printing workflow", "tags": [ "Agents", "Printers", "Documents", "Print jobs" ] } ] }