{ "components": { "parameters": {}, "schemas": { "Computer": { "example": { "agentVersion": "1.4.0", "arch": "amd64", "createdAt": "2026-10-01T08:30:00.000Z", "hostname": "PACK-01", "id": "0192f1a0-7c00-7000-8000-0000000000cc", "lastSeenAt": "2026-10-14T10:00:00.000Z", "mode": "live", "name": "Warehouse packing desk", "os": "windows", "osVersion": "10.0.26100", "state": "online" }, "properties": { "agentVersion": { "type": "string" }, "arch": { "type": "string" }, "createdAt": { "type": "string" }, "hostname": { "type": "string" }, "id": { "type": "string" }, "lastSeenAt": { "type": [ "string", "null" ] }, "mode": { "enum": [ "live", "test" ], "type": "string" }, "name": { "type": "string" }, "os": { "type": "string" }, "osVersion": { "type": "string" }, "state": { "enum": [ "online", "offline", "disabled" ], "type": "string" } }, "required": [ "id", "mode", "name", "hostname", "os", "osVersion", "arch", "agentVersion", "state", "lastSeenAt", "createdAt" ], "type": "object" }, "Error": { "description": "Every error response uses this envelope; code is stable, message is for humans.", "properties": { "error": { "properties": { "code": { "example": "not_found", "type": "string" }, "message": { "example": "Printer not found", "type": "string" }, "request_id": { "example": "4f9c2a7e-1b3d-4c5e-8f6a-0b1c2d3e4f5a", "type": "string" }, "upgrade_url": { "description": "Billing page to upgrade from; present on quota_exceeded", "example": "https://app.inkrelay.app/billing?upgrade=1", "format": "uri", "type": "string" } }, "required": [ "code", "message", "request_id" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "Event": { "example": { "createdAt": "2026-10-14T10:00:00.000Z", "data": { "id": "0192f1a0-7c00-7000-8000-0000000000aa", "state": "done" }, "id": "0192f1a0-7c00-7000-8000-000000000001", "mode": "test", "resourceId": "0192f1a0-7c00-7000-8000-0000000000aa", "resourceType": "print_job", "type": "printjob.done" }, "properties": { "createdAt": { "format": "date-time", "type": "string" }, "data": { "additionalProperties": {}, "description": "The same object webhooks deliver as data", "type": "object" }, "id": { "description": "Also the webhook-id of its deliveries", "format": "uuid", "type": "string" }, "mode": { "enum": [ "live", "test" ], "type": "string" }, "resourceId": { "format": "uuid", "type": "string" }, "resourceType": { "example": "print_job", "type": "string" }, "type": { "enum": [ "printjob.queued", "printjob.sent", "printjob.received", "printjob.printing", "printjob.done", "printjob.error", "printjob.cancelled", "printjob.expired", "computer.online", "computer.offline", "printer.added", "printer.removed", "printer.online", "printer.offline", "printer.updated" ], "type": "string" } }, "required": [ "id", "type", "mode", "resourceType", "resourceId", "data", "createdAt" ], "type": "object" }, "PrintJob": { "example": { "computerId": "0192f1a0-7c00-7000-8000-0000000000cc", "contentType": "pdf_uri", "createdAt": "2026-10-14T10:00:00.000Z", "expireAfter": 86400, "expiresAt": "2026-10-15T10:00:00.000Z", "fileSha256": "9f2c4a1e0b7d3f5a8c6e2d4b1a9f7e5c3b1d9f7a5e3c1b9d7f5a3e1c9b7d5f3a", "fileSize": 48213, "finishedAt": "2026-10-14T10:00:09.000Z", "id": "0192f1a0-7c00-7000-8000-0000000000aa", "mode": "live", "options": { "copies": 1, "paper": "A4" }, "printerId": "0192f1a0-7c00-7000-8000-0000000000bb", "printingAt": "2026-10-14T10:00:03.000Z", "qty": 1, "receivedAt": "2026-10-14T10:00:02.000Z", "sentAt": "2026-10-14T10:00:01.000Z", "source": "api", "state": "done", "stateMessage": null, "title": "Invoice 1042" }, "properties": { "computerId": { "type": "string" }, "contentType": { "enum": [ "pdf_uri", "pdf_base64", "raw_uri", "raw_base64" ], "type": "string" }, "createdAt": { "type": "string" }, "expireAfter": { "type": "number" }, "expiresAt": { "type": "string" }, "fileSha256": { "type": [ "string", "null" ] }, "fileSize": { "type": [ "number", "null" ] }, "finishedAt": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "mode": { "enum": [ "live", "test" ], "type": "string" }, "options": { "additionalProperties": false, "properties": { "bin": { "maxLength": 100, "minLength": 1, "type": "string" }, "collate": { "type": "boolean" }, "color": { "type": "boolean" }, "copies": { "maximum": 999, "minimum": 1, "type": "integer" }, "dpi": { "pattern": "^\\d+x\\d+$", "type": "string" }, "duplex": { "enum": [ "one-sided", "long-edge", "short-edge" ], "type": "string" }, "fit_to_page": { "type": "boolean" }, "media": { "maxLength": 100, "minLength": 1, "type": "string" }, "nup": { "maximum": 16, "minimum": 1, "type": "integer" }, "pages": { "pattern": "^\\d+(-\\d+)?(,\\d+(-\\d+)?)*$", "type": "string" }, "paper": { "maxLength": 100, "minLength": 1, "type": "string" }, "rotate": { "anyOf": [ { "enum": [ 0 ], "type": "number" }, { "enum": [ 90 ], "type": "number" }, { "enum": [ 180 ], "type": "number" }, { "enum": [ 270 ], "type": "number" } ] } }, "type": "object" }, "printerId": { "type": "string" }, "printingAt": { "type": [ "string", "null" ] }, "qty": { "type": "number" }, "receivedAt": { "type": [ "string", "null" ] }, "sentAt": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "state": { "enum": [ "queued", "sent", "received", "printing", "done", "error", "cancelled", "expired" ], "type": "string" }, "stateMessage": { "type": [ "string", "null" ] }, "title": { "type": "string" } }, "required": [ "id", "mode", "printerId", "computerId", "title", "source", "contentType", "fileSize", "fileSha256", "options", "qty", "expireAfter", "state", "stateMessage", "createdAt", "sentAt", "receivedAt", "printingAt", "finishedAt", "expiresAt" ], "type": "object" }, "PrintJobCreate": { "description": "Send exactly one of two forms: contentType with content (a new document), or reprintOf alone (print the stored file of an earlier job again). Any other combination is 400 invalid_request.", "example": { "content": "https://example.com/invoice-1042.pdf", "contentType": "pdf_uri", "options": { "copies": 1, "paper": "A4" }, "printerId": "0192f1a0-7c00-7000-8000-0000000000bb", "title": "Invoice 1042" }, "properties": { "authentication": { "properties": { "credentials": { "properties": { "pass": { "maxLength": 255, "type": "string" }, "user": { "maxLength": 255, "type": "string" } }, "required": [ "user", "pass" ], "type": "object" }, "type": { "enum": [ "BasicAuth" ], "type": "string" } }, "required": [ "type", "credentials" ], "type": "object" }, "content": { "description": "Base64 document or https content URL. Required together with contentType; must be omitted with reprintOf.", "minLength": 1, "type": "string" }, "contentType": { "description": "How content is sent. Required together with content; must be omitted with reprintOf.", "enum": [ "pdf_uri", "pdf_base64", "raw_uri", "raw_base64" ], "type": "string" }, "expireAfter": { "default": 86400, "maximum": 604800, "minimum": 60, "type": "integer" }, "options": { "additionalProperties": false, "default": {}, "properties": { "bin": { "maxLength": 100, "minLength": 1, "type": "string" }, "collate": { "type": "boolean" }, "color": { "type": "boolean" }, "copies": { "maximum": 999, "minimum": 1, "type": "integer" }, "dpi": { "pattern": "^\\d+x\\d+$", "type": "string" }, "duplex": { "enum": [ "one-sided", "long-edge", "short-edge" ], "type": "string" }, "fit_to_page": { "type": "boolean" }, "media": { "maxLength": 100, "minLength": 1, "type": "string" }, "nup": { "maximum": 16, "minimum": 1, "type": "integer" }, "pages": { "pattern": "^\\d+(-\\d+)?(,\\d+(-\\d+)?)*$", "type": "string" }, "paper": { "maxLength": 100, "minLength": 1, "type": "string" }, "rotate": { "anyOf": [ { "enum": [ 0 ], "type": "number" }, { "enum": [ 90 ], "type": "number" }, { "enum": [ 180 ], "type": "number" }, { "enum": [ 270 ], "type": "number" } ] } }, "type": "object" }, "printerId": { "description": "Printer to print on", "format": "uuid", "type": "string" }, "qty": { "default": 1, "maximum": 100, "minimum": 1, "type": "integer" }, "reprintOf": { "description": "Id of an earlier job of this organization and mode whose stored file is printed again. Send it instead of contentType and content, never with them. Its contentType is copied; 410 file_expired once the file is gone.", "format": "uuid", "type": "string" }, "source": { "default": "api", "maxLength": 255, "type": "string" }, "title": { "description": "Shown in the dashboard and logs", "maxLength": 255, "minLength": 1, "type": "string" } }, "required": [ "printerId", "title" ], "type": "object" }, "PrintJobEvent": { "example": { "actor": "agent", "createdAt": "2026-10-14T10:00:09.000Z", "id": "0192f1a0-7c00-7000-8000-0000000000ab", "message": null, "state": "done" }, "properties": { "actor": { "enum": [ "api", "agent", "system", "user" ], "type": "string" }, "createdAt": { "type": "string" }, "id": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "state": { "enum": [ "queued", "sent", "received", "printing", "done", "error", "cancelled", "expired" ], "type": "string" } }, "required": [ "id", "state", "message", "actor", "createdAt" ], "type": "object" }, "Printer": { "example": { "capabilities": { "bins": [ "Auto", "Tray 1" ], "collate": true, "color": false, "copies": 99, "dpis": [ "600x600" ], "duplex": true, "extent": null, "medias": [], "nup": [ 1, 2, 4 ], "papers": { "A4": [ 2100, 2970 ], "Letter": [ 2159, 2794 ] }, "printrate": { "rate": 38, "unit": "ppm" }, "supports_custom_paper_size": false }, "computerId": "0192f1a0-7c00-7000-8000-0000000000cc", "createdAt": "2026-10-01T08:30:00.000Z", "customPapers": [], "defaultOptions": { "duplex": "long-edge", "paper": "A4" }, "description": "HP LaserJet Pro M404-M405 PCL 6", "displayName": "Front office laser", "enabled": true, "id": "0192f1a0-7c00-7000-8000-0000000000bb", "isDefault": true, "name": "Front office laser", "osName": "HP LaserJet Pro M404", "remarks": null, "state": "online", "stateDetail": "", "updatedAt": "2026-10-14T09:00:00.000Z" }, "properties": { "capabilities": { "properties": { "bins": { "items": { "type": "string" }, "type": "array" }, "collate": { "type": "boolean" }, "color": { "type": "boolean" }, "copies": { "minimum": 1, "type": "integer" }, "dpis": { "items": { "type": "string" }, "type": "array" }, "duplex": { "type": "boolean" }, "extent": { "description": "Custom paper size range in tenths of a millimetre", "items": { "items": { "maximum": 100000, "minimum": 1, "type": "integer" }, "maxItems": 2, "minItems": 2, "type": "array" }, "maxItems": 2, "minItems": 2, "prefixItems": [ { "description": "Minimum width and height", "items": { "maximum": 100000, "minimum": 1, "type": "integer" }, "maxItems": 2, "minItems": 2, "prefixItems": [ { "maximum": 100000, "minimum": 1, "type": "integer" }, { "maximum": 100000, "minimum": 1, "type": "integer" } ], "type": "array" }, { "description": "Maximum width and height", "items": { "maximum": 100000, "minimum": 1, "type": "integer" }, "maxItems": 2, "minItems": 2, "prefixItems": [ { "maximum": 100000, "minimum": 1, "type": "integer" }, { "maximum": 100000, "minimum": 1, "type": "integer" } ], "type": "array" } ], "type": [ "array", "null" ] }, "medias": { "items": { "type": "string" }, "type": "array" }, "nup": { "items": { "minimum": 1, "type": "integer" }, "type": "array" }, "papers": { "additionalProperties": { "description": "Width and height in tenths of a millimetre; null when the driver does not say", "items": { "maximum": 100000, "minimum": 1, "type": [ "integer", "null" ] }, "maxItems": 2, "minItems": 2, "prefixItems": [ { "maximum": 100000, "minimum": 1, "type": [ "integer", "null" ] }, { "maximum": 100000, "minimum": 1, "type": [ "integer", "null" ] } ], "type": "array" }, "description": "Paper names the printer supports", "type": "object" }, "printrate": { "properties": { "rate": { "type": "number" }, "unit": { "type": "string" } }, "required": [ "unit", "rate" ], "type": [ "object", "null" ] }, "supports_custom_paper_size": { "type": "boolean" } }, "required": [ "papers", "bins", "dpis", "duplex", "color", "collate", "copies", "extent", "medias", "nup", "printrate", "supports_custom_paper_size" ], "type": "object" }, "computerId": { "type": "string" }, "createdAt": { "type": "string" }, "customPapers": { "items": { "properties": { "height": { "maximum": 100000, "minimum": 1, "type": "integer" }, "name": { "maxLength": 100, "minLength": 1, "type": "string" }, "width": { "maximum": 100000, "minimum": 1, "type": "integer" } }, "required": [ "name", "width", "height" ], "type": "object" }, "type": "array" }, "defaultOptions": { "additionalProperties": false, "properties": { "bin": { "maxLength": 100, "minLength": 1, "type": "string" }, "collate": { "type": "boolean" }, "color": { "type": "boolean" }, "copies": { "maximum": 999, "minimum": 1, "type": "integer" }, "dpi": { "pattern": "^\\d+x\\d+$", "type": "string" }, "duplex": { "enum": [ "one-sided", "long-edge", "short-edge" ], "type": "string" }, "fit_to_page": { "type": "boolean" }, "media": { "maxLength": 100, "minLength": 1, "type": "string" }, "nup": { "maximum": 16, "minimum": 1, "type": "integer" }, "pages": { "pattern": "^\\d+(-\\d+)?(,\\d+(-\\d+)?)*$", "type": "string" }, "paper": { "maxLength": 100, "minLength": 1, "type": "string" }, "rotate": { "anyOf": [ { "enum": [ 0 ], "type": "number" }, { "enum": [ 90 ], "type": "number" }, { "enum": [ 180 ], "type": "number" }, { "enum": [ 270 ], "type": "number" } ] } }, "type": "object" }, "description": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "id": { "type": "string" }, "isDefault": { "type": "boolean" }, "name": { "type": "string" }, "osName": { "type": "string" }, "remarks": { "type": [ "string", "null" ] }, "state": { "enum": [ "online", "offline", "unknown" ], "type": "string" }, "stateDetail": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "computerId", "osName", "displayName", "name", "description", "enabled", "state", "stateDetail", "capabilities", "defaultOptions", "customPapers", "remarks", "isDefault", "createdAt", "updatedAt" ], "type": "object" }, "Usage": { "example": { "history": [], "period": { "end": "2026-11-01T00:00:00.000Z", "includedPrints": 5000, "overagePrints": 0, "start": "2026-10-01T00:00:00.000Z", "usedPrints": 1234 }, "plan": "essential" }, "properties": { "history": { "description": "Earlier periods, newest first (up to 12)", "items": { "properties": { "end": { "description": "First instant after the period (UTC), exclusive", "format": "date-time", "type": "string" }, "includedPrints": { "description": "Live prints the plan includes", "type": "integer" }, "overagePrints": { "description": "Live prints past the included allowance, billed as overage on paid plans (always 0 on Lite)", "type": "integer" }, "start": { "description": "First instant of the period (UTC)", "format": "date-time", "type": "string" }, "usedPrints": { "description": "Live print jobs created so far", "type": "integer" } }, "required": [ "start", "end", "includedPrints", "usedPrints" ], "type": "object" }, "type": "array" }, "period": { "properties": { "end": { "description": "First instant after the period (UTC), exclusive", "format": "date-time", "type": "string" }, "includedPrints": { "description": "Live prints the plan includes", "type": "integer" }, "overagePrints": { "description": "Live prints past the included allowance, billed as overage on paid plans (always 0 on Lite)", "type": "integer" }, "start": { "description": "First instant of the period (UTC)", "format": "date-time", "type": "string" }, "usedPrints": { "description": "Live print jobs created so far", "type": "integer" } }, "required": [ "start", "end", "includedPrints", "usedPrints" ], "type": "object" }, "plan": { "description": "Current plan (lite, essential, standard or premium), as in GET /v1/whoami", "example": "essential", "type": "string" } }, "required": [ "plan", "period", "history" ], "type": "object" }, "WebhookDelivery": { "properties": { "attempt": { "description": "Sends made so far, 0 before the first", "type": "integer" }, "createdAt": { "format": "date-time", "type": "string" }, "deliveredAt": { "format": "date-time", "type": [ "string", "null" ] }, "endpointId": { "format": "uuid", "type": "string" }, "eventId": { "description": "Also sent as the webhook-id header", "format": "uuid", "type": "string" }, "eventType": { "description": "One of the subscribable event types, or ping for a test delivery from POST /v1/webhooks/{id}/ping", "example": "printjob.done", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "nextAttemptAt": { "format": "date-time", "type": [ "string", "null" ] }, "payload": { "additionalProperties": {}, "description": "The exact envelope sent as the request body", "type": "object" }, "responseBodyExcerpt": { "description": "First 2,048 characters of the last response body, or the network error", "type": [ "string", "null" ] }, "responseCode": { "description": "HTTP status of the last attempt; null when it got no response", "type": [ "integer", "null" ] }, "status": { "enum": [ "pending", "retrying", "succeeded", "failed" ], "type": "string" } }, "required": [ "id", "endpointId", "eventId", "eventType", "payload", "attempt", "status", "responseCode", "responseBodyExcerpt", "nextAttemptAt", "deliveredAt", "createdAt" ], "type": "object" }, "WebhookEndpoint": { "properties": { "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": [ "string", "null" ] }, "disabledReason": { "description": "Why the endpoint is disabled: by a user, or automatically after 5 days of failures", "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "events": { "items": { "enum": [ "printjob.queued", "printjob.sent", "printjob.received", "printjob.printing", "printjob.done", "printjob.error", "printjob.cancelled", "printjob.expired", "computer.online", "computer.offline", "printer.added", "printer.removed", "printer.online", "printer.offline", "printer.updated" ], "example": "printjob.done", "type": "string" }, "type": "array" }, "failingSince": { "description": "Start of the current run of failed deliveries; null while healthy", "format": "date-time", "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "mode": { "enum": [ "live", "test" ], "type": "string" }, "previousSecretExpiresAt": { "description": "Until this time deliveries are also signed with the secret replaced by the last rotation; null when there is none", "format": "date-time", "type": [ "string", "null" ] }, "url": { "example": "https://example.com/inkrelay/webhooks", "type": "string" } }, "required": [ "id", "url", "description", "events", "mode", "enabled", "disabledReason", "failingSince", "previousSecretExpiresAt", "createdAt" ], "type": "object" }, "WebhookEndpointCreate": { "properties": { "description": { "example": "ERP print status", "maxLength": 256, "type": "string" }, "events": { "example": [ "printjob.done", "printjob.error" ], "items": { "enum": [ "printjob.queued", "printjob.sent", "printjob.received", "printjob.printing", "printjob.done", "printjob.error", "printjob.cancelled", "printjob.expired", "computer.online", "computer.offline", "printer.added", "printer.removed", "printer.online", "printer.offline", "printer.updated" ], "example": "printjob.done", "type": "string" }, "minItems": 1, "type": "array" }, "url": { "example": "https://example.com/inkrelay/webhooks", "maxLength": 2048, "type": "string" } }, "required": [ "url", "events" ], "type": "object" }, "WebhookEndpointUpdate": { "example": { "enabled": true }, "properties": { "description": { "maxLength": 256, "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "events": { "items": { "enum": [ "printjob.queued", "printjob.sent", "printjob.received", "printjob.printing", "printjob.done", "printjob.error", "printjob.cancelled", "printjob.expired", "computer.online", "computer.offline", "printer.added", "printer.removed", "printer.online", "printer.offline", "printer.updated" ], "example": "printjob.done", "type": "string" }, "minItems": 1, "type": "array" }, "url": { "maxLength": 2048, "type": "string" } }, "type": "object" }, "WebhookEndpointWithSecret": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "properties": { "secret": { "description": "Signing secret, returned only by this response. Store it now.", "example": "whsec_C2FVsBQIhrscChlQIMV+b5sSYspob7oD", "type": "string" } }, "required": [ "secret" ], "type": "object" } ] }, "Whoami": { "example": { "apiKeyId": "Kd82jQm1Zp7sW0xe", "mode": "test", "organization": { "id": "Yx3kP9qL2mN8rT4v", "name": "Acme Logistics" }, "plan": "lite", "usage": { "end": "2026-11-01T00:00:00.000Z", "includedPrints": 50, "overagePrints": 0, "start": "2026-10-01T00:00:00.000Z", "usedPrints": 12 } }, "properties": { "apiKeyId": { "type": "string" }, "mode": { "description": "Mode of the calling key", "enum": [ "live", "test" ], "type": "string" }, "organization": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "plan": { "description": "Current plan (lite, essential, standard or premium), as in GET /v1/usage", "type": "string" }, "usage": { "description": "Live usage of the current billing period, the same as period in GET /v1/usage", "properties": { "end": { "description": "First instant after the period (UTC), exclusive", "format": "date-time", "type": "string" }, "includedPrints": { "description": "Live prints the plan includes", "type": "integer" }, "overagePrints": { "description": "Live prints past the included allowance, billed as overage on paid plans (always 0 on Lite)", "type": "integer" }, "start": { "description": "First instant of the period (UTC)", "format": "date-time", "type": "string" }, "usedPrints": { "description": "Live print jobs created so far", "type": "integer" } }, "required": [ "start", "end", "includedPrints", "usedPrints" ], "type": "object" } }, "required": [ "organization", "mode", "apiKeyId", "plan" ], "type": "object" } }, "securitySchemes": { "ApiKeyAuth": { "bearerFormat": "ir_live_ or ir_test_ key", "description": "Send `Authorization: Bearer `. Use an ir_test_ key in the playground; it only reaches virtual test printers.", "scheme": "bearer", "type": "http", "x-default": "ir_test_REPLACE_WITH_YOUR_TEST_KEY" }, "BasicAuth": { "description": "PrintNode compatible: put the API key in the username with an empty password", "scheme": "basic", "type": "http" } } }, "info": { "contact": { "name": "InkRelay", "url": "https://docs.inkrelay.app" }, "description": "Cloud printing API: send PDFs and raw jobs to printers attached to computers running the InkRelay agent.", "title": "InkRelay API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/v1/computers": { "get": { "description": "Lists the computers running the InkRelay agent in the organization and mode of the caller, newest first. A test key sees the virtual test computer.", "operationId": "listComputers", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Cursor: the nextCursor of the previous page", "in": "query", "name": "after", "required": false, "schema": { "description": "Cursor: the nextCursor of the previous page", "format": "uuid", "type": "string" } }, { "description": "desc is newest first; asc is oldest first and suits polling", "in": "query", "name": "dir", "required": false, "schema": { "default": "desc", "description": "desc is newest first; asc is oldest first and suits polling", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Computer" }, "type": "array" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "hasMore", "nextCursor" ], "type": "object" } } }, "description": "A page of computers" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "List computers", "tags": [ "Computers" ] } }, "/v1/computers/{id}": { "delete": { "description": "Soft-deletes the computer and its printers, revokes its agent tokens and disconnects the agent. The virtual test computer cannot be deleted.", "operationId": "deleteComputer", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid id, or the virtual test computer" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found in this organization and mode" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "Delete a computer", "tags": [ "Computers" ] }, "get": { "description": "Returns one computer with its agent version, operating system and connection state.", "operationId": "getComputer", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Computer" } } }, "description": "The computer" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found in this organization and mode" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "Get a computer", "tags": [ "Computers" ] }, "patch": { "description": "Renames a computer or disables it. Disabling disconnects the agent at once; re-enabling lets it reconnect and go online on its next ping.", "operationId": "updateComputer", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "name": "Warehouse packing desk" }, "properties": { "disabled": { "description": "true disconnects the agent and stops printing; false re-enables it", "type": "boolean" }, "name": { "description": "New display name", "maxLength": 100, "minLength": 1, "type": "string" } }, "type": "object" } } }, "description": "Changes" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Computer" } } }, "description": "The updated computer" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found in this organization and mode" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "Rename, disable or re-enable a computer", "tags": [ "Computers" ] } }, "/v1/computers/{id}/printers": { "get": { "description": "Lists the printers that the agent on one computer reports. Returns 404 when the computer is not in the organization and mode of the caller.", "operationId": "listComputerPrinters", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Cursor: the nextCursor of the previous page", "in": "query", "name": "after", "required": false, "schema": { "description": "Cursor: the nextCursor of the previous page", "format": "uuid", "type": "string" } }, { "description": "desc is newest first; asc is oldest first and suits polling", "in": "query", "name": "dir", "required": false, "schema": { "default": "desc", "description": "desc is newest first; asc is oldest first and suits polling", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Printer" }, "type": "array" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "hasMore", "nextCursor" ], "type": "object" } } }, "description": "A page of printers on the computer" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Computer not found in this organization and mode" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "List the printers on a computer", "tags": [ "Printers" ] } }, "/v1/events": { "get": { "description": "The organization's event feed for the caller's mode, the same events webhooks deliver. Page back with dir=desc, or poll for new events with dir=asc and after set to the last id you processed. Polling with dir=asc sees an event about 2 seconds after it happens, so events that commit out of order are never skipped.", "operationId": "listEvents", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Cursor: the nextCursor of the previous page", "in": "query", "name": "after", "required": false, "schema": { "description": "Cursor: the nextCursor of the previous page", "format": "uuid", "type": "string" } }, { "description": "desc is newest first; asc is oldest first and suits polling", "in": "query", "name": "dir", "required": false, "schema": { "default": "desc", "description": "desc is newest first; asc is oldest first and suits polling", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Comma separated event types", "in": "query", "name": "type", "required": false, "schema": { "description": "Comma separated event types", "example": "printjob.done,printjob.error", "type": "string" } }, { "description": "Only events of this print job, printer or computer", "in": "query", "name": "resourceId", "required": false, "schema": { "description": "Only events of this print job, printer or computer", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Event" }, "type": "array" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "hasMore", "nextCursor" ], "type": "object" } } }, "description": "A page of events" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "List events", "tags": [ "Events" ] } }, "/v1/printers": { "get": { "description": "Lists the printers reported by every computer in the organization and mode of the caller. A test key sees the four virtual test printers.", "operationId": "listPrinters", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Cursor: the nextCursor of the previous page", "in": "query", "name": "after", "required": false, "schema": { "description": "Cursor: the nextCursor of the previous page", "format": "uuid", "type": "string" } }, { "description": "desc is newest first; asc is oldest first and suits polling", "in": "query", "name": "dir", "required": false, "schema": { "default": "desc", "description": "desc is newest first; asc is oldest first and suits polling", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Printer" }, "type": "array" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "hasMore", "nextCursor" ], "type": "object" } } }, "description": "A page of printers" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "List printers", "tags": [ "Printers" ] } }, "/v1/printers/{id}": { "get": { "description": "Returns one printer with its state, capabilities, default options and custom paper sizes.", "operationId": "getPrinter", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Printer" } } }, "description": "The printer" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found in this organization and mode" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "Get a printer", "tags": [ "Printers" ] }, "patch": { "description": "Changes the display name, the live flag, default job options, custom paper sizes or remarks of a printer. Only enabled printers accept jobs.", "operationId": "updatePrinter", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "displayName": "Packing label printer", "enabled": true }, "properties": { "customPapers": { "items": { "properties": { "height": { "maximum": 100000, "minimum": 1, "type": "integer" }, "name": { "maxLength": 100, "minLength": 1, "type": "string" }, "width": { "maximum": 100000, "minimum": 1, "type": "integer" } }, "required": [ "name", "width", "height" ], "type": "object" }, "maxItems": 50, "type": "array" }, "defaultOptions": { "additionalProperties": false, "properties": { "bin": { "maxLength": 100, "minLength": 1, "type": "string" }, "collate": { "type": "boolean" }, "color": { "type": "boolean" }, "copies": { "maximum": 999, "minimum": 1, "type": "integer" }, "dpi": { "pattern": "^\\d+x\\d+$", "type": "string" }, "duplex": { "enum": [ "one-sided", "long-edge", "short-edge" ], "type": "string" }, "fit_to_page": { "type": "boolean" }, "media": { "maxLength": 100, "minLength": 1, "type": "string" }, "nup": { "maximum": 16, "minimum": 1, "type": "integer" }, "pages": { "pattern": "^\\d+(-\\d+)?(,\\d+(-\\d+)?)*$", "type": "string" }, "paper": { "maxLength": 100, "minLength": 1, "type": "string" }, "rotate": { "anyOf": [ { "enum": [ 0 ], "type": "number" }, { "enum": [ 90 ], "type": "number" }, { "enum": [ 180 ], "type": "number" }, { "enum": [ 270 ], "type": "number" } ] } }, "type": "object" }, "displayName": { "maxLength": 100, "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "remarks": { "maxLength": 2000, "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Changes" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Printer" } } }, "description": "The updated printer" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found in this organization and mode" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "Update printer settings", "tags": [ "Printers" ] } }, "/v1/printers/{id}/printjobs": { "get": { "description": "Lists the print jobs sent to one printer, newest first by default. Returns 404 when the printer is not in the organization and mode of the caller.", "operationId": "listPrinterPrintJobs", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Cursor: the nextCursor of the previous page", "in": "query", "name": "after", "required": false, "schema": { "description": "Cursor: the nextCursor of the previous page", "format": "uuid", "type": "string" } }, { "description": "desc is newest first; asc is oldest first and suits polling", "in": "query", "name": "dir", "required": false, "schema": { "default": "desc", "description": "desc is newest first; asc is oldest first and suits polling", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PrintJob" }, "type": "array" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "hasMore", "nextCursor" ], "type": "object" } } }, "description": "A page of print jobs of the printer" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Printer not found in this organization and mode" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "List the print jobs of a printer", "tags": [ "Print jobs" ] } }, "/v1/printjobs": { "get": { "description": "Lists the print jobs of the organization and mode of the caller, newest first by default. Filter by printer, computer, state or creation time.", "operationId": "listPrintJobs", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Cursor: the nextCursor of the previous page", "in": "query", "name": "after", "required": false, "schema": { "description": "Cursor: the nextCursor of the previous page", "format": "uuid", "type": "string" } }, { "description": "desc is newest first; asc is oldest first and suits polling", "in": "query", "name": "dir", "required": false, "schema": { "default": "desc", "description": "desc is newest first; asc is oldest first and suits polling", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Only jobs of this printer", "in": "query", "name": "printerId", "required": false, "schema": { "description": "Only jobs of this printer", "format": "uuid", "type": "string" } }, { "description": "Only jobs of this computer", "in": "query", "name": "computerId", "required": false, "schema": { "description": "Only jobs of this computer", "format": "uuid", "type": "string" } }, { "description": "Only jobs in this state", "in": "query", "name": "state", "required": false, "schema": { "description": "Only jobs in this state", "enum": [ "queued", "sent", "received", "printing", "done", "error", "cancelled", "expired" ], "type": "string" } }, { "description": "Only jobs created at or after this ISO 8601 time", "in": "query", "name": "createdFrom", "required": false, "schema": { "description": "Only jobs created at or after this ISO 8601 time", "format": "date-time", "type": "string" } }, { "description": "Only jobs created at or before this ISO 8601 time", "in": "query", "name": "createdTo", "required": false, "schema": { "description": "Only jobs created at or before this ISO 8601 time", "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PrintJob" }, "type": "array" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "hasMore", "nextCursor" ], "type": "object" } } }, "description": "A page of print jobs" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "List print jobs", "tags": [ "Print jobs" ] }, "post": { "description": "Queues a PDF or raw document for a printer. Send an Idempotency-Key header to make retries safe: a repeat with the same body returns the first response with header Idempotent-Replayed: true. To print an earlier job again, send reprintOf with its id instead of contentType and content.", "operationId": "createPrintJob", "parameters": [ { "description": "Any unique string up to 255 characters; retries with it never print twice", "in": "header", "name": "idempotency-key", "required": false, "schema": { "description": "Any unique string up to 255 characters; retries with it never print twice", "example": "invoice-1042-print-1", "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJobCreate" } } }, "description": "Job to print" }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJob" } } }, "description": "The queued job" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request body or Idempotency-Key" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "quota_exceeded: the Lite plan's live prints for this period are used up; error.upgrade_url links to the billing page" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Printer, or the job named in reprintOf, not found in this organization and mode" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "A request with this Idempotency-Key is still being processed" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The file of the job named in reprintOf is no longer stored" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Content larger than 25 MB, or a request body larger than 36 MB" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid content, content URL, printer mode, disabled printer or Idempotency-Key reuse" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key (retry after the Retry-After header), or test_mode_daily_cap: the test mode daily job cap is reached", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "File storage is temporarily unavailable" } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "Create a print job", "tags": [ "Print jobs" ] } }, "/v1/printjobs/{id}": { "get": { "description": "Returns one print job with its current state and the time of each state change so far.", "operationId": "getPrintJob", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJob" } } }, "description": "The print job" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found in this organization and mode" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "Get a print job", "tags": [ "Print jobs" ] } }, "/v1/printjobs/{id}/cancel": { "post": { "description": "Cancels a print job that is still queued or sent; the agent drops it if it already has it. Jobs the printer has received can no longer be cancelled.", "operationId": "cancelPrintJob", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJob" } } }, "description": "The cancelled job" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this; members cannot cancel jobs" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found in this organization and mode" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The job is past the point where it can be cancelled" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "Cancel a print job", "tags": [ "Print jobs" ] } }, "/v1/printjobs/{id}/events": { "get": { "description": "Lists every state change of one print job, oldest first, with the message and the actor (api, user, agent or system) behind it.", "operationId": "listPrintJobEvents", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PrintJobEvent" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "State changes, oldest first" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found in this organization and mode" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "List the state changes of a print job", "tags": [ "Print jobs" ] } }, "/v1/usage": { "get": { "description": "Returns the plan, the live prints it includes this billing period, the live prints used so far (overage past the allowance on paid plans) and earlier periods. Lite periods are calendar months; paid periods follow the subscription's renewal date. Test mode jobs never count, so a test key sees the same live usage.", "operationId": "getUsage", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } }, "description": "Usage of the current period" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "Get print usage for this period", "tags": [ "Usage" ] } }, "/v1/webhooks": { "get": { "description": "Lists webhook endpoints in the organization and mode of the calling key, newest first. Secrets are never included.", "operationId": "listWebhooks", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Cursor: the nextCursor of the previous page", "in": "query", "name": "after", "required": false, "schema": { "description": "Cursor: the nextCursor of the previous page", "format": "uuid", "type": "string" } }, { "description": "desc is newest first; asc is oldest first and suits polling", "in": "query", "name": "dir", "required": false, "schema": { "default": "desc", "description": "desc is newest first; asc is oldest first and suits polling", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookEndpoint" }, "type": "array" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "hasMore", "nextCursor" ], "type": "object" } } }, "description": "A page of endpoints" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "List webhook endpoints", "tags": [ "Webhooks" ] }, "post": { "description": "Creates an endpoint in the mode of the calling key. The response holds the signing secret; store it now, it is never shown again. Live endpoints need https and every URL must resolve to a public address.", "operationId": "createWebhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreate" } } }, "description": "Endpoint to create", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } } }, "description": "The new endpoint with its secret" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The URL was refused (invalid_url)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "Create a webhook endpoint", "tags": [ "Webhooks" ] } }, "/v1/webhooks/deliveries/{id}/replay": { "post": { "description": "Sends the same event again as a new delivery with its own retry schedule. webhook-id stays the event id, so receivers that already processed it can skip it.", "operationId": "replayWebhookDelivery", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "description": "The new delivery, queued" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found in this organization and mode" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The endpoint is disabled (endpoint_disabled)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "Replay a delivery", "tags": [ "Webhooks" ] } }, "/v1/webhooks/{id}": { "delete": { "description": "Deletes the endpoint and its delivery log; queued retries stop.", "operationId": "deleteWebhook", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found in this organization and mode" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "Delete a webhook endpoint", "tags": [ "Webhooks" ] }, "get": { "description": "Returns one endpoint, including whether it is enabled and why it was disabled.", "operationId": "getWebhook", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "description": "The endpoint" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found in this organization and mode" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "Get a webhook endpoint", "tags": [ "Webhooks" ] }, "patch": { "description": "Changes the URL, description, events or enabled flag. Enabling clears failingSince and disabledReason.", "operationId": "updateWebhook", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointUpdate" } } }, "description": "Changes", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "description": "The updated endpoint" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found in this organization and mode" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The URL was refused (invalid_url)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "Update a webhook endpoint", "tags": [ "Webhooks" ] } }, "/v1/webhooks/{id}/deliveries": { "get": { "description": "Delivery log for one endpoint, newest first, kept for 30 days. Filter with status to find failed deliveries to replay.", "operationId": "listWebhookDeliveries", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Cursor: the nextCursor of the previous page", "in": "query", "name": "after", "required": false, "schema": { "description": "Cursor: the nextCursor of the previous page", "format": "uuid", "type": "string" } }, { "description": "desc is newest first; asc is oldest first and suits polling", "in": "query", "name": "dir", "required": false, "schema": { "default": "desc", "description": "desc is newest first; asc is oldest first and suits polling", "enum": [ "asc", "desc" ], "type": "string" } }, { "in": "query", "name": "status", "required": false, "schema": { "enum": [ "pending", "retrying", "succeeded", "failed" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookDelivery" }, "type": "array" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "hasMore", "nextCursor" ], "type": "object" } } }, "description": "A page of deliveries" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found in this organization and mode" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "List deliveries for an endpoint", "tags": [ "Webhooks" ] } }, "/v1/webhooks/{id}/ping": { "post": { "description": "Queues a signed ping delivery to the endpoint, with the usual retries, to check that it receives and verifies webhooks. The body is an envelope of type ping with empty data. Pings are not events: they never appear in GET /v1/events and never count as usage.", "operationId": "pingWebhook", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "description": "The ping delivery, queued" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found in this organization and mode" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The endpoint is disabled (endpoint_disabled)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "Send a test ping", "tags": [ "Webhooks" ] } }, "/v1/webhooks/{id}/rotate-secret": { "post": { "description": "Replaces the signing secret and returns the new one; store it now, it is never shown again. Until previousSecretExpiresAt every delivery carries two signatures, one per secret, so receivers can switch without dropping deliveries. A rotation during an overlap replaces the older secret.", "operationId": "rotateWebhookSecret", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "overlapSeconds": { "default": 86400, "description": "How long deliveries stay signed with the old secret too (0 to 604800 seconds, default 1 day). 0 drops it at once.", "example": 86400, "maximum": 604800, "minimum": 0, "type": "integer" } }, "type": "object" } } }, "description": "Rotation options", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } } }, "description": "The endpoint with its new secret" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not found in this organization and mode" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "Rotate a webhook signing secret", "tags": [ "Webhooks" ] } }, "/v1/whoami": { "get": { "description": "Returns the organization, mode, key id, plan and current period usage of the API key that signs the request. Use it to check that a key works.", "operationId": "getWhoami", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Whoami" } } }, "description": "Caller identity" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Missing or invalid API key or session" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The key scope or member role does not allow this" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "rate_limited: more than 20 requests per second with this API key; retry after the Retry-After header", "headers": { "RateLimit-Limit": { "description": "Requests allowed per second for this API key (20)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current one second window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window frees a request", "schema": { "type": "integer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying; present on rate_limited", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "summary": "Identify the organization behind an API key", "tags": [ "Account" ] } } }, "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "servers": [ { "description": "Production", "url": "https://api.inkrelay.app" } ], "tags": [ { "description": "Who you are, your plan and usage", "name": "Account" }, { "description": "Machines running the InkRelay agent", "name": "Computers" }, { "description": "Printers reported by agents", "name": "Printers" }, { "description": "Submit and track print jobs", "name": "Print jobs" }, { "description": "Signed event delivery to your HTTPS endpoints", "name": "Webhooks" }, { "description": "Cursor based event feed", "name": "Events" }, { "description": "Prints used this period", "name": "Usage" } ], "webhooks": {} }