{ "openapi": "3.1.0", "info": { "title": "CloudPrint Public API", "version": "v1", "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\nCloudPrint supports two server-to-server authorization models:\n\n- Account API Clients exchange account-owned `client_id` and `client_secret` values at\n `POST /oauth/token`.\n- Developer Applications authenticate with a one-time RS256 assertion at\n `POST /developer-api/v1/app-installations/{installationId}/access-tokens` and receive\n a token limited to the approved App Installation.\n\nUse the resulting `Authorization: Bearer ` on `/api/v1` resource endpoints.\nTokens are short-lived, so cache them until shortly before `expires_in` instead of\nrequesting a new token for every print job. Developer Application assertions are credentials\nfor the installation-token endpoint only; do not send them to `/api/v1` resources.\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": { "/agent-download-api/v1/installers/{filename}": { "get": { "tags": [ "Agent Downloads" ], "summary": "Download a public CloudPrint Agent installer", "operationId": "downloadPublicAgentInstaller", "parameters": [ { "name": "filename", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent installer binary", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Agent installer was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Agent release catalog is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Download one installer filename returned by the public release catalog. Verify its SHA-256 checksum before distributing it through an automated workflow.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -fL -o cloudprint-agent.pkg \\\n \"https://public-api.cloudprint.me/agent-download-api/v1/installers/$INSTALLER_FILENAME\"" } ] } }, "/agent-download-api/v1/releases": { "get": { "tags": [ "Agent Downloads" ], "summary": "List publicly downloadable CloudPrint Agent releases", "operationId": "listPublicAgentReleases", "responses": { "200": { "description": "Public Agent release catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAgentReleaseCatalog" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Agent release catalog is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "List the current official CloudPrint Agent release, installer metadata and SHA-256 checksums. This endpoint does not require CloudPrint credentials.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.me/agent-download-api/v1/releases" } ] } }, "/developer-api/v1/app-installations/{installationId}/access-tokens": { "post": { "tags": [ "Developer Platform" ], "summary": "Issue a short-lived token for an App Installation", "operationId": "issueInstallationAccessToken", "parameters": [ { "name": "installationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueInstallationAccessTokenRequest" } } } }, "responses": { "200": { "description": "Installation Access Token issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedInstallationAccessToken" } } } }, "401": { "description": "Application assertion is missing, invalid or already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Installation is inactive or requested permissions are invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "developerApplicationAssertion": [] } ], "servers": [ { "url": "https://public-api.cloudprint.me", "description": "Production" } ], "description": "Authenticate the Developer Application with a one-time RS256 assertion and issue a short-lived token for one active App Installation. The token is limited to the installation CloudPrint Account and a subset of its approved permissions. No refresh token is issued, and issuing a new token does not revoke existing tokens.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.me/developer-api/v1/app-installations/$INSTALLATION_ID/access-tokens \\\n -H \"Authorization: Bearer $APPLICATION_ASSERTION\" \\\n -H 'Content-Type: application/json' \\\n -d '{\"permissions\":[\"documents:write\",\"print_jobs:write\"]}'" } ] } }, "/partner-api/v1/accounts/{relationshipId}/{action}": { "post": { "tags": [ "Partner Management" ], "summary": "Suspend, resume or permanently close a managed customer relationship", "operationId": "changePartnerManagedAccountState", "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "suspend", "resume", "close" ] } } ], "responses": { "200": { "description": "Managed Account lifecycle updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerManagedAccount" } } } }, "401": { "description": "Application assertion is missing, invalid or already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Partner capability is not granted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Managed Account was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Relationship ID or lifecycle action is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "developerApplicationAssertion": [] } ], "description": "Suspend, resume or permanently close a relationship owned by the authenticated Developer Application. Closing is terminal.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS -X POST \"https://public-api.cloudprint.me/partner-api/v1/accounts/$RELATIONSHIP_ID/suspend\" \\\n -H \"Authorization: Bearer $APPLICATION_ASSERTION\"" } ] } }, "/partner-api/v1/accounts": { "get": { "tags": [ "Partner Management" ], "summary": "List customer Accounts managed by the authenticated partner application", "operationId": "listPartnerManagedAccounts", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100, "minimum": 1 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "external_customer_id", "in": "query", "description": "Exact tenant identifier supplied when the managed Account was created.", "schema": { "type": "string", "maxLength": 160, "minLength": 1 } } ], "responses": { "200": { "description": "Managed Accounts page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerManagedAccountPage" } } } }, "401": { "description": "Application assertion is missing, invalid or already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Partner capability is not granted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Pagination parameters are invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "developerApplicationAssertion": [] } ], "description": "List managed customers created by the authenticated Developer Application, including agent and printer health summaries.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.me/partner-api/v1/accounts \\\n -H \"Authorization: Bearer $APPLICATION_ASSERTION\"" } ] }, "post": { "tags": [ "Partner Management" ], "summary": "Provision a customer Account without customer registration", "operationId": "createPartnerManagedAccount", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 200, "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePartnerManagedAccountRequest" } } } }, "responses": { "200": { "description": "Idempotent replay of the existing relationship and hosted onboarding URL", "headers": { "Cache-Control": { "description": "Prevents the one-time Agent onboarding URL from being stored.", "schema": { "type": "string", "example": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerManagedAccount" } } } }, "201": { "description": "Managed Account provisioned; a single-use hosted Agent onboarding URL is included", "headers": { "Cache-Control": { "description": "Prevents the one-time Agent onboarding URL from being stored.", "schema": { "type": "string", "example": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerManagedAccount" } } } }, "401": { "description": "Application assertion is missing, invalid or already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Partner capability is not granted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Idempotency record references a relationship that no longer exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Idempotency key or customer relationship conflicts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request payload, application or permissions are invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "developerApplicationAssertion": [] } ], "description": "Provision an isolated headless CloudPrint Account, stable App Installation and one-time Agent Enrollment. Idempotency-Key is required and bound to the complete request.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS https://public-api.cloudprint.me/partner-api/v1/accounts \\\n -H \"Authorization: Bearer $APPLICATION_ASSERTION\" \\\n -H 'Idempotency-Key: customer-42-provision-v1' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"external_customer_id\": \"customer-42\",\n \"name\": \"Acme Store 42\",\n \"permissions\": [\"printers:read\", \"documents:write\", \"print_jobs:write\", \"print_jobs:read\"],\n \"agent_onboarding\": {\n \"return_uri\": \"https://app.integrator.example/cloudprint/callback\",\n \"state\": \"single-use-random-state\"\n }\n }'" } ] } }, "/partner-api/v1/accounts/{relationshipId}/agent-enrollments": { "get": { "tags": [ "Partner Management" ], "summary": "List Agent Enrollments issued for a managed customer Account", "operationId": "listPartnerAgentEnrollments", "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100, "minimum": 1 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent Enrollments page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAgentEnrollmentPage" } } } }, "401": { "description": "Application assertion is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Partner capability is not granted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Managed Account was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Pagination parameters are invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "developerApplicationAssertion": [] } ], "description": "List pending, claimed, expired and revoked Agent Enrollments for one customer.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS \"https://public-api.cloudprint.me/partner-api/v1/accounts/$RELATIONSHIP_ID/agent-enrollments\" \\\n -H \"Authorization: Bearer $APPLICATION_ASSERTION\"" } ] }, "post": { "tags": [ "Partner Management" ], "summary": "Create hosted onboarding for a managed customer Agent", "operationId": "createPartnerAgentEnrollment", "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 200, "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePartnerAgentEnrollmentRequest" } } } }, "responses": { "201": { "description": "Agent Enrollment created", "headers": { "Cache-Control": { "description": "Prevents the one-time Agent onboarding URL from being stored.", "schema": { "type": "string", "example": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerIssuedAgentEnrollment" } } } }, "401": { "description": "Application assertion is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Partner capability is not granted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Managed Account or replacement Enrollment was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Idempotency key conflicts with a previous request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "developerApplicationAssertion": [] } ], "description": "Issue an expiring one-time Agent Enrollment before or after onboarding. Idempotency-Key is required. Repeating an identical request with the same key returns the original secret, so a lost response can be recovered safely.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS -X POST \"https://public-api.cloudprint.me/partner-api/v1/accounts/$RELATIONSHIP_ID/agent-enrollments\" \\\n -H \"Authorization: Bearer $APPLICATION_ASSERTION\" \\\n -H 'Idempotency-Key: customer-42-agent-2-v1' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"name\": \"Warehouse workstation 2\",\n \"agent_onboarding\": {\n \"return_uri\": \"https://app.integrator.example/cloudprint/callback\",\n \"state\": \"new-single-use-random-state\"\n }\n }'" } ] } }, "/partner-api/v1/accounts/{relationshipId}": { "get": { "tags": [ "Partner Management" ], "summary": "Get one managed customer Account", "operationId": "getPartnerManagedAccount", "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Managed Account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerManagedAccountView" } } } }, "401": { "description": "Application assertion is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Partner capability is not granted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Managed Account was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Relationship ID is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "developerApplicationAssertion": [] } ], "description": "Retrieve one managed customer directly by its stable relationship ID.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS \"https://public-api.cloudprint.me/partner-api/v1/accounts/$RELATIONSHIP_ID\" \\\n -H \"Authorization: Bearer $APPLICATION_ASSERTION\"" } ] } }, "/partner-api/v1/accounts/{relationshipId}/agent-enrollments/{enrollmentId}": { "get": { "tags": [ "Partner Management" ], "summary": "Get one Agent Enrollment issued for a managed customer Account", "operationId": "getPartnerAgentEnrollment", "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enrollmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Agent Enrollment", "headers": { "Cache-Control": { "description": "Prevents an Enrollment polling response from being stored.", "schema": { "type": "string", "example": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAgentEnrollment" } } } }, "401": { "description": "Application assertion is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Partner capability is not granted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Managed Account or Agent Enrollment was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Relationship ID or Agent Enrollment ID is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "developerApplicationAssertion": [] } ], "description": "Poll one exact Agent Enrollment. A claimed response contains the Agent ID created from that one-time link.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS \\\n \"https://public-api.cloudprint.me/partner-api/v1/accounts/$RELATIONSHIP_ID/agent-enrollments/$ENROLLMENT_ID\" \\\n -H \"Authorization: Bearer $APPLICATION_ASSERTION\"" } ] }, "delete": { "tags": [ "Partner Management" ], "summary": "Revoke one unclaimed Agent Enrollment", "operationId": "revokePartnerAgentEnrollment", "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enrollmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Agent Enrollment revoked" }, "401": { "description": "Application assertion is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Partner capability is not granted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Managed Account or Agent Enrollment was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Relationship ID or Agent Enrollment ID is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "developerApplicationAssertion": [] } ], "description": "Revoke an unclaimed Agent Enrollment. Repeating the request is safe.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS -X DELETE \\\n \"https://public-api.cloudprint.me/partner-api/v1/accounts/$RELATIONSHIP_ID/agent-enrollments/$ENROLLMENT_ID\" \\\n -H \"Authorization: Bearer $APPLICATION_ASSERTION\"" } ] } }, "/partner-api/v1/usage": { "get": { "tags": [ "Partner Management" ], "summary": "Get operational usage for the authenticated partner application", "operationId": "getPartnerUsage", "parameters": [ { "name": "period", "in": "query", "description": "UTC calendar month. Defaults to the current month.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "example": "2026-08" } } ], "responses": { "200": { "description": "Partner usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerUsage" } } } }, "401": { "description": "Application assertion is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Partner capability is not granted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Period is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "developerApplicationAssertion": [] } ], "description": "Return operational usage for one UTC calendar month. Usage is informational; the Partner Program is invoiced at the fixed monthly price in the signed agreement.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS 'https://public-api.cloudprint.me/partner-api/v1/usage?period=2026-08' \\\n -H \"Authorization: Bearer $APPLICATION_ASSERTION\"" } ] } }, "/partner-api/v1/accounts/{relationshipId}/agents": { "get": { "tags": [ "Partner Management" ], "summary": "List Agents connected to a managed customer Account", "operationId": "listPartnerManagedAgents", "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100, "minimum": 1 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Managed Agents page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerManagedAgentPage" } } } }, "401": { "description": "Application assertion is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Partner capability is not granted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Managed Account was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Pagination parameters are invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "developerApplicationAssertion": [] } ], "description": "List every Agent connected to one managed customer, including revoked Agents.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS \"https://public-api.cloudprint.me/partner-api/v1/accounts/$RELATIONSHIP_ID/agents\" \\\n -H \"Authorization: Bearer $APPLICATION_ASSERTION\"" } ] } }, "/partner-api/v1/accounts/{relationshipId}/agents/{agentId}": { "delete": { "tags": [ "Partner Management" ], "summary": "Revoke one Agent connected to a managed customer Account", "operationId": "revokePartnerManagedAgent", "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Agent revoked" }, "401": { "description": "Application assertion is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Partner capability is not granted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Managed Account or Agent was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Relationship ID or Agent ID is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "developerApplicationAssertion": [] } ], "description": "Revoke one Agent and take its printers offline. Repeating the request is safe.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -sS -X DELETE \"https://public-api.cloudprint.me/partner-api/v1/accounts/$RELATIONSHIP_ID/agents/$AGENT_ID\" \\\n -H \"Authorization: Bearer $APPLICATION_ASSERTION\"" } ] } }, "/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 missing, invalid or no longer authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "description": "Use this endpoint during setup checks to confirm the account and authorization mode. Account API Client tokens return client and scope details; App Installation tokens return Developer Application, installation and permission details.", "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 missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "OAuth bearer token does not include agents:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Pagination parameters are invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "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 a short-lived OAuth2 access token", "operationId": "issueOAuthToken", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "required": [ "grant_type", "client_id", "client_secret" ], "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ], "example": "client_credentials" }, "client_id": { "description": "Account-owned Account API Client ID.", "type": "string" }, "client_secret": { "type": "string" }, "scope": { "description": "Optional space-separated subset of scopes approved for the Account API Client.", "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", "scope" ], "properties": { "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "type": "integer", "example": 900 }, "access_token": { "type": "string", "example": "eyJ..." }, "scope": { "type": "string", "example": "printers:read print_jobs:write" } } } } } }, "400": { "description": "Invalid OAuth2 request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid OAuth2 client credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } } }, "500": { "description": "OAuth2 server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Exchange an account-owned Account API Client 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" } } } }, "401": { "description": "OAuth bearer token is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "OAuth bearer token does not include documents:write", "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" } } }, "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "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" } } } }, "422": { "description": "Pagination parameters are invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected error", "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" } } } }, "401": { "description": "OAuth bearer token is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "OAuth bearer token lacks documents:write or print_jobs:write", "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" } } } }, "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" } } }, "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "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" } } } }, "401": { "description": "OAuth bearer token is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "OAuth bearer token lacks documents:write or print_jobs:write", "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" } } }, "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "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" } } } }, "401": { "description": "OAuth bearer token is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "OAuth bearer token lacks documents:write or print_jobs:write", "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" } } }, "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "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" } } } }, "401": { "description": "OAuth bearer token is missing or 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" } } } }, "404": { "description": "Print job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Print job ID is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "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" } } } }, "401": { "description": "OAuth bearer token is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "OAuth bearer token does not include printers:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Pagination parameters are invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when the current window resets.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Scope": { "description": "Quota that rejected the request, such as ip, application or installation.", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "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", "authorization_mode", "installation_id" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "account_name": { "type": "string", "example": "Acme Print Ops" }, "client_app_id": { "type": [ "string", "null" ], "format": "uuid" }, "client_app_name": { "type": [ "string", "null" ] }, "application_id": { "type": [ "string", "null" ], "format": "uuid" }, "application_name": { "type": [ "string", "null" ] }, "authorization_mode": { "type": "string", "enum": [ "client_credentials", "app_installation" ] }, "installation_id": { "type": [ "string", "null" ], "format": "uuid" }, "scopes": { "type": "array", "items": { "type": "string" }, "example": [ "agents:read", "printers:read", "documents:write", "print_jobs:write", "print_jobs:read" ] }, "permissions": { "type": "array", "items": { "type": "string" } } }, "type": "object", "oneOf": [ { "required": [ "client_app_id", "client_app_name", "scopes" ], "properties": { "authorization_mode": { "type": "string", "enum": [ "client_credentials" ] } }, "type": "object" }, { "required": [ "application_id", "application_name", "permissions" ], "properties": { "authorization_mode": { "type": "string", "enum": [ "app_installation" ] }, "installation_id": { "type": "string", "format": "uuid" } }, "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": { "description": "media_width_mm and media_height_mm must be supplied together when custom media is used.", "required": [ "document_id", "printer_id" ], "properties": { "document_id": { "type": "string", "format": "uuid" }, "printer_id": { "type": "string", "format": "uuid" }, "copies": { "type": "integer", "maximum": 99, "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" ], "maximum": 2000, "minimum": 1, "example": 58 }, "media_height_mm": { "type": [ "number", "null" ], "maximum": 2000, "minimum": 1, "example": 40 }, "dpi": { "type": [ "integer", "null" ], "maximum": 2400, "minimum": 72, "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", "maximum": 2000, "minimum": -2000, "example": 0 }, "offset_y_mm": { "type": "number", "maximum": 2000, "minimum": -2000, "example": 0 }, "margin_top_mm": { "type": "number", "maximum": 2000, "minimum": 0, "example": 0 }, "margin_right_mm": { "type": "number", "maximum": 2000, "minimum": 0, "example": 0 }, "margin_bottom_mm": { "type": "number", "maximum": 2000, "minimum": 0, "example": 0 }, "margin_left_mm": { "type": "number", "maximum": 2000, "minimum": 0, "example": 0 } }, "type": "object" }, "CreatePrintJobFromUrlRequest": { "description": "media_width_mm and media_height_mm must be supplied together when custom media is used.", "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", "maximum": 99, "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" ], "maximum": 2000, "minimum": 1, "example": 58 }, "media_height_mm": { "type": [ "number", "null" ], "maximum": 2000, "minimum": 1, "example": 40 }, "dpi": { "type": [ "integer", "null" ], "maximum": 2400, "minimum": 72, "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", "maximum": 2000, "minimum": -2000, "example": 0 }, "offset_y_mm": { "type": "number", "maximum": 2000, "minimum": -2000, "example": 0 }, "margin_top_mm": { "type": "number", "maximum": 2000, "minimum": 0, "example": 0 }, "margin_right_mm": { "type": "number", "maximum": 2000, "minimum": 0, "example": 0 }, "margin_bottom_mm": { "type": "number", "maximum": 2000, "minimum": 0, "example": 0 }, "margin_left_mm": { "type": "number", "maximum": 2000, "minimum": 0, "example": 0 } }, "type": "object" }, "CreatePrintJobFromBase64Request": { "description": "media_width_mm and media_height_mm must be supplied together when custom media is used.", "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", "maximum": 99, "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" ], "maximum": 2000, "minimum": 1, "example": 58 }, "media_height_mm": { "type": [ "number", "null" ], "maximum": 2000, "minimum": 1, "example": 40 }, "dpi": { "type": [ "integer", "null" ], "maximum": 2400, "minimum": 72, "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", "maximum": 2000, "minimum": -2000, "example": 0 }, "offset_y_mm": { "type": "number", "maximum": 2000, "minimum": -2000, "example": 0 }, "margin_top_mm": { "type": "number", "maximum": 2000, "minimum": 0, "example": 0 }, "margin_right_mm": { "type": "number", "maximum": 2000, "minimum": 0, "example": 0 }, "margin_bottom_mm": { "type": "number", "maximum": 2000, "minimum": 0, "example": 0 }, "margin_left_mm": { "type": "number", "maximum": 2000, "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", "media_width_mm", "media_height_mm", "dpi", "scale_mode", "orientation", "offset_x_mm", "offset_y_mm", "margin_top_mm", "margin_right_mm", "margin_bottom_mm", "margin_left_mm", "created_at", "reserved_at", "started_at", "completed_at", "failure_reason" ], "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", "enum": [ "pending", "reserved", "printing", "printed", "failed", "cancelled" ], "example": "pending" }, "copies": { "type": "integer", "maximum": 99, "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" ], "maximum": 2000, "minimum": 1, "example": 58 }, "media_height_mm": { "type": [ "number", "null" ], "maximum": 2000, "minimum": 1, "example": 40 }, "dpi": { "type": [ "integer", "null" ], "maximum": 2400, "minimum": 72, "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", "maximum": 2000, "minimum": -2000, "example": 0 }, "offset_y_mm": { "type": "number", "maximum": 2000, "minimum": -2000, "example": 0 }, "margin_top_mm": { "type": "number", "maximum": 2000, "minimum": 0, "example": 0 }, "margin_right_mm": { "type": "number", "maximum": 2000, "minimum": 0, "example": 0 }, "margin_bottom_mm": { "type": "number", "maximum": 2000, "minimum": 0, "example": 0 }, "margin_left_mm": { "type": "number", "maximum": 2000, "minimum": 0, "example": 0 }, "created_at": { "type": "string", "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", "version", "supported_commands", "max_bitmap_width_dots", "max_bitmap_height_dots", "compression_modes", "codepage" ], "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", "configuration_issue", "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": { "required": [ "width_mm", "height_mm", "dpi", "orientation", "feed_type", "darkness", "speed" ], "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" ], "enum": [ "online", "offline", "revoked" ], "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", "agent_instance_id", "hostname", "version", "update", "last_seen_at" ], "properties": { "agent_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Warehouse PC agent" }, "status": { "type": "string", "enum": [ "online", "offline", "revoked" ], "example": "online" }, "agent_instance_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" }, "PublicAgentInstaller": { "required": [ "filename", "platform", "architecture", "format", "size_bytes", "sha256", "download_url" ], "properties": { "filename": { "type": "string" }, "platform": { "type": "string", "enum": [ "darwin", "windows", "linux" ] }, "architecture": { "type": "string" }, "format": { "type": "string" }, "size_bytes": { "type": "integer", "minimum": 1 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "download_url": { "type": "string", "format": "uri-reference" } }, "type": "object" }, "PublicAgentRelease": { "required": [ "version", "channel", "published_at", "installers" ], "properties": { "version": { "type": "string" }, "channel": { "type": "string" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "installers": { "type": "array", "items": { "$ref": "#/components/schemas/PublicAgentInstaller" } } }, "type": "object" }, "PublicAgentReleaseCatalog": { "required": [ "available", "channel", "releases" ], "properties": { "available": { "type": "boolean" }, "channel": { "type": [ "string", "null" ] }, "releases": { "type": "array", "items": { "$ref": "#/components/schemas/PublicAgentRelease" } }, "unavailable_reason": { "type": [ "string", "null" ] } }, "type": "object" }, "IssueInstallationAccessTokenRequest": { "properties": { "permissions": { "description": "Optional non-empty subset of the installation effective permissions. Omit to request all effective permissions.", "type": "array", "items": { "type": "string", "enum": [ "agents:read", "printers:read", "documents:write", "print_jobs:write", "print_jobs:read" ] }, "minItems": 1, "uniqueItems": true } }, "type": "object" }, "IssuedInstallationAccessToken": { "required": [ "access_token", "token_type", "expires_in", "installation_id", "account_id", "permissions" ], "properties": { "access_token": { "type": "string", "example": "eyJ..." }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer", "minimum": 1, "example": 3600 }, "installation_id": { "type": "string", "format": "uuid" }, "account_id": { "type": "string", "format": "uuid" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "agents:read", "printers:read", "documents:write", "print_jobs:write", "print_jobs:read" ] }, "minItems": 1, "uniqueItems": true } }, "type": "object" }, "PartnerAgentOnboardingRequest": { "required": [ "return_uri", "state" ], "properties": { "return_uri": { "description": "Exact callback URI registered on the Developer Application. It must not contain result, state or agent_id query parameters. CloudPrint returns result=ready after the first authenticated Agent heartbeat, even when no printers were discovered. The integrator must then refresh the managed Account, Agents and printer list before enabling printing.", "type": "string", "format": "uri", "maxLength": 2048 }, "state": { "description": "Integrator-generated, single-use CSRF value returned unchanged to the callback.", "type": "string", "maxLength": 512, "minLength": 1 } }, "type": "object" }, "CreatePartnerManagedAccountRequest": { "required": [ "external_customer_id", "name", "agent_onboarding" ], "properties": { "external_customer_id": { "description": "Stable customer or tenant identifier from the integrator system.", "type": "string", "maxLength": 160, "minLength": 1, "example": "customer-42" }, "name": { "type": "string", "maxLength": 120, "minLength": 1, "example": "Acme Store 42" }, "permissions": { "description": "Optional non-empty subset of permissions declared by the application. Omit to use every declared permission.", "type": "array", "items": { "type": "string", "enum": [ "agents:read", "printers:read", "documents:write", "print_jobs:write", "print_jobs:read" ] }, "minItems": 1, "uniqueItems": true }, "agent_onboarding": { "$ref": "#/components/schemas/PartnerAgentOnboardingRequest" } }, "type": "object" }, "PartnerManagedAccount": { "required": [ "relationship_id", "developer_account_id", "cloudprint_account_id", "external_customer_id", "name", "application_id", "installation_id", "agent_enrollment_id", "agent_onboarding_expires_at", "agent_onboarding_url", "onboarding_status", "status", "created_at", "updated_at" ], "properties": { "relationship_id": { "type": "string", "format": "uuid" }, "developer_account_id": { "type": "string", "format": "uuid" }, "cloudprint_account_id": { "description": "Read-only CloudPrint Account identifier. It can be compared with account_id from an Installation Access Token response, but is never supplied when issuing a token.", "type": "string", "format": "uuid" }, "external_customer_id": { "type": "string", "maxLength": 160 }, "name": { "type": "string", "maxLength": 120 }, "application_id": { "type": "string", "format": "uuid" }, "installation_id": { "description": "Stable App Installation identifier used to issue short-lived Installation Access Tokens. Store it with relationship_id, or retrieve it from this resource.", "type": [ "string", "null" ], "format": "uuid" }, "agent_enrollment_id": { "type": [ "string", "null" ], "format": "uuid" }, "agent_onboarding_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "agent_onboarding_url": { "description": "CloudPrint-selected hosted onboarding URL. Open the complete value unchanged, including its #token fragment. Do not parse, log, proxy or rebuild it. Network routing and Agent API failover are managed by CloudPrint.", "type": [ "string", "null" ], "format": "uri", "example": "https://connect.cloudprint.me/setup#token=cpat_example" }, "onboarding_status": { "description": "ready means that at least one Agent completed its first authenticated heartbeat. It does not mean that a printer was discovered or is online.", "type": "string", "enum": [ "provisioning", "waiting_for_agent", "ready", "failed" ] }, "status": { "description": "Managed relationship lifecycle. Printing is ready only when status=active, health.online_agent_count > 0 and health.online_printer_count > 0.", "type": "string", "enum": [ "provisioning", "active", "suspended", "closed" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "PartnerManagedAccountHealth": { "description": "Operational availability for a managed Account. Printing is ready only when status=active, online_agent_count > 0 and online_printer_count > 0. Agent onboarding readiness alone is insufficient.", "required": [ "agent_count", "online_agent_count", "printer_count", "online_printer_count", "last_seen_at" ], "properties": { "agent_count": { "description": "Number of non-revoked Agents connected to the managed Account.", "type": "integer", "minimum": 0 }, "online_agent_count": { "description": "Non-revoked Agents with status online and a heartbeat in the last minute.", "type": "integer", "minimum": 0 }, "printer_count": { "description": "Number of printers discovered by non-revoked Agents.", "type": "integer", "minimum": 0 }, "online_printer_count": { "description": "Online printers whose Agent is non-revoked, online and has sent a heartbeat in the last minute.", "type": "integer", "minimum": 0 }, "last_seen_at": { "description": "Most recent heartbeat from a non-revoked Agent, or null when none was received.", "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "PartnerManagedAccountView": { "required": [ "health" ], "allOf": [ { "$ref": "#/components/schemas/PartnerManagedAccount" }, { "required": [ "health" ], "properties": { "health": { "$ref": "#/components/schemas/PartnerManagedAccountHealth" } }, "type": "object" } ] }, "PartnerManagedAccountPage": { "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerManagedAccountView" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } }, "type": "object" }, "CreatePartnerAgentEnrollmentRequest": { "required": [ "agent_onboarding" ], "properties": { "name": { "description": "Optional operator-facing computer name. When omitted, CloudPrint derives a name from the managed Account. A supplied name is trimmed, must contain 1 to 255 Unicode characters and must not contain ASCII control characters.", "type": "string", "maxLength": 255, "minLength": 1, "example": "Warehouse workstation 2" }, "agent_onboarding": { "$ref": "#/components/schemas/PartnerAgentOnboardingRequest" }, "replaces_enrollment_id": { "description": "Optional unclaimed Enrollment to revoke atomically before issuing the new one.", "type": [ "string", "null" ], "format": "uuid" } }, "type": "object" }, "PartnerIssuedAgentEnrollment": { "required": [ "agent_enrollment_id", "expires_at", "agent_onboarding_url", "status" ], "properties": { "agent_enrollment_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "agent_onboarding_url": { "description": "CloudPrint-selected hosted onboarding URL. Open the complete value unchanged, including its #token fragment. Do not parse, log, proxy or rebuild it.", "type": "string", "format": "uri", "example": "https://connect.cloudprint.me/setup#token=cpat_example" }, "status": { "type": "string", "enum": [ "pending" ] } }, "type": "object" }, "PartnerAgentEnrollment": { "required": [ "agent_enrollment_id", "name", "status", "expires_at", "created_at", "agent_id", "claimed_at", "revoked_at" ], "properties": { "agent_enrollment_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "claimed", "expired", "revoked" ] }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "agent_id": { "description": "Agent created from this Enrollment. Null until status becomes claimed.", "type": [ "string", "null" ], "format": "uuid" }, "claimed_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "PartnerAgentEnrollmentPage": { "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerAgentEnrollment" } }, "next_cursor": { "type": [ "string", "null" ] } }, "type": "object" }, "PartnerManagedAgent": { "required": [ "agent_id", "name", "status", "agent_instance_id", "hostname", "version", "last_seen_at", "created_at", "revoked_at" ], "properties": { "agent_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "online", "offline", "revoked" ] }, "agent_instance_id": { "type": [ "string", "null" ] }, "hostname": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "PartnerManagedAgentPage": { "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerManagedAgent" } }, "next_cursor": { "type": [ "string", "null" ] } }, "type": "object" }, "PartnerUsage": { "required": [ "period", "starts_at", "ends_at", "managed_accounts", "active_agents", "print_jobs" ], "properties": { "period": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "managed_accounts": { "type": "integer", "minimum": 0 }, "active_agents": { "type": "integer", "minimum": 0 }, "print_jobs": { "type": "integer", "minimum": 0 } }, "type": "object" }, "OAuthErrorResponse": { "required": [ "error" ], "properties": { "error": { "description": "OAuth2 machine-readable error code.", "type": "string", "example": "invalid_token" }, "error_description": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "hint": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] } }, "type": "object" }, "ErrorResponse": { "required": [ "error", "error_code", "message" ], "properties": { "error": { "description": "Stable machine-readable error code.", "type": "string" }, "error_code": { "description": "Alias of error retained for a uniform public API error envelope.", "type": "string" }, "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": "Short-lived CloudPrint access token issued by OAuth2 Client Credentials or for an active App Installation.", "bearerFormat": "JWT", "scheme": "bearer" }, "developerApplicationAssertion": { "type": "http", "description": "One-time RS256 Developer Application assertion with kid and a maximum five-minute TTL. Use the exact installation token endpoint as aud for Developer API token issuance, or the configured Partner Management audience for Partner API calls.", "bearerFormat": "JWT", "scheme": "bearer" } } }, "tags": [ { "name": "Auth", "description": "Get an Account API Client token and inspect the current authorization 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." }, { "name": "Developer Platform", "description": "Issue account-scoped tokens for an active App Installation." }, { "name": "Partner Management", "description": "Provision and operate isolated customer Accounts from an active partner backend." }, { "name": "Agent Downloads", "description": "Discover and download official CloudPrint Agent installers without signing in." } ], "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" ] }, { "name": "App installations", "tags": [ "Developer Platform" ] }, { "name": "Managed customers", "tags": [ "Partner Management" ] }, { "name": "Agent downloads", "tags": [ "Agent Downloads" ] } ] }