{ "openapi": "3.0.0", "paths": { "/health/live": { "get": { "operationId": "HealthController_live", "parameters": [], "responses": { "200": { "description": "The process is running." } }, "tags": [ "health" ] } }, "/health/ready": { "get": { "operationId": "HealthController_ready", "parameters": [], "responses": { "200": { "description": "Database and Redis are reachable." } }, "tags": [ "health" ] } }, "/auth/signup": { "post": { "operationId": "AuthController_signup", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "password": { "type": "string", "minLength": 10, "maxLength": 200 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "locale": { "default": "en", "type": "string", "enum": [ "en", "fr", "ht" ] } }, "required": [ "email", "password", "name" ] } } } }, "responses": { "201": { "description": "" } }, "tags": [ "auth" ] } }, "/auth/verify-email": { "post": { "operationId": "AuthController_verifyEmail", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "token": { "type": "string", "minLength": 10, "maxLength": 200 } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "" } }, "tags": [ "auth" ] } }, "/auth/resend-verification": { "post": { "operationId": "AuthController_resend", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "email" ] } } } }, "responses": { "202": { "description": "" } }, "tags": [ "auth" ] } }, "/auth/login": { "post": { "operationId": "AuthController_login", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "password": { "type": "string", "minLength": 1, "maxLength": 200 }, "code": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "" } }, "tags": [ "auth" ] } }, "/auth/login/2fa": { "post": { "operationId": "AuthController_login2fa", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "challenge": { "type": "string", "minLength": 1 }, "code": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "challenge", "code" ] } } } }, "responses": { "200": { "description": "" } }, "tags": [ "auth" ] } }, "/auth/refresh": { "post": { "operationId": "AuthController_refresh", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "auth" ] } }, "/auth/logout": { "post": { "operationId": "AuthController_logout", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "auth" ] } }, "/auth/forgot-password": { "post": { "operationId": "AuthController_forgot", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "email" ] } } } }, "responses": { "202": { "description": "" } }, "tags": [ "auth" ] } }, "/auth/reset-password": { "post": { "operationId": "AuthController_reset", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "token": { "type": "string", "minLength": 10, "maxLength": 200 }, "password": { "type": "string", "minLength": 10, "maxLength": 200 } }, "required": [ "token", "password" ] } } } }, "responses": { "200": { "description": "" } }, "tags": [ "auth" ] } }, "/auth/me": { "get": { "operationId": "AuthController_me", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "auth" ] } }, "/auth/2fa/setup": { "post": { "operationId": "AuthController_setup", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "auth" ] } }, "/auth/2fa/confirm": { "post": { "operationId": "AuthController_confirm", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "setupToken": { "type": "string", "minLength": 1 }, "code": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "setupToken", "code" ] } } } }, "responses": { "200": { "description": "" } }, "tags": [ "auth" ] } }, "/auth/2fa/disable": { "post": { "operationId": "AuthController_disable", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "" } }, "tags": [ "auth" ] } }, "/orgs": { "post": { "operationId": "OrganizationsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "locale": { "default": "en", "type": "string", "enum": [ "en", "fr", "ht" ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "" } }, "tags": [ "organizations" ] }, "get": { "operationId": "OrganizationsController_mine", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "organizations" ] } }, "/orgs/{orgId}/me": { "get": { "operationId": "OrganizationsController_myAccess", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "organizations" ] } }, "/orgs/{orgId}": { "get": { "operationId": "OrganizationsController_get", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "organizations" ] }, "patch": { "operationId": "OrganizationsController_update", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "locale": { "type": "string", "enum": [ "en", "fr", "ht" ] }, "retentionDays": { "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 1 }, { "type": "number", "const": 7 }, { "type": "number", "const": 30 }, { "type": "number", "const": 90 } ] }, "requireSignature": { "type": "boolean" }, "unsignedModeEnabled": { "type": "boolean" }, "devModeEnabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "" } }, "tags": [ "organizations" ] }, "delete": { "operationId": "DashboardController_deleteOrg", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirm": { "type": "string", "description": "The organization's name, typed by the user" } }, "required": [ "confirm" ] } } } }, "responses": { "200": { "description": "" } }, "tags": [ "dashboard" ] } }, "/orgs/{orgId}/members": { "get": { "operationId": "MembersController_members", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "members" ] } }, "/orgs/{orgId}/members/{userId}": { "patch": { "operationId": "MembersController_setRole", "parameters": [ { "name": "userId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "developer", "viewer" ] } }, "required": [ "role" ] } } } }, "responses": { "200": { "description": "" } }, "tags": [ "members" ] }, "delete": { "operationId": "MembersController_remove", "parameters": [ { "name": "userId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "members" ] } }, "/orgs/{orgId}/invitations": { "get": { "operationId": "MembersController_invitations", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "members" ] }, "post": { "operationId": "MembersController_invite", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "enum": [ "owner", "admin", "developer", "viewer" ] } }, "required": [ "email", "role" ] } } } }, "responses": { "201": { "description": "" } }, "tags": [ "members" ] } }, "/orgs/{orgId}/invitations/{id}": { "delete": { "operationId": "MembersController_cancel", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "members" ] } }, "/invitations/accept": { "post": { "operationId": "InvitationsController_accept", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "token": { "type": "string", "minLength": 10, "maxLength": 200 } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "" } }, "tags": [ "members" ] } }, "/orgs/{orgId}/billing": { "get": { "operationId": "BillingController_overview", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "billing" ] } }, "/orgs/{orgId}/billing/checkout": { "post": { "operationId": "BillingController_checkout", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "planCode": { "type": "string", "pattern": "^[a-z0-9_-]{1,32}$" } }, "required": [ "planCode" ] } } } }, "responses": { "201": { "description": "" } }, "summary": "Start a subscription: returns the hosted checkout page URL", "tags": [ "billing" ] } }, "/orgs/{orgId}/billing/portal": { "post": { "operationId": "BillingController_portal", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Open the billing portal (change plan, card, cancel)", "tags": [ "billing" ] } }, "/admin/organizations/{orgId}/plan": { "post": { "operationId": "AdminBillingController_setPlan", "parameters": [ { "name": "orgId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "planCode": { "type": "string", "pattern": "^[a-z0-9_-]{1,32}$" }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "planCode" ] } } } }, "responses": { "200": { "description": "" } }, "tags": [ "admin" ] } }, "/admin/license": { "get": { "operationId": "AdminLicenseController_status", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Self-hosted license status", "tags": [ "admin" ] } }, "/agent/v1/logs": { "post": { "operationId": "AgentLogsController_upload", "parameters": [], "requestBody": { "required": true, "description": "Multipart: `file` (gzip, at most 50 MB) and optional `requestId`.", "content": { "multipart/form-data": { "schema": { "type": "string" } } } }, "responses": { "201": { "description": "" } }, "tags": [ "agent" ] } }, "/orgs/{orgId}/devices/{deviceId}/logs/request": { "post": { "operationId": "DeviceLogsController_request", "parameters": [ { "name": "deviceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "tags": [ "devices" ] } }, "/orgs/{orgId}/devices/{deviceId}/logs": { "get": { "operationId": "DeviceLogsController_list", "parameters": [ { "name": "deviceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "devices" ] } }, "/orgs/{orgId}/devices/{deviceId}/logs/{logId}/download": { "get": { "operationId": "DeviceLogsController_download", "parameters": [ { "name": "deviceId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "logId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "devices" ] } }, "/agent/v1/license-key": { "get": { "operationId": "LicenseKeyController_key", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "agent" ] } }, "/.well-known/jodaprint-license-keys.json": { "get": { "operationId": "JwksController_jwks", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "agent" ] } }, "/users/me": { "patch": { "operationId": "UsersController_update", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "locale": { "type": "string", "enum": [ "en", "fr", "ht" ] } } } } } }, "responses": { "200": { "description": "" } }, "tags": [ "users" ] } }, "/orgs/{orgId}/api-keys": { "get": { "operationId": "ApiKeysController_list", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "api-keys" ] }, "post": { "operationId": "ApiKeysController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "printers:read", "jobs:write", "jobs:read", "devices:read", "devices:write", "webhooks:write" ] } }, "mode": { "default": "live", "type": "string", "enum": [ "live", "test" ] } }, "required": [ "name", "scopes" ] } } } }, "responses": { "201": { "description": "" } }, "tags": [ "api-keys" ] } }, "/orgs/{orgId}/api-keys/{id}": { "delete": { "operationId": "ApiKeysController_revoke", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "api-keys" ] } }, "/v1/me": { "get": { "operationId": "V1MeController_me", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "v1" ] } }, "/orgs/{orgId}/signing-keys": { "get": { "operationId": "SigningKeysController_list", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "signing-keys" ] }, "post": { "operationId": "SigningKeysController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "publicKey": { "type": "string", "minLength": 40, "maxLength": 1000 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "" } }, "tags": [ "signing-keys" ] } }, "/orgs/{orgId}/signing-keys/{id}": { "delete": { "operationId": "SigningKeysController_revoke", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "signing-keys" ] } }, "/orgs/{orgId}/origins": { "get": { "operationId": "OriginsController_list", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "origins" ] }, "post": { "operationId": "OriginsController_add", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "origin": { "type": "string", "minLength": 8, "maxLength": 300 } }, "required": [ "origin" ] } } } }, "responses": { "201": { "description": "" } }, "tags": [ "origins" ] } }, "/orgs/{orgId}/origins/{id}": { "delete": { "operationId": "OriginsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "origins" ] } }, "/orgs/{orgId}/devices": { "get": { "operationId": "DevicesController_list", "parameters": [ { "name": "q", "required": false, "in": "query", "description": "Search in names and host names.", "schema": {} }, { "name": "state", "required": false, "in": "query", "schema": { "enum": [ "active", "deactivated", "all" ], "type": "string" } }, { "name": "os", "required": false, "in": "query", "schema": { "enum": [ "windows", "darwin", "linux", "android" ], "type": "string" } }, { "name": "version", "required": false, "in": "query", "schema": {} }, { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "online", "offline" ], "type": "string" } }, { "name": "groupId", "required": false, "in": "query", "description": "A group ID, or \"none\".", "schema": {} } ], "responses": { "200": { "description": "" } }, "tags": [ "devices" ] } }, "/orgs/{orgId}/devices/{id}": { "get": { "operationId": "DevicesController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "devices" ] }, "patch": { "operationId": "DevicesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "groupId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "releaseChannel": { "type": "string", "enum": [ "stable", "beta" ] } } } } } }, "responses": { "200": { "description": "" } }, "tags": [ "devices" ] }, "delete": { "operationId": "DevicesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "devices" ] } }, "/orgs/{orgId}/devices/{id}/config": { "get": { "operationId": "DevicesController_config_", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "devices" ] } }, "/orgs/{orgId}/devices/{id}/deactivate": { "post": { "operationId": "DevicesController_deactivate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "devices" ] } }, "/orgs/{orgId}/device-groups": { "get": { "operationId": "DeviceGroupsController_list", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "device-groups" ] }, "post": { "operationId": "DeviceGroupsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "parentId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "" } }, "tags": [ "device-groups" ] } }, "/orgs/{orgId}/device-groups/{id}": { "patch": { "operationId": "DeviceGroupsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "parentId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "" } }, "tags": [ "device-groups" ] }, "delete": { "operationId": "DeviceGroupsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "device-groups" ] } }, "/orgs/{orgId}/activation-codes": { "get": { "operationId": "ActivationCodesController_list", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "activation" ] }, "post": { "operationId": "ActivationCodesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "groupId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "maxUses": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000 }, "expiresInHours": { "default": 168, "type": "integer", "minimum": 1, "maximum": 720 } } } } } }, "responses": { "201": { "description": "" } }, "tags": [ "activation" ] } }, "/orgs/{orgId}/activation-codes/{id}": { "delete": { "operationId": "ActivationCodesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "activation" ] } }, "/agent/v1/activate": { "post": { "operationId": "AgentController_activate", "parameters": [], "requestBody": { "required": true, "description": "protocol/schemas/agent-activate-request.json", "content": { "application/json": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "" } }, "tags": [ "agent" ] } }, "/agent/v1/config": { "get": { "operationId": "AgentController_getConfig", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "agent" ] } }, "/orgs/{orgId}/printers": { "get": { "operationId": "PrintersController_list", "parameters": [ { "name": "deviceId", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "printers" ] } }, "/orgs/{orgId}/printers/{id}": { "get": { "operationId": "PrintersController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "printers" ] }, "patch": { "operationId": "PrintersController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "alias": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,64}$" }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "paper": { "anyOf": [ { "type": "string", "enum": [ "58mm", "80mm", "label-4x6", "label-2x1", "a4", "letter" ] }, { "type": "null" } ] }, "codepage": { "anyOf": [ { "type": "string", "enum": [ "CP437", "CP850", "CP858", "CP1252", "CP866", "ISO-8859-15" ] }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "" } }, "tags": [ "printers" ] } }, "/orgs/{orgId}/config/profiles": { "get": { "operationId": "ConfigController_list", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "config" ] } }, "/orgs/{orgId}/config/profiles/{scope}/{targetId}": { "get": { "operationId": "ConfigController_get", "parameters": [ { "name": "scope", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "targetId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "config" ] }, "put": { "operationId": "ConfigController_put", "parameters": [ { "name": "scope", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "targetId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "A partial agent config (protocol/schemas/config.json).", "content": { "application/json": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "" } }, "tags": [ "config" ] }, "delete": { "operationId": "ConfigController_remove", "parameters": [ { "name": "scope", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "targetId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "config" ] } }, "/orgs/{orgId}/config/profiles/{scope}/{targetId}/export": { "get": { "operationId": "ConfigController_export", "parameters": [ { "name": "scope", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "targetId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "config" ] } }, "/v1/receipt/preview": { "post": { "description": "Renders an A8 receipt document to PNG exactly as the agent prints it on a thermal printer. Image URLs are not fetched: they show as a crossed box (inline base64 images render).", "operationId": "V1ReceiptController_preview", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "document": { "description": "An A8 receipt document (protocol/schemas/receipt-document.json)" }, "profile": { "description": "Printer profile, default generic-80mm", "type": "string", "maxLength": 40 }, "paper": { "type": "string", "enum": [ "58mm", "80mm" ] }, "footer": { "description": "Add the free plan's \"Printed with JodaPrint\" line", "type": "boolean" } }, "required": [ "document" ] } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Preview a receipt", "tags": [ "v1 receipts" ] } }, "/orgs/{orgId}/receipt/preview": { "post": { "operationId": "OrgReceiptController_preview", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "document": { "description": "An A8 receipt document (protocol/schemas/receipt-document.json)" }, "profile": { "description": "Printer profile, default generic-80mm", "type": "string", "maxLength": 40 }, "paper": { "type": "string", "enum": [ "58mm", "80mm" ] }, "footer": { "description": "Add the free plan's \"Printed with JodaPrint\" line", "type": "boolean" } }, "required": [ "document" ] } } } }, "responses": { "201": { "description": "" } }, "summary": "Preview a receipt (dashboard)", "tags": [ "receipts" ] } }, "/orgs/{orgId}/overview": { "get": { "operationId": "DashboardController_overview", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Numbers for the dashboard overview", "tags": [ "dashboard" ] } }, "/orgs/{orgId}/jobs": { "get": { "operationId": "DashboardController_list", "parameters": [ { "name": "printerId", "required": false, "in": "query", "schema": {} }, { "name": "deviceId", "required": false, "in": "query", "schema": {} }, { "name": "state", "required": false, "in": "query", "schema": {} } ], "responses": { "200": { "description": "" } }, "summary": "Jobs (dashboard): newest first", "tags": [ "dashboard" ] } }, "/orgs/{orgId}/jobs.csv": { "get": { "operationId": "DashboardController_csv", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Jobs matching the filters as CSV (at most 10 000 rows)", "tags": [ "dashboard" ] } }, "/orgs/{orgId}/jobs/{id}": { "get": { "operationId": "DashboardController_job", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "dashboard" ] } }, "/orgs/{orgId}/jobs/{id}/preview": { "get": { "operationId": "DashboardController_preview", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "dashboard" ] } }, "/orgs/{orgId}/jobs/{id}/cancel": { "post": { "operationId": "DashboardController_cancel", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "dashboard" ] } }, "/orgs/{orgId}/jobs/{id}/reprint": { "post": { "operationId": "DashboardController_reprint", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "tags": [ "dashboard" ] } }, "/orgs/{orgId}/jobs/{id}/render": { "get": { "operationId": "DashboardController_render", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "dashboard" ] } }, "/orgs/{orgId}/downloads": { "get": { "operationId": "DashboardController_downloads", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "dashboard" ] } }, "/orgs/{orgId}/webhooks/{id}/secret": { "get": { "operationId": "DashboardController_webhookSecret", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "dashboard" ] } }, "/orgs/{orgId}/printers/{id}/test-print": { "post": { "operationId": "DashboardController_testPrint", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "summary": "Send a test page to a printer through the cloud", "tags": [ "dashboard" ] } }, "/orgs/{orgId}/print": { "post": { "operationId": "DashboardController_print", "parameters": [], "responses": { "201": { "description": "" } }, "summary": "Print any job on a printer of the organization (dashboard test page)", "tags": [ "dashboard" ] } }, "/orgs/{orgId}/sandbox/print": { "post": { "operationId": "DashboardController_sandboxPrint", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "document": { "description": "An A8 receipt document; default a test receipt" }, "paper": { "type": "string", "enum": [ "58mm", "80mm" ] } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Print on the sandbox printer (preview only)", "tags": [ "dashboard" ] } }, "/orgs/{orgId}/devices/{id}/config/layers": { "get": { "operationId": "DashboardController_layers", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "A device's merged config with the layers it comes from", "tags": [ "dashboard" ] } }, "/orgs/{orgId}/config/profiles/{scope}/{targetId}/affected": { "get": { "operationId": "DashboardController_affected", "parameters": [ { "name": "scope", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "targetId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "How many active devices a profile change reaches", "tags": [ "dashboard" ] } }, "/admin/organizations": { "get": { "operationId": "AdminOrganizationsController_list", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "admin" ] } }, "/admin/organizations/{id}": { "delete": { "operationId": "AdminOrganizationsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Delete an organization and everything in it (platform admin)", "tags": [ "admin" ] } }, "/v1/jobs": { "post": { "description": "Dispatched at once when the device is online, otherwise queued until it reconnects or the job expires.", "operationId": "V1JobsController_create", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Same key within 24 hours returns the first job and prints nothing.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "A job-request (protocol/schemas/job-request.json) plus the target: `printerId`, or `deviceId` with an optional `alias`. The `Idempotency-Key` header overrides `idempotencyKey` in the body. To print a template, send `templateId` and its variables in `data` instead of `type`, `encoding` and content; the cloud renders it (GET /v1/templates lists them).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/job-request" }, { "type": "object", "properties": { "printerId": { "type": "string", "example": "prn_01J8Z2ABCDEF" }, "deviceId": { "type": "string", "example": "dev_01J8Z2ABCDEF" }, "alias": { "type": "string", "example": "receipt" } } } ], "example": { "printerId": "prn_01J8Z2ABCDEF", "type": "receipt", "encoding": "json", "data": { "width": "80mm", "blocks": [ { "type": "text", "value": "Hello" }, { "type": "cut", "mode": "partial" } ] }, "options": { "copies": 1 }, "metadata": { "orderId": "10492" } } } } } }, "responses": { "200": { "description": "A job with this idempotency key already exists; it is returned unchanged.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "idempotencyKey": { "type": [ "string", "null" ] }, "deviceId": { "type": [ "string", "null" ] }, "printerId": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "local", "cloud" ] }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "test: created with a jp_test_ key" }, "type": { "type": "string" }, "templateId": { "description": "The template the job was printed from, if any", "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "queued", "sending", "printed", "failed", "cancelled" ] }, "attempt": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "errorCode": { "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "contentRetained": { "type": "boolean", "description": "Whether the content is still stored (needed to reprint)" }, "hasPreview": { "type": "boolean", "description": "Sandbox jobs (jp_test_ keys): GET /v1/jobs/{id}/preview returns the printed receipt as PNG" }, "createdAt": { "type": "string", "description": "ISO 8601 date-time" }, "updatedAt": { "type": "string", "description": "ISO 8601 date-time" }, "dispatchedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "printedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "queued", "sending", "printed", "failed", "cancelled" ] }, "errorCode": { "type": [ "string", "null" ] }, "at": { "type": "string", "description": "ISO 8601 date-time" } }, "required": [ "state", "errorCode", "at" ], "additionalProperties": false } } }, "required": [ "id", "idempotencyKey", "deviceId", "printerId", "source", "mode", "type", "templateId", "state", "attempt", "errorCode", "errorMessage", "metadata", "contentRetained", "hasPreview", "createdAt", "updatedAt", "dispatchedAt", "printedAt", "expiresAt" ], "additionalProperties": false } } } }, "201": { "description": "The job was created.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "idempotencyKey": { "type": [ "string", "null" ] }, "deviceId": { "type": [ "string", "null" ] }, "printerId": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "local", "cloud" ] }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "test: created with a jp_test_ key" }, "type": { "type": "string" }, "templateId": { "description": "The template the job was printed from, if any", "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "queued", "sending", "printed", "failed", "cancelled" ] }, "attempt": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "errorCode": { "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "contentRetained": { "type": "boolean", "description": "Whether the content is still stored (needed to reprint)" }, "hasPreview": { "type": "boolean", "description": "Sandbox jobs (jp_test_ keys): GET /v1/jobs/{id}/preview returns the printed receipt as PNG" }, "createdAt": { "type": "string", "description": "ISO 8601 date-time" }, "updatedAt": { "type": "string", "description": "ISO 8601 date-time" }, "dispatchedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "printedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "queued", "sending", "printed", "failed", "cancelled" ] }, "errorCode": { "type": [ "string", "null" ] }, "at": { "type": "string", "description": "ISO 8601 date-time" } }, "required": [ "state", "errorCode", "at" ], "additionalProperties": false } } }, "required": [ "id", "idempotencyKey", "deviceId", "printerId", "source", "mode", "type", "templateId", "state", "attempt", "errorCode", "errorMessage", "metadata", "contentRetained", "hasPreview", "createdAt", "updatedAt", "dispatchedAt", "printedAt", "expiresAt" ], "additionalProperties": false } } } }, "400": { "description": "INVALID_JOB", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "LICENSE_LIMIT: monthly jobs of the plan used up", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a print job", "tags": [ "v1 jobs" ] }, "get": { "description": "Filter metadata with `metadata.=` query parameters.", "operationId": "V1JobsController_list", "parameters": [ { "name": "cursor", "required": false, "in": "query", "schema": {} }, { "name": "limit", "required": false, "in": "query", "description": "1–100, default 25", "schema": {} }, { "name": "to", "required": false, "in": "query", "description": "Created before (ISO 8601)", "schema": {} }, { "name": "from", "required": false, "in": "query", "description": "Created at or after (ISO 8601)", "schema": {} }, { "name": "printerId", "required": false, "in": "query", "schema": {} }, { "name": "deviceId", "required": false, "in": "query", "schema": {} }, { "name": "state", "required": false, "in": "query", "schema": { "enum": [ "queued", "sending", "printed", "failed", "cancelled" ], "type": "string" } } ], "responses": { "200": { "description": "A page of jobs.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "idempotencyKey": { "type": [ "string", "null" ] }, "deviceId": { "type": [ "string", "null" ] }, "printerId": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "local", "cloud" ] }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "test: created with a jp_test_ key" }, "type": { "type": "string" }, "templateId": { "description": "The template the job was printed from, if any", "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "queued", "sending", "printed", "failed", "cancelled" ] }, "attempt": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "errorCode": { "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "contentRetained": { "type": "boolean", "description": "Whether the content is still stored (needed to reprint)" }, "hasPreview": { "type": "boolean", "description": "Sandbox jobs (jp_test_ keys): GET /v1/jobs/{id}/preview returns the printed receipt as PNG" }, "createdAt": { "type": "string", "description": "ISO 8601 date-time" }, "updatedAt": { "type": "string", "description": "ISO 8601 date-time" }, "dispatchedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "printedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "queued", "sending", "printed", "failed", "cancelled" ] }, "errorCode": { "type": [ "string", "null" ] }, "at": { "type": "string", "description": "ISO 8601 date-time" } }, "required": [ "state", "errorCode", "at" ], "additionalProperties": false } } }, "required": [ "id", "idempotencyKey", "deviceId", "printerId", "source", "mode", "type", "templateId", "state", "attempt", "errorCode", "errorMessage", "metadata", "contentRetained", "hasPreview", "createdAt", "updatedAt", "dispatchedAt", "printedAt", "expiresAt" ], "additionalProperties": false } }, "nextCursor": { "description": "Pass as ?cursor= for the next page", "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } } }, "security": [ { "bearer": [] } ], "summary": "List jobs, newest first", "tags": [ "v1 jobs" ] } }, "/v1/jobs/{id}": { "get": { "operationId": "V1JobsController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The job, with events.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "idempotencyKey": { "type": [ "string", "null" ] }, "deviceId": { "type": [ "string", "null" ] }, "printerId": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "local", "cloud" ] }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "test: created with a jp_test_ key" }, "type": { "type": "string" }, "templateId": { "description": "The template the job was printed from, if any", "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "queued", "sending", "printed", "failed", "cancelled" ] }, "attempt": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "errorCode": { "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "contentRetained": { "type": "boolean", "description": "Whether the content is still stored (needed to reprint)" }, "hasPreview": { "type": "boolean", "description": "Sandbox jobs (jp_test_ keys): GET /v1/jobs/{id}/preview returns the printed receipt as PNG" }, "createdAt": { "type": "string", "description": "ISO 8601 date-time" }, "updatedAt": { "type": "string", "description": "ISO 8601 date-time" }, "dispatchedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "printedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "queued", "sending", "printed", "failed", "cancelled" ] }, "errorCode": { "type": [ "string", "null" ] }, "at": { "type": "string", "description": "ISO 8601 date-time" } }, "required": [ "state", "errorCode", "at" ], "additionalProperties": false } } }, "required": [ "id", "idempotencyKey", "deviceId", "printerId", "source", "mode", "type", "templateId", "state", "attempt", "errorCode", "errorMessage", "metadata", "contentRetained", "hasPreview", "createdAt", "updatedAt", "dispatchedAt", "printedAt", "expiresAt" ], "additionalProperties": false } } } }, "404": { "description": "JOB_NOT_FOUND", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "bearer": [] } ], "summary": "Get a job with its state history", "tags": [ "v1 jobs" ] } }, "/v1/jobs/{id}/preview": { "get": { "description": "The receipt a sandbox job (jp_test_ key) printed on the cloud's virtual printer, as PNG. Only receipt, escpos, raw and text jobs have one; it is deleted with the job content.", "operationId": "V1JobsController_preview", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "404": { "description": "JOB_NOT_FOUND or NOT_FOUND (no preview)", "content": { "image/png": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "bearer": [] } ], "summary": "Preview of a sandbox job", "tags": [ "v1 jobs" ] } }, "/v1/jobs/{id}/cancel": { "post": { "operationId": "V1JobsController_cancel", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The job, now cancelled.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "idempotencyKey": { "type": [ "string", "null" ] }, "deviceId": { "type": [ "string", "null" ] }, "printerId": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "local", "cloud" ] }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "test: created with a jp_test_ key" }, "type": { "type": "string" }, "templateId": { "description": "The template the job was printed from, if any", "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "queued", "sending", "printed", "failed", "cancelled" ] }, "attempt": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "errorCode": { "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "contentRetained": { "type": "boolean", "description": "Whether the content is still stored (needed to reprint)" }, "hasPreview": { "type": "boolean", "description": "Sandbox jobs (jp_test_ keys): GET /v1/jobs/{id}/preview returns the printed receipt as PNG" }, "createdAt": { "type": "string", "description": "ISO 8601 date-time" }, "updatedAt": { "type": "string", "description": "ISO 8601 date-time" }, "dispatchedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "printedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "queued", "sending", "printed", "failed", "cancelled" ] }, "errorCode": { "type": [ "string", "null" ] }, "at": { "type": "string", "description": "ISO 8601 date-time" } }, "required": [ "state", "errorCode", "at" ], "additionalProperties": false } } }, "required": [ "id", "idempotencyKey", "deviceId", "printerId", "source", "mode", "type", "templateId", "state", "attempt", "errorCode", "errorMessage", "metadata", "contentRetained", "hasPreview", "createdAt", "updatedAt", "dispatchedAt", "printedAt", "expiresAt" ], "additionalProperties": false } } } }, "409": { "description": "JOB_ALREADY_FINISHED", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "bearer": [] } ], "summary": "Cancel a queued cloud job", "tags": [ "v1 jobs" ] } }, "/v1/jobs/{id}/reprint": { "post": { "description": "Only while its content is retained. The new job has metadata.reprintOf.", "operationId": "V1JobsController_reprint", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "The new job.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "idempotencyKey": { "type": [ "string", "null" ] }, "deviceId": { "type": [ "string", "null" ] }, "printerId": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "local", "cloud" ] }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "test: created with a jp_test_ key" }, "type": { "type": "string" }, "templateId": { "description": "The template the job was printed from, if any", "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "queued", "sending", "printed", "failed", "cancelled" ] }, "attempt": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "errorCode": { "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "contentRetained": { "type": "boolean", "description": "Whether the content is still stored (needed to reprint)" }, "hasPreview": { "type": "boolean", "description": "Sandbox jobs (jp_test_ keys): GET /v1/jobs/{id}/preview returns the printed receipt as PNG" }, "createdAt": { "type": "string", "description": "ISO 8601 date-time" }, "updatedAt": { "type": "string", "description": "ISO 8601 date-time" }, "dispatchedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "printedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "queued", "sending", "printed", "failed", "cancelled" ] }, "errorCode": { "type": [ "string", "null" ] }, "at": { "type": "string", "description": "ISO 8601 date-time" } }, "required": [ "state", "errorCode", "at" ], "additionalProperties": false } } }, "required": [ "id", "idempotencyKey", "deviceId", "printerId", "source", "mode", "type", "templateId", "state", "attempt", "errorCode", "errorMessage", "metadata", "contentRetained", "hasPreview", "createdAt", "updatedAt", "dispatchedAt", "printedAt", "expiresAt" ], "additionalProperties": false } } } }, "409": { "description": "CONFLICT: content no longer retained", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "bearer": [] } ], "summary": "Print a job again", "tags": [ "v1 jobs" ] } }, "/v1/devices": { "get": { "operationId": "V1DevicesController_list", "parameters": [ { "name": "cursor", "required": false, "in": "query", "schema": {} }, { "name": "limit", "required": false, "in": "query", "schema": {} }, { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "online", "offline" ], "type": "string" } } ], "responses": { "200": { "description": "A page of devices.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "groupId": { "type": [ "string", "null" ] }, "os": { "type": "string" }, "arch": { "type": "string" }, "agentVersion": { "type": "string" }, "status": { "type": "string", "enum": [ "online", "offline" ] }, "activated": { "type": "boolean" }, "lastSeenAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO 8601 date-time" } }, "required": [ "id", "name", "groupId", "os", "arch", "agentVersion", "status", "activated", "lastSeenAt", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "description": "Pass as ?cursor= for the next page", "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } } }, "security": [ { "bearer": [] } ], "summary": "List active devices", "tags": [ "v1 devices" ] } }, "/v1/devices/{id}": { "get": { "operationId": "V1DevicesController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The device.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "groupId": { "type": [ "string", "null" ] }, "os": { "type": "string" }, "arch": { "type": "string" }, "agentVersion": { "type": "string" }, "status": { "type": "string", "enum": [ "online", "offline" ] }, "activated": { "type": "boolean" }, "lastSeenAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO 8601 date-time" } }, "required": [ "id", "name", "groupId", "os", "arch", "agentVersion", "status", "activated", "lastSeenAt", "createdAt" ], "additionalProperties": false } } } } }, "security": [ { "bearer": [] } ], "summary": "Get a device", "tags": [ "v1 devices" ] } }, "/v1/printers": { "get": { "operationId": "V1PrintersController_list", "parameters": [ { "name": "cursor", "required": false, "in": "query", "schema": {} }, { "name": "limit", "required": false, "in": "query", "schema": {} }, { "name": "status", "required": false, "in": "query", "description": "For example online, offline, paper_out", "schema": {} }, { "name": "deviceId", "required": false, "in": "query", "schema": {} } ], "responses": { "200": { "description": "A page of printers.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cloud printer ID, used as printerId when creating jobs" }, "deviceId": { "type": "string" }, "agentPrinterId": { "type": "string", "description": "The ID the agent uses for this printer" }, "name": { "type": "string" }, "alias": { "type": [ "string", "null" ] }, "connection": { "type": "string" }, "kind": { "type": "string" }, "paper": { "type": [ "string", "null" ] }, "codepage": { "type": [ "string", "null" ] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "isDefault": { "type": "boolean" }, "status": { "type": "string" }, "lastStatusAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] } }, "required": [ "id", "deviceId", "agentPrinterId", "name", "alias", "connection", "kind", "paper", "codepage", "capabilities", "isDefault", "status", "lastStatusAt" ], "additionalProperties": false } }, "nextCursor": { "description": "Pass as ?cursor= for the next page", "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } } }, "security": [ { "bearer": [] } ], "summary": "List printers", "tags": [ "v1 printers" ] } }, "/v1/printers/{id}": { "get": { "operationId": "V1PrintersController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The printer.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "Cloud printer ID, used as printerId when creating jobs" }, "deviceId": { "type": "string" }, "agentPrinterId": { "type": "string", "description": "The ID the agent uses for this printer" }, "name": { "type": "string" }, "alias": { "type": [ "string", "null" ] }, "connection": { "type": "string" }, "kind": { "type": "string" }, "paper": { "type": [ "string", "null" ] }, "codepage": { "type": [ "string", "null" ] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "isDefault": { "type": "boolean" }, "status": { "type": "string" }, "lastStatusAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 date-time" }, { "type": "null" } ] } }, "required": [ "id", "deviceId", "agentPrinterId", "name", "alias", "connection", "kind", "paper", "codepage", "capabilities", "isDefault", "status", "lastStatusAt" ], "additionalProperties": false } } } } }, "security": [ { "bearer": [] } ], "summary": "Get a printer", "tags": [ "v1 printers" ] } }, "/agent/v1/jobs/{id}/content": { "get": { "operationId": "AgentJobContentController_content", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "agent" ] } }, "/orgs/{orgId}/templates": { "get": { "operationId": "TemplatesController_list", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "templates" ] }, "post": { "operationId": "TemplatesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "enum": [ "zpl", "epl", "receipt", "html" ] }, "content": { "type": "string", "minLength": 1, "maxLength": 65536 }, "paper": { "anyOf": [ { "type": "string", "enum": [ "58mm", "80mm", "label-4x6", "label-2x1", "a4", "letter" ] }, { "type": "null" } ] }, "sampleData": { "description": "Example variables for the editor's preview", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "type", "content" ] } } } }, "responses": { "201": { "description": "" } }, "summary": "Create a label, receipt or document (html) template", "tags": [ "templates" ] } }, "/orgs/{orgId}/templates/preview": { "post": { "description": "Renders the template with the data. Returns the text sent to the printer, and for receipts a PNG (base64) exactly as a thermal printer prints it.", "operationId": "TemplatesController_preview", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string", "enum": [ "zpl", "epl", "receipt", "html" ] }, "content": { "type": "string", "minLength": 1, "maxLength": 65536 }, "data": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "paper": { "type": "string", "enum": [ "58mm", "80mm", "label-4x6", "label-2x1", "a4", "letter" ] } }, "required": [ "type", "content" ] } } } }, "responses": { "200": { "description": "" } }, "summary": "Preview a template", "tags": [ "templates" ] } }, "/orgs/{orgId}/templates/{id}": { "get": { "operationId": "TemplatesController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "templates" ] }, "patch": { "operationId": "TemplatesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "enum": [ "zpl", "epl", "receipt", "html" ] }, "content": { "type": "string", "minLength": 1, "maxLength": 65536 }, "paper": { "anyOf": [ { "type": "string", "enum": [ "58mm", "80mm", "label-4x6", "label-2x1", "a4", "letter" ] }, { "type": "null" } ] }, "sampleData": { "description": "Example variables for the editor's preview", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } } } }, "responses": { "200": { "description": "" } }, "tags": [ "templates" ] }, "delete": { "operationId": "TemplatesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "" } }, "tags": [ "templates" ] } }, "/v1/templates": { "get": { "description": "Print one with POST /v1/jobs and { templateId, data }.", "operationId": "V1TemplatesController_list", "parameters": [], "responses": { "200": { "description": "Every template of the organization (one page).", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Use as templateId when creating jobs" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "zpl", "epl", "receipt", "html" ] }, "content": { "type": "string", "description": "Template text with {{variables}}" }, "paper": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "description": "ISO 8601 date-time" }, "updatedAt": { "type": "string", "description": "ISO 8601 date-time" } }, "required": [ "id", "name", "type", "content", "paper", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "description": "Pass as ?cursor= for the next page", "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } } }, "security": [ { "bearer": [] } ], "summary": "List templates", "tags": [ "v1 templates" ] } }, "/v1/templates/{id}": { "get": { "operationId": "V1TemplatesController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The template.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "Use as templateId when creating jobs" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "zpl", "epl", "receipt", "html" ] }, "content": { "type": "string", "description": "Template text with {{variables}}" }, "paper": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "description": "ISO 8601 date-time" }, "updatedAt": { "type": "string", "description": "ISO 8601 date-time" } }, "required": [ "id", "name", "type", "content", "paper", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "bearer": [] } ], "summary": "Get a template", "tags": [ "v1 templates" ] } }, "/orgs/{orgId}/webhooks": { "get": { "operationId": "WebhooksController_list", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "webhooks" ] }, "post": { "operationId": "WebhooksController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "minLength": 8, "maxLength": 2048 }, "events": { "minItems": 1, "maxItems": 13, "type": "array", "items": { "type": "string", "enum": [ "job.queued", "job.printed", "job.failed", "job.cancelled", "printer.online", "printer.offline", "printer.paper_out", "printer.error", "device.online", "device.offline", "device.activated", "alert.opened", "alert.resolved" ] } }, "description": { "type": "string", "maxLength": 200 } }, "required": [ "url", "events" ] } } } }, "responses": { "201": { "description": "The endpoint and its signing secret (shown once).", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "failingSince": { "type": [ "string", "null" ] }, "disabledAt": { "type": [ "string", "null" ] }, "disabledReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "url", "description", "events", "enabled", "failingSince", "disabledAt", "disabledReason", "createdAt" ], "additionalProperties": false }, "secret": { "type": "string", "description": "Shown only now: store it to verify signatures" } }, "required": [ "webhook", "secret" ], "additionalProperties": false } } } } }, "tags": [ "webhooks" ] } }, "/orgs/{orgId}/webhooks/{id}": { "get": { "operationId": "WebhooksController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "webhooks" ] }, "patch": { "operationId": "WebhooksController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "minLength": 8, "maxLength": 2048 }, "events": { "minItems": 1, "maxItems": 13, "type": "array", "items": { "type": "string", "enum": [ "job.queued", "job.printed", "job.failed", "job.cancelled", "printer.online", "printer.offline", "printer.paper_out", "printer.error", "device.online", "device.offline", "device.activated", "alert.opened", "alert.resolved" ] } }, "description": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "" } }, "tags": [ "webhooks" ] }, "delete": { "operationId": "WebhooksController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "webhooks" ] } }, "/orgs/{orgId}/webhooks/{id}/rotate-secret": { "post": { "operationId": "WebhooksController_rotate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "webhooks" ] } }, "/orgs/{orgId}/webhooks/{id}/test": { "post": { "operationId": "WebhooksController_test", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "summary": "Send a webhook.test event to this endpoint", "tags": [ "webhooks" ] } }, "/orgs/{orgId}/webhooks/{id}/deliveries": { "get": { "operationId": "WebhooksController_deliveries", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delivery log, newest first.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "eventId": { "type": "string" }, "event": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed" ] }, "attempts": { "type": "number" }, "lastResponseCode": { "type": [ "number", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "durationMs": { "type": [ "number", "null" ] }, "deliveredAt": { "type": [ "string", "null" ] }, "nextAttemptAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "eventId", "event", "status", "attempts", "lastResponseCode", "lastError", "durationMs", "deliveredAt", "nextAttemptAt", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } } }, "tags": [ "webhooks" ] } }, "/orgs/{orgId}/webhooks/{id}/deliveries/{deliveryId}": { "get": { "operationId": "WebhooksController_delivery", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "deliveryId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "webhooks" ] } }, "/orgs/{orgId}/webhooks/{id}/deliveries/{deliveryId}/resend": { "post": { "operationId": "WebhooksController_resend", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "deliveryId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "summary": "Send the same event again (same event ID)", "tags": [ "webhooks" ] } }, "/v1/webhooks": { "get": { "operationId": "V1WebhooksController_list", "parameters": [], "responses": { "200": { "description": "The organization's endpoints.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "failingSince": { "type": [ "string", "null" ] }, "disabledAt": { "type": [ "string", "null" ] }, "disabledReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "url", "description", "events", "enabled", "failingSince", "disabledAt", "disabledReason", "createdAt" ], "additionalProperties": false } } } } } }, "security": [ { "bearer": [] } ], "tags": [ "v1 webhooks" ] }, "post": { "operationId": "V1WebhooksController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "minLength": 8, "maxLength": 2048 }, "events": { "minItems": 1, "maxItems": 13, "type": "array", "items": { "type": "string", "enum": [ "job.queued", "job.printed", "job.failed", "job.cancelled", "printer.online", "printer.offline", "printer.paper_out", "printer.error", "device.online", "device.offline", "device.activated", "alert.opened", "alert.resolved" ] } }, "description": { "type": "string", "maxLength": 200 } }, "required": [ "url", "events" ] } } } }, "responses": { "201": { "description": "The endpoint and its signing secret (shown once).", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "failingSince": { "type": [ "string", "null" ] }, "disabledAt": { "type": [ "string", "null" ] }, "disabledReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "url", "description", "events", "enabled", "failingSince", "disabledAt", "disabledReason", "createdAt" ], "additionalProperties": false }, "secret": { "type": "string", "description": "Shown only now: store it to verify signatures" } }, "required": [ "webhook", "secret" ], "additionalProperties": false } } } } }, "security": [ { "bearer": [] } ], "tags": [ "v1 webhooks" ] } }, "/v1/webhooks/{id}": { "delete": { "operationId": "V1WebhooksController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "v1 webhooks" ] } }, "/orgs/{orgId}/alerts/rules": { "get": { "operationId": "AlertsController_rules", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "alerts" ] }, "post": { "operationId": "AlertsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string", "enum": [ "device_offline", "printer_offline", "paper_out", "job_failed_rate" ] }, "thresholdMinutes": { "default": 5, "type": "integer", "minimum": 1, "maximum": 1440 }, "thresholdPercent": { "type": "integer", "minimum": 1, "maximum": 100 }, "channels": { "type": "object", "properties": { "email": { "type": "object", "properties": { "to": { "maxItems": 10, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } } } }, "sms": { "type": "object", "properties": { "to": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" } } }, "required": [ "to" ] }, "whatsapp": { "type": "object", "properties": { "to": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" } } }, "required": [ "to" ] }, "webhook": { "type": "boolean" } } }, "enabled": { "default": true, "type": "boolean" } }, "required": [ "type", "channels" ] } } } }, "responses": { "201": { "description": "" } }, "tags": [ "alerts" ] } }, "/orgs/{orgId}/alerts/rules/{id}": { "patch": { "operationId": "AlertsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "thresholdMinutes": { "type": "integer", "minimum": 1, "maximum": 1440 }, "thresholdPercent": { "type": "integer", "minimum": 1, "maximum": 100 }, "channels": { "type": "object", "properties": { "email": { "type": "object", "properties": { "to": { "maxItems": 10, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } } } }, "sms": { "type": "object", "properties": { "to": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" } } }, "required": [ "to" ] }, "whatsapp": { "type": "object", "properties": { "to": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" } } }, "required": [ "to" ] }, "webhook": { "type": "boolean" } } }, "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "" } }, "tags": [ "alerts" ] }, "delete": { "operationId": "AlertsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "alerts" ] } }, "/orgs/{orgId}/alerts/incidents": { "get": { "operationId": "AlertsController_incidents", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "alerts" ] } }, "/admin/releases": { "get": { "operationId": "AdminReleasesController_list", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "admin" ] }, "post": { "operationId": "AdminReleasesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brand": { "default": "jodaprint", "type": "string", "pattern": "^[a-z][a-z0-9-]{0,30}[a-z0-9]$" }, "version": { "type": "string" }, "platform": { "type": "string", "enum": [ "windows", "darwin", "linux", "android" ] }, "arch": { "type": "string", "enum": [ "amd64", "arm64", "universal" ] }, "channel": { "default": "beta", "type": "string", "enum": [ "stable", "beta" ] }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9_-]{86}$" }, "minSupportedVersion": { "type": "string" }, "rolloutPercent": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100 }, "notes": { "type": "string", "maxLength": 20000 }, "publish": { "default": false, "type": "boolean" } }, "required": [ "version", "platform", "arch", "url", "sha256", "signature", "minSupportedVersion" ] } } } }, "responses": { "201": { "description": "" } }, "summary": "Register a signed release (unpublished unless publish: true)", "tags": [ "admin" ] } }, "/admin/releases/{id}": { "patch": { "operationId": "AdminReleasesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "stable", "beta" ] }, "rolloutPercent": { "type": "integer", "minimum": 0, "maximum": 100 }, "minSupportedVersion": { "type": "string" }, "notes": { "anyOf": [ { "type": "string", "maxLength": 20000 }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "" } }, "tags": [ "admin" ] } }, "/admin/releases/{id}/publish": { "post": { "operationId": "AdminReleasesController_publish", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "admin" ] } }, "/admin/releases/{id}/pause": { "post": { "operationId": "AdminReleasesController_pause", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "admin" ] } }, "/admin/releases/{id}/resume": { "post": { "operationId": "AdminReleasesController_resume", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "admin" ] } }, "/admin/releases/{id}/mark-bad": { "post": { "operationId": "AdminReleasesController_markBad", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "admin" ] } }, "/agent/v1/releases/latest": { "get": { "operationId": "AgentReleasesController_latest", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "agent" ] } }, "/orgs/{orgId}/agent-versions": { "get": { "operationId": "AgentVersionsController_list", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "devices" ] } }, "/admin/installers": { "get": { "operationId": "AdminInstallersController_list", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "admin" ] }, "post": { "operationId": "AdminInstallersController_upload", "parameters": [], "responses": { "201": { "description": "" } }, "summary": "Upload an installer (raw body, application/octet-stream); unpublished at first", "tags": [ "admin" ] } }, "/admin/installers/{id}/publish": { "post": { "operationId": "AdminInstallersController_publish", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "admin" ] } }, "/admin/installers/{id}/unpublish": { "post": { "operationId": "AdminInstallersController_unpublish", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "admin" ] } }, "/admin/installers/{id}": { "delete": { "operationId": "AdminInstallersController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "admin" ] } }, "/orgs/{orgId}/installers": { "get": { "operationId": "OrgInstallersController_list", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "downloads" ] } }, "/downloads/installers/{id}/{fileName}": { "get": { "operationId": "PublicInstallersController_download", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "fileName", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Download a published installer", "tags": [ "downloads" ] } }, "/downloads/install.ps1": { "get": { "operationId": "WindowsScriptController_script", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "PowerShell script that installs and activates the agent on Windows", "tags": [ "downloads" ] } }, "/orgs/{orgId}/audit": { "get": { "operationId": "AuditController_list", "parameters": [ { "name": "action", "required": false, "in": "query", "description": "Exact action, or a prefix such as device.*", "schema": {} } ], "responses": { "200": { "description": "" } }, "tags": [ "audit" ] } }, "/users/me/security-events": { "get": { "operationId": "SecurityEventsController_list", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "users" ] } }, "/branding": { "get": { "operationId": "BrandingController_byHost", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "branding" ] } }, "/orgs/{orgId}/branding": { "get": { "operationId": "BrandingController_byOrg", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "branding" ] } }, "/orgs/{orgId}/reseller": { "get": { "operationId": "ResellerController_get", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "reseller" ] } }, "/orgs/{orgId}/reseller/branding": { "patch": { "operationId": "ResellerController_updateBrand", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "productName": { "type": "string", "minLength": 1, "maxLength": 60 }, "logoUrl": { "anyOf": [ { "type": "string", "maxLength": 500, "format": "uri" }, { "type": "null" } ] }, "faviconUrl": { "anyOf": [ { "type": "string", "maxLength": 500, "format": "uri" }, { "type": "null" } ] }, "primaryColor": { "anyOf": [ { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, { "type": "null" } ] }, "secondaryColor": { "anyOf": [ { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, { "type": "null" } ] }, "supportEmail": { "anyOf": [ { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "supportUrl": { "anyOf": [ { "type": "string", "maxLength": 500, "format": "uri" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "" } }, "tags": [ "reseller" ] } }, "/orgs/{orgId}/reseller/customers": { "get": { "operationId": "ResellerController_customers", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "reseller" ] }, "post": { "operationId": "ResellerController_createCustomer", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "ownerEmail": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "locale": { "type": "string", "enum": [ "en", "fr", "ht" ] }, "planCode": { "type": "string", "pattern": "^[a-z0-9_-]{1,32}$" } }, "required": [ "name", "ownerEmail" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "" } }, "tags": [ "reseller" ] } }, "/orgs/{orgId}/reseller/customers/{customerId}/plan": { "post": { "operationId": "ResellerController_setPlan", "parameters": [ { "name": "customerId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "planCode": { "type": "string", "pattern": "^[a-z0-9_-]{1,32}$" } }, "required": [ "planCode" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "" } }, "tags": [ "reseller" ] } }, "/orgs/{orgId}/reseller/customers/{customerId}": { "delete": { "operationId": "ResellerController_deleteCustomer", "parameters": [ { "name": "customerId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "reseller" ] } }, "/admin/white-labels": { "get": { "operationId": "AdminWhiteLabelsController_list", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "admin" ] }, "post": { "operationId": "AdminWhiteLabelsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "productName": { "type": "string", "minLength": 1, "maxLength": 60 }, "logoUrl": { "anyOf": [ { "type": "string", "maxLength": 500, "format": "uri" }, { "type": "null" } ] }, "faviconUrl": { "anyOf": [ { "type": "string", "maxLength": 500, "format": "uri" }, { "type": "null" } ] }, "primaryColor": { "anyOf": [ { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, { "type": "null" } ] }, "secondaryColor": { "anyOf": [ { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, { "type": "null" } ] }, "supportEmail": { "anyOf": [ { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "supportUrl": { "anyOf": [ { "type": "string", "maxLength": 500, "format": "uri" }, { "type": "null" } ] }, "domain": { "type": [ "string", "null" ] }, "installerName": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._-]{0,39}$" }, { "type": "null" } ] }, "buildId": { "anyOf": [ { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,30}[a-z0-9]$" }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "" } }, "tags": [ "admin" ] } }, "/admin/white-labels/{id}": { "patch": { "operationId": "AdminWhiteLabelsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "productName": { "type": "string", "minLength": 1, "maxLength": 60 }, "logoUrl": { "anyOf": [ { "type": "string", "maxLength": 500, "format": "uri" }, { "type": "null" } ] }, "faviconUrl": { "anyOf": [ { "type": "string", "maxLength": 500, "format": "uri" }, { "type": "null" } ] }, "primaryColor": { "anyOf": [ { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, { "type": "null" } ] }, "secondaryColor": { "anyOf": [ { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, { "type": "null" } ] }, "supportEmail": { "anyOf": [ { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "supportUrl": { "anyOf": [ { "type": "string", "maxLength": 500, "format": "uri" }, { "type": "null" } ] }, "domain": { "type": [ "string", "null" ] }, "installerName": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._-]{0,39}$" }, { "type": "null" } ] }, "buildId": { "anyOf": [ { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,30}[a-z0-9]$" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "" } }, "tags": [ "admin" ] }, "delete": { "operationId": "AdminWhiteLabelsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "admin" ] } }, "/admin/white-labels/{id}/reseller": { "post": { "operationId": "AdminWhiteLabelsController_attach", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "pattern": "^org_[0-9A-Za-z]{1,40}$" } }, "required": [ "organizationId" ] } } } }, "responses": { "200": { "description": "" } }, "tags": [ "admin" ] }, "delete": { "operationId": "AdminWhiteLabelsController_detach", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "admin" ] } }, "/admin/users": { "get": { "operationId": "AdminUsersController_list", "parameters": [ { "name": "q", "required": false, "in": "query", "description": "Part of the email or the name", "schema": {} } ], "responses": { "200": { "description": "" } }, "summary": "Every user account, newest first (platform admin)", "tags": [ "admin" ] } }, "/admin/users/{id}": { "get": { "operationId": "AdminUsersController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "admin" ] }, "patch": { "operationId": "AdminUsersController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "isSuperuser": { "type": "boolean" }, "emailVerified": { "type": "boolean", "const": true }, "disabled": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "" } }, "summary": "Grant or revoke superuser, mark verified, disable or enable", "tags": [ "admin" ] } }, "/admin/stats": { "get": { "operationId": "AdminStatsController_get", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Platform-wide counts (platform admin)", "tags": [ "admin" ] } }, "/admin/billing/subscriptions": { "get": { "operationId": "AdminBillingOverviewController_subscriptions", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "active", "past_due", "canceled", "none" ], "type": "string" } }, { "name": "q", "required": false, "in": "query", "schema": {} } ], "responses": { "200": { "description": "" } }, "summary": "Organizations with plan and subscription (platform admin)", "tags": [ "admin" ] } }, "/admin/billing/usage": { "get": { "operationId": "AdminBillingOverviewController_usage", "parameters": [ { "name": "sort", "required": false, "in": "query", "schema": { "enum": [ "jobs", "devices", "name" ], "type": "string" } }, { "name": "nearLimit", "required": false, "in": "query", "schema": {} } ], "responses": { "200": { "description": "" } }, "summary": "Jobs this month and devices against plan limits (platform admin)", "tags": [ "admin" ] } }, "/admin/plans": { "get": { "operationId": "AdminPlansController_list", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Plans with their limits and features (platform admin)", "tags": [ "admin" ] } }, "/admin/plans/{code}": { "patch": { "operationId": "AdminPlansController_update", "parameters": [ { "name": "code", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "maxDevices": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100000000 }, { "type": "null" } ] }, "maxJobsPerMonth": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100000000 }, { "type": "null" } ] }, "features": { "maxItems": 6, "type": "array", "items": { "type": "string", "enum": [ "alerts", "footer", "roles", "selfHosted", "webhooks", "whiteLabel" ] } }, "stripePriceId": { "anyOf": [ { "type": "string", "pattern": "^price_[A-Za-z0-9]{1,100}$" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "" } }, "summary": "Edit a plan's name, limits, features or Stripe price", "tags": [ "admin" ] } } }, "info": { "title": "JodaPrint API", "description": "Public API v1 (`/v1`, API keys in `Authorization: Bearer jp_live_…`), the dashboard API and the agent endpoints. Errors use the A9 format `{ error: { code, message, retryable, details? }, requestId }`; every response has an `x-request-id` header. Lists return `{ data, nextCursor }`.", "version": "1", "contact": {} }, "tags": [], "servers": [], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http" } }, "schemas": { "agent-activate-request": { "title": "ActivateRequest", "description": "agent -> cloud: POST /agent/v1/activate. Exchanges an activation code for a device token.", "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Activation code as shown (KJ74-PX9Q-M3TZ; older codes have 8 characters); case and dashes are ignored.", "pattern": "^[A-Za-z0-9]{4}-?[A-Za-z0-9]{4}(-?[A-Za-z0-9]{4})?$" }, "deviceId": { "type": "string", "pattern": "^dev_[A-Za-z0-9]{1,64}$" }, "publicKey": { "type": "string", "description": "Device Ed25519 public key: raw 32 bytes, standard base64.", "pattern": "^[A-Za-z0-9+/]{43}=$" }, "os": { "type": "string", "enum": [ "windows", "darwin", "linux", "android" ] }, "arch": { "type": "string", "enum": [ "amd64", "arm64", "arm", "386" ] }, "hostname": { "type": "string", "description": "Machine name; the default device name.", "minLength": 1, "maxLength": 253 }, "agentVersion": { "type": "string", "description": "Agent version.", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(-[0-9A-Za-z.-]+)?(\\+[0-9A-Za-z.-]+)?$" }, "releaseChannel": { "type": "string", "enum": [ "stable", "beta" ], "description": "Update channel chosen at install (installer CHANNEL property); stable when omitted." } }, "required": [ "code", "deviceId", "publicKey", "os", "arch", "hostname", "agentVersion" ] }, "agent-activate-response": { "title": "ActivateResponse", "description": "cloud -> agent: result of a successful activation. deviceToken is shown only here.", "type": "object", "additionalProperties": false, "properties": { "deviceToken": { "type": "string", "description": "Bearer token for /agent/v1 requests and the agent WebSocket.", "pattern": "^jpd_[A-Za-z0-9]{32,64}$" }, "orgId": { "type": "string", "pattern": "^org_[A-Za-z0-9]{1,64}$" }, "orgName": { "type": "string", "description": "The organization's name, for display.", "minLength": 1, "maxLength": 200 }, "deviceId": { "type": "string", "pattern": "^dev_[A-Za-z0-9]{1,64}$" }, "deviceName": { "type": "string", "minLength": 1, "maxLength": 253 }, "config": { "$ref": "#/components/schemas/config" }, "configHash": { "type": "string", "description": "SHA-256 of the merged config (RFC 8785 canonical JSON), lowercase hex.", "pattern": "^[a-f0-9]{64}$" }, "licenseToken": { "type": "string", "description": "License JWT (EdDSA).", "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" } }, "required": [ "deviceToken", "orgId", "deviceId", "deviceName", "config", "configHash", "licenseToken" ] }, "agent-config-response": { "title": "AgentConfigResponse", "description": "cloud -> agent: GET /agent/v1/config, the merged config for the calling device (A13).", "type": "object", "additionalProperties": false, "properties": { "config": { "$ref": "#/components/schemas/config" }, "configHash": { "type": "string", "description": "SHA-256 of the merged config (RFC 8785 canonical JSON), lowercase hex.", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "config", "configHash" ] }, "agent-info": { "title": "AgentInfo", "description": "Result of agent.info (A6).", "type": "object", "additionalProperties": false, "properties": { "version": { "type": "string", "description": "Agent version (semver).", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(-[0-9A-Za-z.-]+)?(\\+[0-9A-Za-z.-]+)?$" }, "os": { "type": "string", "enum": [ "windows", "darwin", "linux", "android" ] }, "arch": { "type": "string", "enum": [ "amd64", "arm64", "arm", "386" ] }, "deviceId": { "type": "string", "description": "Device ID, generated once per installation.", "pattern": "^dev_[A-Za-z0-9]{1,64}$" }, "orgId": { "oneOf": [ { "type": "string", "pattern": "^org_[A-Za-z0-9]{1,64}$" }, { "type": "null" } ], "description": "Organization ID, null before activation." }, "activated": { "type": "boolean", "description": "True once the agent is activated." }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/capability" }, "uniqueItems": true } }, "required": [ "version", "os", "arch", "deviceId", "orgId", "activated", "capabilities" ] }, "auth": { "title": "RequestAuth", "description": "Request signature (A10.1). The signed string is v1\\n{method}\\n{orgId}\\n{ts}\\n{nonce}\\n{sha256_hex(canonical_json(params))}.", "type": "object", "additionalProperties": false, "properties": { "orgId": { "type": "string", "description": "Organization ID.", "pattern": "^org_[A-Za-z0-9]{1,64}$" }, "keyId": { "type": "string", "description": "Signing key ID.", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "ts": { "type": "integer", "description": "Unix time in seconds when the request was signed.", "minimum": 0 }, "nonce": { "type": "string", "description": "Random value, base64url, at least 16 bytes.", "pattern": "^[A-Za-z0-9_-]{22,88}$" }, "sig": { "type": "string", "description": "Ed25519 signature, base64url without padding.", "pattern": "^[A-Za-z0-9_-]{86}$" } }, "required": [ "orgId", "keyId", "ts", "nonce", "sig" ] }, "capability": { "title": "AgentCapability", "type": "string", "enum": [ "escpos", "receipt", "raw", "zpl", "epl", "pdf", "image", "text", "html", "drawer", "status.realtime", "template" ] }, "cloud-challenge": { "title": "ChallengeMessage", "description": "cloud -> agent: First message after connect. The agent signs v1\\nchallenge\\n{deviceId}\\n{nonce} with its device key and sends the signature in hello.", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "id": { "type": "string", "description": "Message ID, unique per connection.", "minLength": 1, "maxLength": 128 }, "type": { "const": "challenge" }, "data": { "type": "object", "additionalProperties": false, "properties": { "nonce": { "type": "string", "description": "Random nonce, base64url.", "pattern": "^[A-Za-z0-9_-]{22,88}$" }, "serverTime": { "type": "string", "format": "date-time", "description": "Server time." } }, "required": [ "nonce", "serverTime" ] } }, "required": [ "v", "id", "type", "data" ] }, "cloud-config-updated": { "title": "ConfigUpdatedMessage", "description": "cloud -> agent: New merged config.", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "id": { "type": "string", "description": "Message ID, unique per connection.", "minLength": 1, "maxLength": 128 }, "type": { "const": "config.updated" }, "data": { "type": "object", "additionalProperties": false, "properties": { "configHash": { "type": "string", "description": "SHA-256 of the merged config.", "pattern": "^[a-f0-9]{64}$" }, "config": { "$ref": "#/components/schemas/config" } }, "required": [ "configHash", "config" ] } }, "required": [ "v", "id", "type", "data" ] }, "cloud-heartbeat": { "title": "HeartbeatMessage", "description": "agent -> cloud: Periodic health report.", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "id": { "type": "string", "description": "Message ID, unique per connection.", "minLength": 1, "maxLength": 128 }, "type": { "const": "heartbeat" }, "data": { "type": "object", "additionalProperties": false, "properties": { "uptimeSeconds": { "type": "integer", "description": "Agent uptime.", "minimum": 0 }, "printers": { "type": "array", "items": { "$ref": "#/components/schemas/printer-status" } }, "queueSize": { "type": "integer", "description": "Jobs waiting in the local queue.", "minimum": 0 }, "lastError": { "type": "object", "additionalProperties": false, "properties": { "code": { "$ref": "#/components/schemas/error-code" }, "message": { "type": "string", "description": "Message.", "maxLength": 1000 }, "at": { "type": "string", "format": "date-time", "description": "When it happened." } }, "required": [ "code", "message", "at" ], "title": "HeartbeatLastError" } }, "required": [ "uptimeSeconds", "printers", "queueSize" ] } }, "required": [ "v", "id", "type", "data" ] }, "cloud-hello": { "title": "HelloMessage", "description": "agent -> cloud: Answers the challenge and reports the device state.", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "id": { "type": "string", "description": "Message ID, unique per connection.", "minLength": 1, "maxLength": 128 }, "type": { "const": "hello" }, "data": { "type": "object", "additionalProperties": false, "properties": { "deviceId": { "type": "string", "pattern": "^dev_[A-Za-z0-9]{1,64}$" }, "version": { "type": "string", "description": "Agent version.", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(-[0-9A-Za-z.-]+)?(\\+[0-9A-Za-z.-]+)?$" }, "os": { "type": "string", "enum": [ "windows", "darwin", "linux", "android" ] }, "arch": { "type": "string", "enum": [ "amd64", "arm64", "arm", "386" ] }, "printers": { "type": "array", "items": { "$ref": "#/components/schemas/printer" } }, "queueSize": { "type": "integer", "description": "Jobs waiting in the local queue.", "minimum": 0 }, "configHash": { "oneOf": [ { "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" } ], "description": "SHA-256 of the cached config, null if none." }, "licenseExp": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "exp of the cached license token, null if none." }, "challengeSignature": { "type": "string", "description": "Ed25519 signature over the challenge string, base64url.", "pattern": "^[A-Za-z0-9_-]{86}$" } }, "required": [ "deviceId", "version", "os", "arch", "printers", "queueSize", "configHash", "licenseExp", "challengeSignature" ] } }, "required": [ "v", "id", "type", "data" ] }, "cloud-job-ack": { "title": "JobAckMessage", "description": "agent -> cloud: The job is persisted in the agent queue.", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "id": { "type": "string", "description": "Message ID, unique per connection.", "minLength": 1, "maxLength": 128 }, "type": { "const": "job.ack" }, "data": { "type": "object", "additionalProperties": false, "properties": { "jobId": { "type": "string", "pattern": "^job_[A-Za-z0-9]{1,64}$" } }, "required": [ "jobId" ] } }, "required": [ "v", "id", "type", "data" ] }, "cloud-job-cancel": { "title": "JobCancelMessage", "description": "cloud -> agent: Cancel a queued cloud job.", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "id": { "type": "string", "description": "Message ID, unique per connection.", "minLength": 1, "maxLength": 128 }, "type": { "const": "job.cancel" }, "data": { "type": "object", "additionalProperties": false, "properties": { "jobId": { "type": "string", "pattern": "^job_[A-Za-z0-9]{1,64}$" } }, "required": [ "jobId" ] } }, "required": [ "v", "id", "type", "data" ] }, "cloud-job-dispatch": { "title": "JobDispatchMessage", "description": "cloud -> agent: A cloud job to print. Large content uses encoding url with a short-lived signed URL.", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "id": { "type": "string", "description": "Message ID, unique per connection.", "minLength": 1, "maxLength": 128 }, "type": { "const": "job.dispatch" }, "data": { "type": "object", "additionalProperties": false, "properties": { "jobId": { "type": "string", "pattern": "^job_[A-Za-z0-9]{1,64}$" }, "request": { "$ref": "#/components/schemas/job-request" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the cloud accepted the job." }, "expiresAt": { "type": "string", "format": "date-time", "description": "After this time the job fails with TIMEOUT." } }, "required": [ "jobId", "request", "createdAt", "expiresAt" ] } }, "required": [ "v", "id", "type", "data" ] }, "cloud-job-update-ack": { "title": "JobUpdateAckMessage", "description": "cloud -> agent: These job.update messages are stored in the cloud database; the agent removes them from its outbox (ADR 0046).", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "id": { "type": "string", "description": "Message ID, unique per connection.", "minLength": 1, "maxLength": 128 }, "type": { "const": "job.update.ack" }, "data": { "type": "object", "additionalProperties": false, "properties": { "seqs": { "type": "array", "description": "The seq of every stored job.update this message acknowledges.", "minItems": 1, "maxItems": 1000, "items": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } } }, "required": [ "seqs" ] } }, "required": [ "v", "id", "type", "data" ] }, "cloud-job-update": { "title": "JobUpdateMessage", "description": "agent -> cloud: A job state change, for cloud and local jobs.", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "id": { "type": "string", "description": "Message ID, unique per connection.", "minLength": 1, "maxLength": 128 }, "type": { "const": "job.update" }, "seq": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Outbox sequence number (ADR 0046). Sent only when the cloud's welcome lists the \"job.update.ack\" feature; the cloud answers job.update.ack with it once the update is stored. Stable across resends of the same update." }, "data": { "$ref": "#/components/schemas/job" } }, "required": [ "v", "id", "type", "data" ] }, "cloud-license-updated": { "title": "LicenseUpdatedMessage", "description": "cloud -> agent: A new license token.", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "id": { "type": "string", "description": "Message ID, unique per connection.", "minLength": 1, "maxLength": 128 }, "type": { "const": "license.updated" }, "data": { "type": "object", "additionalProperties": false, "properties": { "token": { "type": "string", "description": "License JWT.", "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "selfHostLicense": { "type": "string", "description": "Self-hosted edition only: the installation's self-host license JWT (EdDSA, issuer jodaprint-selfhost, signed by JodaPrint). Agents verify it with an embedded JodaPrint key and then also trust the device-license keys it lists in deviceLicenseKeys (ADR 0047). Absent on the JodaPrint cloud.", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" } }, "required": [ "token" ] } }, "required": [ "v", "id", "type", "data" ] }, "cloud-logs-request": { "title": "LogsRequestMessage", "description": "cloud -> agent: Upload recent logs over HTTPS.", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "id": { "type": "string", "description": "Message ID, unique per connection.", "minLength": 1, "maxLength": 128 }, "type": { "const": "logs.request" }, "data": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "type": "string", "description": "Request ID to include in the upload.", "minLength": 1, "maxLength": 128 }, "maxMb": { "type": "integer", "description": "Maximum upload size.", "minimum": 1, "maximum": 50 }, "uploadUrl": { "type": "string", "description": "HTTPS upload URL.", "format": "uri", "pattern": "^https?://" } }, "required": [ "requestId", "maxMb", "uploadUrl" ] } }, "required": [ "v", "id", "type", "data" ] }, "cloud-message": { "title": "CloudMessage", "description": "Any message on the agent <-> cloud WebSocket (A12).", "oneOf": [ { "$ref": "#/components/schemas/cloud-challenge" }, { "$ref": "#/components/schemas/cloud-hello" }, { "$ref": "#/components/schemas/cloud-welcome" }, { "$ref": "#/components/schemas/cloud-heartbeat" }, { "$ref": "#/components/schemas/cloud-printers-changed" }, { "$ref": "#/components/schemas/cloud-printer-status" }, { "$ref": "#/components/schemas/cloud-job-dispatch" }, { "$ref": "#/components/schemas/cloud-job-ack" }, { "$ref": "#/components/schemas/cloud-job-update" }, { "$ref": "#/components/schemas/cloud-job-update-ack" }, { "$ref": "#/components/schemas/cloud-job-cancel" }, { "$ref": "#/components/schemas/cloud-config-updated" }, { "$ref": "#/components/schemas/cloud-update-available" }, { "$ref": "#/components/schemas/cloud-logs-request" }, { "$ref": "#/components/schemas/cloud-license-updated" }, { "$ref": "#/components/schemas/cloud-update-failed" } ] }, "cloud-printer-status": { "title": "PrinterStatusMessage", "description": "agent -> cloud: A printer status change.", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "id": { "type": "string", "description": "Message ID, unique per connection.", "minLength": 1, "maxLength": 128 }, "type": { "const": "printer.status" }, "data": { "$ref": "#/components/schemas/printer-status" } }, "required": [ "v", "id", "type", "data" ] }, "cloud-printers-changed": { "title": "PrintersChangedMessage", "description": "agent -> cloud: Full printer list after a printer was added, removed or renamed.", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "id": { "type": "string", "description": "Message ID, unique per connection.", "minLength": 1, "maxLength": 128 }, "type": { "const": "printers.changed" }, "data": { "type": "object", "additionalProperties": false, "properties": { "printers": { "type": "array", "items": { "$ref": "#/components/schemas/printer" } } }, "required": [ "printers" ] } }, "required": [ "v", "id", "type", "data" ] }, "cloud-update-available": { "title": "UpdateAvailableMessage", "description": "cloud -> agent: A release for this device.", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "id": { "type": "string", "description": "Message ID, unique per connection.", "minLength": 1, "maxLength": 128 }, "type": { "const": "update.available" }, "data": { "$ref": "#/components/schemas/release-manifest" } }, "required": [ "v", "id", "type", "data" ] }, "cloud-update-failed": { "title": "UpdateFailedMessage", "description": "agent -> cloud: An update could not be installed; the agent went back to its previous version (A14).", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "id": { "type": "string", "description": "Message ID, unique per connection.", "minLength": 1, "maxLength": 128 }, "type": { "const": "update.failed" }, "data": { "type": "object", "additionalProperties": false, "properties": { "version": { "type": "string", "description": "The version that failed to install.", "minLength": 1, "maxLength": 64 }, "fromVersion": { "type": "string", "description": "The version the agent runs again.", "minLength": 1, "maxLength": 64 }, "stage": { "enum": [ "download", "verify", "install", "health" ], "description": "Where it failed: download, signature or hash check, binary swap, or the new version did not report healthy within 2 minutes." }, "reason": { "type": "string", "maxLength": 1000 }, "at": { "type": "string", "format": "date-time" } }, "required": [ "version", "fromVersion", "stage", "reason", "at" ] } }, "required": [ "v", "id", "type", "data" ] }, "cloud-welcome": { "title": "WelcomeMessage", "description": "cloud -> agent: Accepts the connection. config and licenseToken are present only when they changed.", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "id": { "type": "string", "description": "Message ID, unique per connection.", "minLength": 1, "maxLength": 128 }, "type": { "const": "welcome" }, "data": { "type": "object", "additionalProperties": false, "properties": { "serverTime": { "type": "string", "format": "date-time", "description": "Server time." }, "configHash": { "type": "string", "description": "SHA-256 of the merged config.", "pattern": "^[a-f0-9]{64}$" }, "config": { "$ref": "#/components/schemas/config" }, "licenseToken": { "type": "string", "description": "License JWT.", "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "selfHostLicense": { "type": "string", "description": "Self-hosted edition only: the installation's self-host license JWT (EdDSA, issuer jodaprint-selfhost, signed by JodaPrint). Agents verify it with an embedded JodaPrint key and then also trust the device-license keys it lists in deviceLicenseKeys (ADR 0047). Absent on the JodaPrint cloud.", "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "update": { "$ref": "#/components/schemas/release-manifest" }, "features": { "type": "array", "description": "Optional protocol features this cloud supports (ADR 0046), e.g. \"job.update.ack\". Agents ignore names they do not know; absent means none.", "maxItems": 64, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-z][a-z0-9.-]{0,63}$" } } }, "required": [ "serverTime", "configHash" ] } }, "required": [ "v", "id", "type", "data" ] }, "codepage": { "title": "Codepage", "type": "string", "enum": [ "CP437", "CP850", "CP858", "CP1252", "CP866", "ISO-8859-15" ] }, "config": { "title": "AgentConfig", "description": "Agent configuration (A13). Every field is optional so partial profiles validate; the merged config has all of them.", "type": "object", "properties": { "configVersion": { "const": 1 }, "cloud": { "type": "object", "properties": { "url": { "type": "string", "description": "Cloud base URL.", "format": "uri", "pattern": "^https?://" }, "heartbeatSeconds": { "type": "integer", "description": "Heartbeat interval.", "minimum": 5, "maximum": 600 } } }, "local": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Run the local WebSocket server." }, "ports": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "integer", "description": "Port.", "minimum": 1024, "maximum": 65535 }, "uniqueItems": true }, "standalone": { "type": "boolean", "description": "Serve signed local requests without cloud activation (self-hosted/offline). Requires local.orgId and security.signingPublicKeys." }, "orgId": { "type": "string", "pattern": "^org_[A-Za-z0-9]{1,64}$", "description": "Organization ID in standalone mode." }, "rateLimitPerSecond": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Requests per second allowed from one origin. Defaults to 50." } } }, "security": { "type": "object", "properties": { "allowedOrigins": { "type": "array", "items": { "type": "string", "pattern": "^https?://[A-Za-z0-9.-]+(:[0-9]{1,5})?$|^https?://\\[[0-9A-Fa-f:]+\\](:[0-9]{1,5})?$" }, "uniqueItems": true }, "signingPublicKeys": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "keyId": { "type": "string", "description": "Signing key ID.", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "publicKey": { "type": "string", "description": "Raw 32-byte Ed25519 public key, standard base64.", "pattern": "^[A-Za-z0-9+/]{43}=$" } }, "required": [ "keyId", "publicKey" ], "title": "SigningPublicKey" } }, "requireSignature": { "type": "boolean", "description": "Reject unsigned requests." }, "unsignedMode": { "type": "boolean", "description": "Allow unsigned requests after the user approves the site (A10.3)." }, "devMode": { "type": "boolean", "description": "Also allow http://localhost:* origins." } } }, "printers": { "type": "object", "properties": { "aliases": { "type": "object", "propertyNames": { "pattern": "^[A-Za-z0-9_.-]{1,64}$" }, "additionalProperties": { "type": "string", "pattern": "^prn_[A-Za-z0-9]{1,64}$" } }, "defaults": { "type": "object", "propertyNames": { "pattern": "^prn_[A-Za-z0-9]{1,64}$" }, "additionalProperties": { "$ref": "#/components/schemas/job-options" } }, "discovery": { "type": "object", "properties": { "network": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Scan subnets for port 9100 printers and browse mDNS (_pdl-datastream._tcp)." }, "subnets": { "type": "array", "items": { "type": "string", "pattern": "^[0-9]{1,3}(\\.[0-9]{1,3}){3}/[0-9]{1,2}$" } } } } } }, "default": { "type": "string", "pattern": "^prn_[A-Za-z0-9]{1,64}$", "description": "Printer used when a job names no printer. Overrides the OS default printer." }, "manual": { "type": "array", "maxItems": 100, "description": "Printers the agent cannot discover: network (host:port), serial and Bluetooth SPP (serial port name).", "items": { "$ref": "#/components/schemas/config__ManualPrinter" } }, "virtual": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Show the JodaPrint Virtual printer, which saves jobs to files." } } }, "drawerPins": { "type": "object", "description": "Cash drawer kick pin per printer ID (2 or 5). Defaults to 2.", "propertyNames": { "pattern": "^prn_[A-Za-z0-9]{1,64}$" }, "additionalProperties": { "type": "integer", "enum": [ 2, 5 ] } }, "statusIntervalSeconds": { "type": "integer", "minimum": 5, "maximum": 300, "description": "How often idle printers are checked. Defaults to 15." } } }, "queue": { "type": "object", "properties": { "maxAttempts": { "type": "integer", "description": "Maximum print attempts per job.", "minimum": 1, "maximum": 20 }, "jobTtlHours": { "type": "integer", "description": "Queued jobs older than this fail with TIMEOUT.", "minimum": 1, "maximum": 720 }, "keepContentHours": { "type": "integer", "description": "Keep printed job content for reprints.", "minimum": 0, "maximum": 720 } } }, "update": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "stable", "beta" ] }, "autoUpdate": { "type": "boolean", "description": "Install updates automatically." }, "window": { "type": "string", "description": "Local time window for updates, HH:MM-HH:MM.", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]-([01][0-9]|2[0-3]):[0-5][0-9]$" } } }, "logs": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] }, "maxSizeMb": { "type": "integer", "description": "Size of one log file.", "minimum": 1, "maximum": 500 }, "maxFiles": { "type": "integer", "description": "Rotated files to keep.", "minimum": 1, "maximum": 50 } } }, "ui": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "en", "fr", "ht" ] }, "showTray": { "type": "boolean", "description": "Show the tray icon." } } }, "android": { "type": "object", "additionalProperties": false, "description": "Android agent settings (Prompt 7.2). Other agents ignore them.", "properties": { "shell": { "type": "object", "additionalProperties": false, "description": "WebView shell: opens a web app full screen and gives it window.JodaPrintBridge.", "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2048, "description": "Page the shell opens (https only). Managed configuration can set it too." }, "fullScreen": { "type": "boolean", "description": "Hide the status and navigation bars." }, "disableBack": { "type": "boolean", "description": "The back button does not leave the web app (kiosk)." }, "autoStart": { "type": "boolean", "description": "Open the shell when the device starts." } } } } }, "templates": { "type": "array", "maxItems": 500, "description": "The organization's templates (Prompt 8.1). The cloud sets them from its template table; profiles cannot.", "items": { "$ref": "#/components/schemas/template" } } } }, "config__ManualPrinter": { "title": "ManualPrinter", "type": "object", "additionalProperties": false, "required": [ "name", "connection", "address" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Display name." }, "connection": { "type": "string", "enum": [ "network", "serial", "bluetooth" ] }, "address": { "type": "string", "minLength": 1, "maxLength": 256, "description": "host:port (port defaults to 9100) for network; serial port such as COM3 or /dev/ttyUSB0 for serial and bluetooth." }, "kind": { "type": "string", "enum": [ "thermal", "label", "document" ], "description": "Defaults to thermal." }, "paper": { "$ref": "#/components/schemas/paper" }, "serial": { "$ref": "#/components/schemas/config__SerialSettings" } } }, "config__SerialSettings": { "title": "SerialSettings", "type": "object", "additionalProperties": false, "properties": { "baudRate": { "type": "integer", "enum": [ 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400 ], "description": "Defaults to 9600." }, "dataBits": { "type": "integer", "enum": [ 7, 8 ] }, "parity": { "type": "string", "enum": [ "none", "odd", "even" ] }, "stopBits": { "type": "integer", "enum": [ 1, 2 ] } } }, "envelope": { "title": "Envelope", "description": "Any message on the local WebSocket.", "oneOf": [ { "$ref": "#/components/schemas/request" }, { "$ref": "#/components/schemas/response" }, { "$ref": "#/components/schemas/event" } ] }, "error-code": { "title": "ErrorCode", "description": "Error codes the agent and cloud send (A9, plus NOT_FOUND, FORBIDDEN, CONFLICT and VALIDATION_FAILED for the cloud REST API, ADR 0016). SDK-only codes are listed in x-sdk-only and never appear on the wire.", "type": "string", "enum": [ "UNAUTHORIZED", "SIGNATURE_INVALID", "SIGNATURE_EXPIRED", "NONCE_REUSED", "ORIGIN_NOT_ALLOWED", "SITE_BLOCKED_BY_USER", "NOT_ACTIVATED", "LICENSE_LIMIT", "RATE_LIMITED", "INVALID_JOB", "UNSUPPORTED_FORMAT", "PRINTER_NOT_FOUND", "PRINTER_OFFLINE", "PAPER_OUT", "COVER_OPEN", "PRINTER_ERROR", "JOB_NOT_FOUND", "JOB_ALREADY_FINISHED", "TIMEOUT", "UPDATE_REQUIRED", "INTERNAL", "NOT_FOUND", "FORBIDDEN", "CONFLICT", "VALIDATION_FAILED" ], "x-retryable": [ "PRINTER_OFFLINE", "PAPER_OUT", "COVER_OPEN", "TIMEOUT" ], "x-sdk-only": [ "AGENT_NOT_FOUND", "AGENT_CERT_UNTRUSTED" ] }, "error": { "title": "ErrorObject", "description": "An error returned in a response (A9).", "type": "object", "additionalProperties": false, "properties": { "code": { "$ref": "#/components/schemas/error-code" }, "message": { "type": "string", "description": "Human-readable message in English.", "minLength": 1, "maxLength": 1000 }, "retryable": { "type": "boolean", "description": "True when retrying the same request may succeed." }, "details": { "type": "object", "description": "Extra machine-readable context.", "additionalProperties": true } }, "required": [ "code", "message", "retryable" ] }, "event": { "title": "Event", "description": "Agent to client event (A6). Events have no id.", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "type": { "const": "event" }, "event": { "type": "string", "description": "Method name, for example printers.list.", "pattern": "^[a-z]+(\\.[a-z]+)*$" }, "data": { "description": "Event payload." } }, "required": [ "v", "type", "event", "data" ] }, "job-options": { "title": "JobOptions", "description": "Print options (A7). Printers ignore options they do not support.", "type": "object", "additionalProperties": false, "properties": { "copies": { "type": "integer", "description": "Number of copies.", "minimum": 1, "maximum": 100 }, "priority": { "type": "string", "enum": [ "normal", "high" ] }, "cut": { "type": "string", "enum": [ "full", "partial", "none" ] }, "openDrawer": { "type": "boolean", "description": "Open the cash drawer after printing." }, "paper": { "$ref": "#/components/schemas/paper" }, "codepage": { "$ref": "#/components/schemas/codepage" }, "orientation": { "type": "string", "enum": [ "portrait", "landscape" ] }, "duplex": { "type": "string", "enum": [ "none", "long", "short" ] }, "color": { "type": "boolean", "description": "Print in color when supported." }, "pageRange": { "type": "string", "description": "Pages to print, for example 1-3,5.", "pattern": "^[1-9][0-9]*(-[1-9][0-9]*)?(,[1-9][0-9]*(-[1-9][0-9]*)?)*$" }, "tray": { "type": "string", "description": "Paper tray name, or auto.", "minLength": 1, "maxLength": 64 }, "scale": { "type": "string", "enum": [ "fit", "actual" ] } } }, "job-request": { "title": "JobRequest", "description": "A print job submitted by a client (A7). With encoding json, data is a receipt document. With encoding url, data is an https URL the agent downloads. With templateId (Prompt 8.1), data holds the template's variables and the template sets the type and content.", "type": "object", "additionalProperties": false, "properties": { "idempotencyKey": { "type": "string", "description": "Same key within 24 h returns the first job and prints nothing.", "minLength": 1, "maxLength": 255 }, "printer": { "$ref": "#/components/schemas/printer-ref" }, "templateId": { "type": "string", "pattern": "^tpl_[A-Za-z0-9]{1,64}$", "description": "Print a stored template (ZPL, EPL or receipt) filled with data. The job then has no type or encoding." }, "type": { "$ref": "#/components/schemas/job-type" }, "encoding": { "type": "string", "enum": [ "json", "base64", "utf8", "url" ] }, "data": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/receipt-document" }, { "type": "object", "description": "Template variables (with templateId)." } ], "description": "Job content, or template variables with templateId." }, "options": { "$ref": "#/components/schemas/job-options" }, "metadata": { "type": "object", "description": "Free key/value pairs stored with the job and searchable.", "maxProperties": 50, "propertyNames": { "pattern": "^[A-Za-z0-9_.-]{1,64}$" }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "data" ], "allOf": [ { "if": { "properties": { "templateId": { "type": "string" } }, "required": [ "templateId" ] }, "then": { "properties": { "data": { "type": "object" } }, "not": { "anyOf": [ { "properties": { "type": { "type": "string" } }, "required": [ "type" ] }, { "properties": { "encoding": { "type": "string" } }, "required": [ "encoding" ] } ] } }, "else": { "properties": { "type": { "type": "string" }, "encoding": { "type": "string" } }, "required": [ "type", "encoding" ] } }, { "if": { "properties": { "encoding": { "const": "json" } }, "required": [ "encoding" ] }, "then": { "properties": { "type": { "const": "receipt" }, "data": { "$ref": "#/components/schemas/receipt-document" } } }, "else": { "if": { "properties": { "encoding": { "type": "string" } }, "required": [ "encoding" ] }, "then": { "properties": { "data": { "type": "string" } } } } }, { "if": { "properties": { "encoding": { "const": "url" } }, "required": [ "encoding" ] }, "then": { "properties": { "data": { "type": "string", "format": "uri", "pattern": "^https://" } } } } ] }, "job-state": { "title": "JobState", "type": "string", "enum": [ "queued", "sending", "printed", "failed", "cancelled" ] }, "job-type": { "title": "JobType", "type": "string", "enum": [ "receipt", "escpos", "raw", "zpl", "epl", "pdf", "image", "text", "html" ] }, "job": { "title": "Job", "description": "A job as stored by the agent or cloud (A7).", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Job ID.", "pattern": "^job_[A-Za-z0-9]{1,64}$" }, "idempotencyKey": { "type": "string", "description": "Idempotency key from the request.", "minLength": 1, "maxLength": 255 }, "printerId": { "type": "string", "pattern": "^prn_[A-Za-z0-9]{1,64}$" }, "deviceId": { "type": "string", "pattern": "^dev_[A-Za-z0-9]{1,64}$" }, "source": { "type": "string", "enum": [ "local", "cloud" ] }, "type": { "$ref": "#/components/schemas/job-type" }, "state": { "$ref": "#/components/schemas/job-state" }, "attempt": { "type": "integer", "description": "Print attempts made so far.", "minimum": 0 }, "errorCode": { "$ref": "#/components/schemas/error-code" }, "errorMessage": { "type": "string", "description": "Last error message.", "maxLength": 1000 }, "metadata": { "type": "object", "description": "Free key/value pairs stored with the job and searchable.", "maxProperties": 50, "propertyNames": { "pattern": "^[A-Za-z0-9_.-]{1,64}$" }, "additionalProperties": { "type": "string", "maxLength": 500 } }, "createdAt": { "type": "string", "format": "date-time", "description": "When the job was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the job last changed state." }, "printedAt": { "type": "string", "format": "date-time", "description": "When the job printed." } }, "required": [ "id", "printerId", "source", "type", "state", "attempt", "createdAt", "updatedAt" ] }, "license-token-claims": { "title": "LicenseTokenClaims", "description": "Claims of the device license JWT, signed with EdDSA (A15).", "type": "object", "additionalProperties": false, "properties": { "iss": { "type": "string", "description": "Issuer, the cloud URL.", "minLength": 1 }, "orgId": { "type": "string", "pattern": "^org_[A-Za-z0-9]{1,64}$" }, "deviceId": { "type": "string", "pattern": "^dev_[A-Za-z0-9]{1,64}$" }, "plan": { "type": "string", "description": "Plan code.", "pattern": "^[a-z0-9_-]{1,32}$" }, "limits": { "type": "object", "additionalProperties": false, "properties": { "maxDevices": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Null means unlimited." }, "maxJobsPerMonth": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Null means unlimited." }, "jobsPerSecond": { "type": "integer", "description": "Device-side rate limit.", "minimum": 1 } }, "required": [ "maxDevices", "maxJobsPerMonth", "jobsPerSecond" ], "title": "LicenseLimits" }, "features": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-zA-Z0-9.]{0,63}$" }, "uniqueItems": true }, "iat": { "type": "integer", "description": "Issued at, Unix seconds.", "minimum": 0 }, "exp": { "type": "integer", "description": "Expires at, Unix seconds.", "minimum": 0 } }, "required": [ "orgId", "deviceId", "plan", "limits", "features", "iat", "exp" ] }, "local-agent-info-params": { "title": "AgentInfoParams", "description": "Params for agent.info.", "type": "object", "additionalProperties": false, "properties": {} }, "local-agent-info-result": { "title": "AgentInfoResult", "description": "Result of agent.info.", "$ref": "#/components/schemas/agent-info" }, "local-drawer-open-params": { "title": "DrawerOpenParams", "description": "Params for drawer.open. Omit printer to use the default printer.", "type": "object", "additionalProperties": false, "properties": { "printer": { "$ref": "#/components/schemas/printer-ref" }, "pin": { "type": "integer", "enum": [ 2, 5 ], "description": "Drawer kick pin. Defaults to 2." } } }, "local-drawer-open-result": { "title": "DrawerOpenResult", "description": "Result of drawer.open.", "type": "object", "additionalProperties": false, "properties": { "ok": { "const": true } }, "required": [ "ok" ] }, "local-event-job-updated": { "title": "JobUpdatedEvent", "description": "job.updated event.", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "type": { "const": "event" }, "event": { "const": "job.updated" }, "data": { "$ref": "#/components/schemas/job" } }, "required": [ "v", "type", "event", "data" ] }, "local-event-printer-status": { "title": "PrinterStatusEvent", "description": "printer.status event.", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "type": { "const": "event" }, "event": { "const": "printer.status" }, "data": { "$ref": "#/components/schemas/printer-status" } }, "required": [ "v", "type", "event", "data" ] }, "local-event": { "title": "LocalEvent", "description": "Any local event.", "oneOf": [ { "$ref": "#/components/schemas/local-event-printer-status" }, { "$ref": "#/components/schemas/local-event-job-updated" } ] }, "local-jobs-cancel-params": { "title": "JobsCancelParams", "description": "Params for jobs.cancel.", "type": "object", "additionalProperties": false, "properties": { "jobId": { "type": "string", "pattern": "^job_[A-Za-z0-9]{1,64}$" } }, "required": [ "jobId" ] }, "local-jobs-cancel-result": { "title": "JobsCancelResult", "description": "Result of jobs.cancel.", "type": "object", "additionalProperties": false, "properties": { "jobId": { "type": "string", "pattern": "^job_[A-Za-z0-9]{1,64}$" }, "state": { "$ref": "#/components/schemas/job-state" } }, "required": [ "jobId", "state" ] }, "local-jobs-get-params": { "title": "JobsGetParams", "description": "Params for jobs.get.", "type": "object", "additionalProperties": false, "properties": { "jobId": { "type": "string", "pattern": "^job_[A-Za-z0-9]{1,64}$" } }, "required": [ "jobId" ] }, "local-jobs-get-result": { "title": "JobsGetResult", "description": "Result of jobs.get.", "$ref": "#/components/schemas/job" }, "local-method": { "title": "LocalMethod", "type": "string", "enum": [ "agent.info", "printers.list", "printers.status", "print", "jobs.get", "jobs.cancel", "drawer.open", "subscribe" ] }, "local-print-params": { "title": "PrintParams", "description": "Params for print: a job request.", "$ref": "#/components/schemas/job-request" }, "local-print-result": { "title": "PrintResult", "description": "Result of print.", "type": "object", "additionalProperties": false, "properties": { "jobId": { "type": "string", "pattern": "^job_[A-Za-z0-9]{1,64}$" }, "state": { "$ref": "#/components/schemas/job-state" } }, "required": [ "jobId", "state" ] }, "local-printers-list-params": { "title": "PrintersListParams", "description": "Params for printers.list.", "type": "object", "additionalProperties": false, "properties": {} }, "local-printers-list-result": { "title": "PrintersListResult", "description": "Result of printers.list.", "type": "array", "items": { "$ref": "#/components/schemas/printer" } }, "local-printers-status-params": { "title": "PrintersStatusParams", "description": "Params for printers.status.", "type": "object", "additionalProperties": false, "properties": { "printerId": { "type": "string", "pattern": "^prn_[A-Za-z0-9]{1,64}$" } }, "required": [ "printerId" ] }, "local-printers-status-result": { "title": "PrintersStatusResult", "description": "Result of printers.status.", "$ref": "#/components/schemas/printer-status" }, "local-subscribe-params": { "title": "SubscribeParams", "description": "Params for subscribe. Omit events to subscribe to all.", "type": "object", "additionalProperties": false, "properties": { "events": { "type": "array", "items": { "type": "string", "enum": [ "printer.status", "job.updated" ] }, "minItems": 1, "uniqueItems": true } } }, "local-subscribe-result": { "title": "SubscribeResult", "description": "Result of subscribe.", "type": "object", "additionalProperties": false, "properties": { "events": { "type": "array", "items": { "type": "string", "enum": [ "printer.status", "job.updated" ] }, "uniqueItems": true } }, "required": [ "events" ] }, "paper": { "title": "Paper", "type": "string", "enum": [ "58mm", "80mm", "label-4x6", "label-2x1", "a4", "letter" ] }, "printer-ref": { "title": "PrinterRef", "description": "Selects a printer by id, alias or name (A7). Omit the whole reference to use the default printer.", "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^prn_[A-Za-z0-9]{1,64}$" } }, "required": [ "id" ], "title": "PrinterRefById" }, { "type": "object", "additionalProperties": false, "properties": { "alias": { "type": "string", "description": "Printer alias from config.", "pattern": "^[A-Za-z0-9_.-]{1,64}$" } }, "required": [ "alias" ], "title": "PrinterRefByAlias" }, { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "OS or driver printer name.", "minLength": 1, "maxLength": 256 } }, "required": [ "name" ], "title": "PrinterRefByName" } ] }, "printer-status": { "title": "PrinterStatus", "description": "Current state of one printer.", "type": "object", "additionalProperties": false, "properties": { "printerId": { "type": "string", "pattern": "^prn_[A-Za-z0-9]{1,64}$" }, "state": { "type": "string", "enum": [ "online", "offline", "error", "unknown" ] }, "paperOut": { "type": "boolean", "description": "Paper end sensor." }, "paperNearEnd": { "type": "boolean", "description": "Paper near end sensor." }, "coverOpen": { "type": "boolean", "description": "Cover open." }, "cutterError": { "type": "boolean", "description": "Auto-cutter error." }, "unrecoverableError": { "type": "boolean", "description": "Unrecoverable printer error." }, "errorCode": { "$ref": "#/components/schemas/error-code" }, "message": { "type": "string", "description": "Details for humans.", "maxLength": 1000 }, "updatedAt": { "type": "string", "format": "date-time", "description": "When this status was observed." } }, "required": [ "printerId", "state", "updatedAt" ] }, "printer": { "title": "Printer", "description": "A printer the agent can reach (A7). IDs are stable hashes of connection + address or OS name.", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Stable printer ID.", "pattern": "^prn_[A-Za-z0-9]{1,64}$" }, "alias": { "type": "string", "description": "Alias from config.", "pattern": "^[A-Za-z0-9_.-]{1,64}$" }, "name": { "type": "string", "description": "Display name.", "minLength": 1, "maxLength": 256 }, "connection": { "type": "string", "enum": [ "usb", "network", "serial", "bluetooth", "spooler", "vendor", "virtual" ] }, "address": { "type": "string", "description": "Connection address: host:port, serial port, OS queue name or vendor ID.", "maxLength": 256 }, "kind": { "type": "string", "enum": [ "thermal", "label", "document" ] }, "paper": { "$ref": "#/components/schemas/paper" }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "cut", "drawer", "status.realtime", "color", "duplex", "copies", "beep" ] }, "uniqueItems": true }, "isDefault": { "type": "boolean", "description": "True for the default printer." } }, "required": [ "id", "name", "connection", "kind", "capabilities", "isDefault" ] }, "receipt-document": { "title": "ReceiptDocument", "description": "A receipt described as blocks (A8). The agent renders it to ESC/POS for the target printer.", "type": "object", "additionalProperties": false, "properties": { "width": { "type": "string", "enum": [ "58mm", "80mm" ] }, "codepage": { "$ref": "#/components/schemas/codepage" }, "blocks": { "type": "array", "minItems": 1, "maxItems": 2000, "items": { "$ref": "#/components/schemas/receipt-document__ReceiptBlock" } } }, "required": [ "blocks" ] }, "receipt-document__ReceiptBlock": { "title": "ReceiptBlock", "oneOf": [ { "$ref": "#/components/schemas/receipt-document__TextBlock" }, { "$ref": "#/components/schemas/receipt-document__LineBlock" }, { "$ref": "#/components/schemas/receipt-document__PairBlock" }, { "$ref": "#/components/schemas/receipt-document__TableBlock" }, { "$ref": "#/components/schemas/receipt-document__QrBlock" }, { "$ref": "#/components/schemas/receipt-document__BarcodeBlock" }, { "$ref": "#/components/schemas/receipt-document__ImageBlock" }, { "$ref": "#/components/schemas/receipt-document__FeedBlock" }, { "$ref": "#/components/schemas/receipt-document__CutBlock" }, { "$ref": "#/components/schemas/receipt-document__DrawerBlock" }, { "$ref": "#/components/schemas/receipt-document__RawBlock" } ] }, "receipt-document__TextBlock": { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "text" }, "value": { "type": "string", "maxLength": 10000 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "bold": { "type": "boolean" }, "underline": { "type": "boolean" }, "size": { "type": "integer", "description": "Character magnification.", "minimum": 1, "maximum": 8 }, "invert": { "type": "boolean" }, "font": { "type": "string", "enum": [ "a", "b" ] } }, "required": [ "type", "value" ], "title": "TextBlock" }, "receipt-document__LineBlock": { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "line" }, "style": { "type": "string", "enum": [ "solid", "dashed", "double" ] } }, "required": [ "type" ], "title": "LineBlock" }, "receipt-document__PairBlock": { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "pair" }, "left": { "type": "string", "maxLength": 1000 }, "right": { "type": "string", "maxLength": 1000 }, "bold": { "type": "boolean" } }, "required": [ "type", "left", "right" ], "title": "PairBlock" }, "receipt-document__TableBlock": { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "table" }, "columns": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "object", "additionalProperties": false, "properties": { "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 1, "description": "Fraction of the line width." }, "align": { "type": "string", "enum": [ "left", "center", "right" ] } }, "required": [ "width" ], "title": "TableColumn" } }, "rows": { "type": "array", "maxItems": 1000, "items": { "type": "array", "items": { "type": "string", "maxLength": 1000 } } }, "bold": { "type": "boolean" } }, "required": [ "type", "columns", "rows" ], "title": "TableBlock" }, "receipt-document__QrBlock": { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "qr" }, "value": { "type": "string", "minLength": 1, "maxLength": 2000 }, "size": { "type": "integer", "description": "Module size in dots.", "minimum": 1, "maximum": 16 }, "errorLevel": { "type": "string", "enum": [ "L", "M", "Q", "H" ] }, "align": { "type": "string", "enum": [ "left", "center", "right" ] } }, "required": [ "type", "value" ], "title": "QrBlock" }, "receipt-document__BarcodeBlock": { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "barcode" }, "format": { "type": "string", "enum": [ "CODE128", "EAN13", "EAN8", "UPC-A", "CODE39", "ITF" ] }, "value": { "type": "string", "minLength": 1, "maxLength": 255 }, "height": { "type": "integer", "description": "Bar height in dots.", "minimum": 1, "maximum": 255 }, "width": { "type": "integer", "description": "Module width in dots.", "minimum": 1, "maximum": 6 }, "hri": { "type": "string", "enum": [ "none", "above", "below", "both" ] }, "align": { "type": "string", "enum": [ "left", "center", "right" ] } }, "required": [ "type", "format", "value" ], "title": "BarcodeBlock" }, "receipt-document__ImageBlock": { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "image" }, "src": { "type": "string", "minLength": 1, "description": "https URL or base64 PNG/JPEG." }, "width": { "type": "integer", "description": "Width in dots.", "minimum": 8, "maximum": 2048 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "dithering": { "type": "string", "enum": [ "floyd-steinberg", "threshold" ] } }, "required": [ "type", "src" ], "title": "ImageBlock" }, "receipt-document__FeedBlock": { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "feed" }, "lines": { "type": "integer", "description": "Lines to feed.", "minimum": 1, "maximum": 255 } }, "required": [ "type" ], "title": "FeedBlock" }, "receipt-document__CutBlock": { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "cut" }, "mode": { "type": "string", "enum": [ "full", "partial" ] } }, "required": [ "type" ], "title": "CutBlock" }, "receipt-document__DrawerBlock": { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "drawer" }, "pin": { "type": "integer", "enum": [ 2, 5 ] } }, "required": [ "type" ], "title": "DrawerBlock" }, "receipt-document__RawBlock": { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "raw" }, "data": { "type": "string", "pattern": "^[A-Za-z0-9+/]*={0,2}$", "description": "Printer bytes, base64." } }, "required": [ "type", "data" ], "title": "RawBlock" }, "release-manifest": { "title": "ReleaseManifest", "description": "An agent release offered to a device (A14).", "type": "object", "additionalProperties": false, "properties": { "version": { "type": "string", "description": "Release version.", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(-[0-9A-Za-z.-]+)?(\\+[0-9A-Za-z.-]+)?$" }, "platform": { "type": "string", "enum": [ "windows", "darwin", "linux", "android" ] }, "arch": { "type": "string", "enum": [ "amd64", "arm64", "universal" ] }, "channel": { "type": "string", "enum": [ "stable", "beta" ] }, "url": { "type": "string", "description": "Download URL.", "format": "uri", "pattern": "^https://" }, "sha256": { "type": "string", "description": "SHA-256 of the binary, lowercase hex.", "pattern": "^[a-f0-9]{64}$" }, "signature": { "type": "string", "description": "Ed25519 signature by the release key, base64url.", "pattern": "^[A-Za-z0-9_-]{86}$" }, "minSupportedVersion": { "type": "string", "description": "Agents below this version must update now.", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(-[0-9A-Za-z.-]+)?(\\+[0-9A-Za-z.-]+)?$" }, "notes": { "type": "string", "description": "Release notes.", "maxLength": 20000 }, "publishedAt": { "type": "string", "format": "date-time", "description": "Publication time." } }, "required": [ "version", "platform", "arch", "channel", "url", "sha256", "signature", "minSupportedVersion", "publishedAt" ] }, "request": { "title": "Request", "description": "Client to agent request (A6).", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "id": { "type": "string", "description": "Request ID chosen by the client. The response carries the same ID.", "minLength": 1, "maxLength": 128 }, "type": { "const": "request" }, "method": { "type": "string", "description": "Method name, for example printers.list.", "pattern": "^[a-z]+(\\.[a-z]+)*$" }, "params": { "type": "object", "description": "Method parameters. Defaults to {}.", "additionalProperties": true }, "auth": { "$ref": "#/components/schemas/auth" } }, "required": [ "v", "id", "type", "method" ] }, "response": { "title": "Response", "description": "Agent to client response (A6). ok=true carries result; ok=false carries error.", "type": "object", "additionalProperties": false, "properties": { "v": { "const": 1 }, "id": { "type": "string", "description": "Request ID chosen by the client. The response carries the same ID.", "minLength": 1, "maxLength": 128 }, "type": { "const": "response" }, "ok": { "type": "boolean", "description": "True on success." }, "result": { "description": "Method result when ok is true." }, "error": { "$ref": "#/components/schemas/error" } }, "required": [ "v", "id", "type", "ok" ], "if": { "properties": { "ok": { "const": true } } }, "then": { "properties": { "result": true, "error": false }, "required": [ "result" ] }, "else": { "properties": { "error": true, "result": false }, "required": [ "error" ] } }, "template": { "title": "Template", "description": "A label or receipt template (Prompt 8.1, ADR 0040) as agents receive it in their config. content uses {{variables}}; see protocol/test-vectors/templates.json.", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^tpl_[A-Za-z0-9]{1,64}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "enum": [ "zpl", "epl", "receipt", "html" ] }, "content": { "type": "string", "minLength": 1, "maxLength": 65536, "description": "Template text. Receipt templates render to an A8 receipt document (JSON)." }, "paper": { "$ref": "#/components/schemas/paper", "description": "Paper the template is made for; used as the job's paper when the job sets none." } }, "required": [ "id", "name", "type", "content" ] } } } }