{
    "openapi": "3.1.0",
    "info": {
        "title": "CloudPrint API",
        "description": "Remote document printing API for backend clients and print agents.",
        "version": "0.1.0"
    },
    "servers": [
        {
            "url": "http://localhost:8080",
            "description": "Local development"
        }
    ],
    "paths": {
        "/api/v1/me": {
            "get": {
                "tags": [
                    "Auth"
                ],
                "summary": "Get current API client context",
                "operationId": "getApiClientContext",
                "responses": {
                    "200": {
                        "description": "Current API client context",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ApiClientContext"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "OAuth bearer token is invalid"
                    },
                    "429": {
                        "description": "Rate limit exceeded",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerAuth": []
                    }
                ]
            }
        },
        "/oauth/token": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Issue OAuth2 access token using client credentials",
                "operationId": "issueOAuthToken",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "required": [
                                    "grant_type",
                                    "client_id",
                                    "client_secret"
                                ],
                                "properties": {
                                    "grant_type": {
                                        "type": "string",
                                        "example": "client_credentials"
                                    },
                                    "client_id": {
                                        "type": "string",
                                        "format": "uuid"
                                    },
                                    "client_secret": {
                                        "type": "string"
                                    },
                                    "scope": {
                                        "description": "Space-separated scopes. The token request is rejected when any requested scope is unknown or not granted to the client app.",
                                        "type": "string",
                                        "example": "documents:write print_jobs:write"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Access token issued"
                    },
                    "400": {
                        "description": "Invalid OAuth2 request"
                    },
                    "401": {
                        "description": "Invalid OAuth2 client credentials"
                    },
                    "429": {
                        "description": "Rate limit exceeded",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/documents": {
            "post": {
                "tags": [
                    "Documents"
                ],
                "summary": "Upload document for printing",
                "operationId": "uploadDocument",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "required": [
                                    "file"
                                ],
                                "properties": {
                                    "file": {
                                        "description": "Supported file types: PDF and ZPL. Convert DOC and DOCX files to PDF before uploading.",
                                        "type": "string",
                                        "format": "binary"
                                    },
                                    "document_format": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "enum": [
                                            "pdf",
                                            "zpl"
                                        ],
                                        "example": "zpl"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Document uploaded",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/UploadedDocument"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid upload request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "413": {
                        "description": "Uploaded file is too large",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "415": {
                        "description": "Uploaded file type is not supported by the Public API",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Document validation failed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Unexpected error"
                    }
                },
                "security": [
                    {
                        "BearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/print-jobs": {
            "get": {
                "tags": [
                    "Print jobs"
                ],
                "summary": "List print jobs",
                "operationId": "listPrintJobs",
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Maximum number of print jobs to return.",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 20,
                            "maximum": 100,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "description": "Cursor from the previous response next_cursor field.",
                        "required": false,
                        "schema": {
                            "type": [
                                "string",
                                "null"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Print jobs",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PrintJobList"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "OAuth bearer token is invalid",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "OAuth bearer token does not include print_jobs:read",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Print jobs"
                ],
                "summary": "Create print job",
                "operationId": "createPrintJob",
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "description": "Optional key that makes create-print-job retries safe for the same account and payload.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "maxLength": 128
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreatePrintJobRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Print job created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PrintJob"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Print job validation failed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Idempotency key conflict",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Unexpected error"
                    }
                },
                "security": [
                    {
                        "BearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/print-jobs/{printJobId}": {
            "get": {
                "tags": [
                    "Print jobs"
                ],
                "summary": "Get print job status",
                "operationId": "getPrintJob",
                "parameters": [
                    {
                        "name": "printJobId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Print job",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PrintJob"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Print job not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Unexpected error"
                    }
                },
                "security": [
                    {
                        "BearerAuth": []
                    }
                ]
            }
        },
        "/api/v1/printers": {
            "get": {
                "tags": [
                    "Printers"
                ],
                "summary": "List account printers",
                "operationId": "listPrinters",
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Maximum number of printers to return.",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 100,
                            "maximum": 100,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "description": "Cursor from the previous response next_cursor field.",
                        "required": false,
                        "schema": {
                            "type": [
                                "string",
                                "null"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Account printers",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PrinterList"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Unexpected error"
                    }
                },
                "security": [
                    {
                        "BearerAuth": []
                    }
                ]
            }
        }
    },
    "components": {
        "schemas": {
            "ApiClientContext": {
                "required": [
                    "account_id",
                    "account_name",
                    "client_app_id",
                    "client_app_name",
                    "scopes"
                ],
                "properties": {
                    "account_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "account_name": {
                        "type": "string",
                        "example": "Acme Print Ops"
                    },
                    "client_app_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "client_app_name": {
                        "type": "string",
                        "example": "Warehouse integration"
                    },
                    "scopes": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "documents:write",
                            "print_jobs:write",
                            "printers:read"
                        ]
                    }
                },
                "type": "object"
            },
            "UploadedDocument": {
                "required": [
                    "document_id",
                    "original_filename",
                    "mime_type",
                    "document_format",
                    "size_bytes"
                ],
                "properties": {
                    "document_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "original_filename": {
                        "type": "string",
                        "example": "invoice.pdf"
                    },
                    "mime_type": {
                        "type": "string",
                        "example": "application/pdf"
                    },
                    "document_format": {
                        "type": "string",
                        "enum": [
                            "pdf",
                            "zpl"
                        ],
                        "example": "pdf"
                    },
                    "size_bytes": {
                        "type": "integer",
                        "example": 1024
                    }
                },
                "type": "object"
            },
            "CreatePrintJobRequest": {
                "required": [
                    "document_id",
                    "printer_id"
                ],
                "properties": {
                    "document_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "printer_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "copies": {
                        "type": "integer",
                        "minimum": 1,
                        "example": 1
                    },
                    "color_mode": {
                        "type": "string",
                        "enum": [
                            "default",
                            "monochrome",
                            "color"
                        ],
                        "example": "default"
                    },
                    "duplex_mode": {
                        "type": "string",
                        "enum": [
                            "default",
                            "simplex",
                            "duplex_long_edge",
                            "duplex_short_edge"
                        ],
                        "example": "default"
                    },
                    "media_width_mm": {
                        "type": [
                            "number",
                            "null"
                        ],
                        "example": 58
                    },
                    "media_height_mm": {
                        "type": [
                            "number",
                            "null"
                        ],
                        "example": 40
                    },
                    "dpi": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "example": 203
                    },
                    "scale_mode": {
                        "type": "string",
                        "enum": [
                            "none",
                            "fit"
                        ],
                        "example": "none"
                    },
                    "orientation": {
                        "type": "string",
                        "enum": [
                            "default",
                            "portrait",
                            "landscape"
                        ],
                        "example": "default"
                    },
                    "offset_x_mm": {
                        "type": "number",
                        "example": 0
                    },
                    "offset_y_mm": {
                        "type": "number",
                        "example": 0
                    },
                    "margin_top_mm": {
                        "type": "number",
                        "minimum": 0,
                        "example": 0
                    },
                    "margin_right_mm": {
                        "type": "number",
                        "minimum": 0,
                        "example": 0
                    },
                    "margin_bottom_mm": {
                        "type": "number",
                        "minimum": 0,
                        "example": 0
                    },
                    "margin_left_mm": {
                        "type": "number",
                        "minimum": 0,
                        "example": 0
                    }
                },
                "type": "object"
            },
            "PrintJob": {
                "required": [
                    "print_job_id",
                    "document_id",
                    "document_mime_type",
                    "document_format",
                    "printer_id",
                    "status",
                    "copies",
                    "color_mode",
                    "duplex_mode",
                    "scale_mode",
                    "orientation",
                    "offset_x_mm",
                    "offset_y_mm",
                    "margin_top_mm",
                    "margin_right_mm",
                    "margin_bottom_mm",
                    "margin_left_mm",
                    "attempt_count",
                    "retry_after"
                ],
                "properties": {
                    "print_job_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "document_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "document_mime_type": {
                        "type": "string",
                        "example": "application/pdf"
                    },
                    "document_format": {
                        "type": "string",
                        "enum": [
                            "pdf",
                            "zpl"
                        ],
                        "example": "pdf"
                    },
                    "printer_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "status": {
                        "type": "string",
                        "example": "pending"
                    },
                    "copies": {
                        "type": "integer",
                        "example": 1
                    },
                    "color_mode": {
                        "type": "string",
                        "enum": [
                            "default",
                            "monochrome",
                            "color"
                        ],
                        "example": "default"
                    },
                    "duplex_mode": {
                        "type": "string",
                        "enum": [
                            "default",
                            "simplex",
                            "duplex_long_edge",
                            "duplex_short_edge"
                        ],
                        "example": "default"
                    },
                    "media_width_mm": {
                        "type": [
                            "number",
                            "null"
                        ],
                        "example": 58
                    },
                    "media_height_mm": {
                        "type": [
                            "number",
                            "null"
                        ],
                        "example": 40
                    },
                    "dpi": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "example": 203
                    },
                    "scale_mode": {
                        "type": "string",
                        "enum": [
                            "none",
                            "fit"
                        ],
                        "example": "none"
                    },
                    "orientation": {
                        "type": "string",
                        "enum": [
                            "default",
                            "portrait",
                            "landscape"
                        ],
                        "example": "default"
                    },
                    "offset_x_mm": {
                        "type": "number",
                        "example": 0
                    },
                    "offset_y_mm": {
                        "type": "number",
                        "example": 0
                    },
                    "margin_top_mm": {
                        "type": "number",
                        "minimum": 0,
                        "example": 0
                    },
                    "margin_right_mm": {
                        "type": "number",
                        "minimum": 0,
                        "example": 0
                    },
                    "margin_bottom_mm": {
                        "type": "number",
                        "minimum": 0,
                        "example": 0
                    },
                    "margin_left_mm": {
                        "type": "number",
                        "minimum": 0,
                        "example": 0
                    },
                    "created_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "reserved_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "started_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "completed_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "failure_reason": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "attempt_count": {
                        "type": "integer",
                        "example": 1
                    },
                    "retry_after": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    }
                },
                "type": "object"
            },
            "PrintJobList": {
                "required": [
                    "print_jobs",
                    "next_cursor"
                ],
                "properties": {
                    "print_jobs": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/PrintJob"
                        }
                    },
                    "next_cursor": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                },
                "type": "object"
            },
            "PrinterCapabilities": {
                "required": [
                    "backend",
                    "supports_pdf",
                    "supports_zpl",
                    "supports_custom_media",
                    "supports_orientation",
                    "supports_copies",
                    "supports_duplex",
                    "supports_color",
                    "supports_scaling",
                    "supports_offsets",
                    "supports_printable_area"
                ],
                "properties": {
                    "backend": {
                        "type": "string",
                        "enum": [
                            "cups",
                            "windows_native",
                            "custom_command",
                            "simulate"
                        ],
                        "example": "windows_native"
                    },
                    "supports_pdf": {
                        "type": "boolean"
                    },
                    "supports_zpl": {
                        "type": "boolean"
                    },
                    "supports_custom_media": {
                        "type": "boolean"
                    },
                    "supports_orientation": {
                        "type": "boolean"
                    },
                    "supports_copies": {
                        "type": "boolean"
                    },
                    "supports_duplex": {
                        "type": "boolean"
                    },
                    "supports_color": {
                        "type": "boolean"
                    },
                    "supports_scaling": {
                        "type": "boolean"
                    },
                    "supports_offsets": {
                        "type": "boolean"
                    },
                    "supports_printable_area": {
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "Printer": {
                "required": [
                    "printer_id",
                    "local_identifier",
                    "name",
                    "status",
                    "last_seen_at",
                    "capabilities"
                ],
                "properties": {
                    "printer_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "local_identifier": {
                        "type": "string",
                        "example": "zebra-zd421-usb-001"
                    },
                    "name": {
                        "type": "string",
                        "example": "Warehouse Label Printer"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "online",
                            "offline",
                            "unknown"
                        ]
                    },
                    "last_seen_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "capabilities": {
                        "$ref": "#/components/schemas/PrinterCapabilities"
                    }
                },
                "type": "object"
            },
            "PrinterList": {
                "required": [
                    "printers",
                    "next_cursor"
                ],
                "properties": {
                    "printers": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Printer"
                        }
                    },
                    "next_cursor": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                },
                "type": "object"
            },
            "ErrorResponse": {
                "required": [
                    "error",
                    "message"
                ],
                "properties": {
                    "error": {
                        "description": "Stable machine-readable error code.",
                        "type": "string"
                    },
                    "error_code": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "message": {
                        "description": "Safe human-readable error message. The message is localized by Accept-Language when a supported translation exists.",
                        "type": "string"
                    }
                },
                "type": "object"
            }
        },
        "securitySchemes": {
            "BearerAuth": {
                "type": "http",
                "description": "OAuth2 client credentials access token.",
                "bearerFormat": "JWT",
                "scheme": "bearer"
            }
        }
    },
    "tags": [
        {
            "name": "Auth"
        },
        {
            "name": "Documents"
        },
        {
            "name": "Print jobs"
        },
        {
            "name": "Printers"
        }
    ]
}