openapi: 3.0.3
info:
  title: Caldera REST API v2.2.0
  contact: {}
  version: 2.2.0
  description: 'Caldera REST API v2.2.0 targeting a wide range of usage from completely custom made integration to perfect integration within a large range of entreprise grade production and business management.'
  license:
    name: Commercial
servers:
  - url: '{protocol}://{host}:{port}/v{version}'
    variables:
      protocol:
        default: http
      host:
        default: localhost
      port:
        default: '12340'
      version:
        default: '1'
paths:
  /services:
    get:
      tags:
        - Services
      summary: 'List services for job(s), operation(s), device(s), ..'
      description: Get information about service(s)
      operationId: services_GET
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Filter'
      responses:
        '200':
          description: List of available service(s)
          headers:
            caldera-page:
              $ref: '#/components/headers/caldera-page'
            caldera-limit:
              $ref: '#/components/headers/caldera-limit'
            caldera-total-results:
              $ref: '#/components/headers/caldera-total-results'
            caldera-sort:
              $ref: '#/components/headers/caldera-sort'
            caldera-filter:
              $ref: '#/components/headers/caldera-filter'
            link:
              $ref: '#/components/headers/link'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Service'
                description: ''
      deprecated: false
    head:
      tags:
        - Services
      summary: 'Count services'
      description: Count service(s)
      operationId: services_HEAD
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Filter'
      responses:
        '200':
          description: Number of service(s)
          headers:
            caldera-page:
              $ref: '#/components/headers/caldera-page'
            caldera-limit:
              $ref: '#/components/headers/caldera-limit'
            caldera-total-results:
              $ref: '#/components/headers/caldera-total-results'
            caldera-sort:
              $ref: '#/components/headers/caldera-sort'
            caldera-filter:
              $ref: '#/components/headers/caldera-filter'
            link:
              $ref: '#/components/headers/link'
      deprecated: false
    post:
      summary: Add service(s)
      tags:
        - Services
      operationId: services_POST
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Service'
      description: 'Add service(s) from the host specified'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  host:
                    type: string
                    example: '10.59.3.127'
                  type:
                    $ref: '#/components/schemas/ServiceType'
                  license:
                    type: string
                    example: '820718241426951368'
                  port:
                    type: number
                    nullable: true
                    example: 45344
                required:
                  - host
                  - type
                  - license
        description: Array of host + service + license to register
    delete:
      summary: Unregister all services (except the Caldera REST API service itself)
      tags:
        - Services
      operationId: services_DELETE
      responses:
        '200':
          description: All services have been successfully unregistered
      description: Unregister all services
  /services/{service}:
    parameters:
      - schema:
          type: string
        name: service
        in: path
        required: true
        description: Service ID
    get:
      tags:
        - Services
      summary: 'Get service'
      description: Get information about a service
      operationId: services_id_GET
      responses:
        '200':
          description: List of available service(s)
          headers:
            X-Collection-Length:
              description: "Number of services."
              schema:
                type: "number"
              example: 5
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Service'
                description: ''
        '403':
          description: Only for service type `calderarip`, its missing CalderaCare licensing to reply useful data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
                description: 'Forbidden access, please contact your reseller to buy a license to use the Caldera REST API.'
      deprecated: false
    delete:
      tags:
        - Services
      summary: 'Unregister service'
      description: Unregister a service
      operationId: services_id_DELETE
      responses:
        '200':
          description: Service successfully unregistered
      deprecated: false
  /services/{service}/images:
    parameters:
      - schema:
          type: string
        name: service
        in: path
        required: true
        description: Service ID
    post:
      tags:
        - Services
      summary: 'Import an image into the service'
      description: Import an image into the service. The image will be usable via an identifier.
      operationId: services_id_image_POST
      responses:
        '201':
          description: The image has been imported into the service, and can be manipulated via the returned ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 'MTI3LjAuMC4xOjQ1MzQzfmNhbGRlcmFyaXB-aW1nLjEyMzQ1Ng'
        '400':
          description: Bad Request. A field in the request cannot be served by the API. It can be for example, the file URI which is unsupported (http://, ftp://, …).
          headers:
            caldera-supported-file-uri:
              schema:
                type: string
                description: A list of supported file URIs.
                example: file, http, ftp
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '405':
          description: Method not allowed on this service (unable to add an image).
          headers:
            Allow:
              schema:
                type: string
                example: GET, POST, HEAD
            caldera-notice:
              schema:
                type: string
              description: Information about the response, e.g. why some methods are allowed or not. Here, it will probably depends on the related service whose don't support all operations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '413':
          description: The image size is too big.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '415':
          description: The image type is not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Unknown server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                uri:
                  type: string
                  example: 'file:///path/to/image.png'
                  description: A file URI. Must begins with a scheme (file://, …)
              required:
                - uri
      deprecated: false
  /devices:
    get:
      tags:
        - Devices
      summary: Return device(s)
      operationId: devices_GET
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Filter'
      responses:
        '200':
          description: List available device(s)
          headers:
            caldera-page:
              $ref: '#/components/headers/caldera-page'
            caldera-limit:
              $ref: '#/components/headers/caldera-limit'
            caldera-total-results:
              $ref: '#/components/headers/caldera-total-results'
            caldera-sort:
              $ref: '#/components/headers/caldera-sort'
            caldera-filter:
              $ref: '#/components/headers/caldera-filter'
            caldera-notice:
              schema:
                type: string
              description: Information about the response , e.g. limited results due to licensing.
            link:
              $ref: '#/components/headers/link'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Device'
                description: ''
      deprecated: false
      description: List device(s)
    head:
      tags:
        - Devices
      summary: Count device(s)
      operationId: devices_HEAD
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Filter'
      responses:
        '200':
          description: Count available device(s)
          headers:
            caldera-page:
              $ref: '#/components/headers/caldera-page'
            caldera-limit:
              $ref: '#/components/headers/caldera-limit'
            caldera-total-results:
              $ref: '#/components/headers/caldera-total-results'
            caldera-sort:
              $ref: '#/components/headers/caldera-sort'
            caldera-filter:
              $ref: '#/components/headers/caldera-filter'
            caldera-notice:
              schema:
                type: string
              description: Information about the response , e.g. limited results due to licensing.
            link:
              $ref: '#/components/headers/link'
      deprecated: false
      description: Count device(s)
  /devices/{device}/presets:
    parameters:
      - schema:
          type: string
        name: device
        in: path
        required: true
        description: Device ID
    get:
      tags:
        - Devices
      summary: Return preset(s) of a specific device
      operationId: devices_id_presets_GET
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Filter'
      responses:
        '200':
          description: List available preset(s) of a device
          headers:
            caldera-page:
              $ref: '#/components/headers/caldera-page'
            caldera-limit:
              $ref: '#/components/headers/caldera-limit'
            caldera-total-results:
              $ref: '#/components/headers/caldera-total-results'
            caldera-sort:
              $ref: '#/components/headers/caldera-sort'
            caldera-filter:
              $ref: '#/components/headers/caldera-filter'
            link:
              $ref: '#/components/headers/link'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Preset'
                description: ''
      deprecated: false
      description: List preset(s)
    head:
      tags:
        - Devices
      summary: Count preset(s) of a specific device
      operationId: devices_id_presets_HEAD
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Filter'
      responses:
        '200':
          description: Count available preset(s) of a device
          headers:
            caldera-page:
              $ref: '#/components/headers/caldera-page'
            caldera-limit:
              $ref: '#/components/headers/caldera-limit'
            caldera-total-results:
              $ref: '#/components/headers/caldera-total-results'
            caldera-sort:
              $ref: '#/components/headers/caldera-sort'
            caldera-filter:
              $ref: '#/components/headers/caldera-filter'
            link:
              $ref: '#/components/headers/link'
      deprecated: false
      description: Count preset(s)
  /devices/{device}/state:
    parameters:
      - schema:
          type: string
        name: device
        in: path
        required: true
        description: Device ID
    put:
      tags:
        - Devices
      summary: Alter state of a specific device
      description: Alter state of a specific device
      operationId: devices_id_operate_PUT
      requestBody:
        content:
          application/json:
            schema:
              type: string
              pattern: "running"
              example: The state to be put in the device. Supports "running", "stopped" and "blocked" states.
      responses:
        '200':
          description: Operation successfully executed
          headers:
            link:
              $ref: '#/components/headers/link'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
                description: 'Explanation of the error. The request is malformed, the operation does not exists or is not supported by the device.'
        '403':
          description: Operation Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
                description: 'Explanation of the error. Forbidden access, the device may have refused the operation.'
        '404':
          description: Device not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
                description: 'Explanation of the error. The device is not found.'
        '500':
          description: Operation failed to be executed, or an unknown error happened.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
                description: 'Explanation of the error. The device may not accept the new state value.'
      deprecated: false
  /devices/{device}/jobs:
    parameters:
      - schema:
          type: string
        name: device
        in: path
        required: true
        description: Device ID
    post:
      tags:
        - Devices
      summary: 'Submit a new job to this device'
      description: |
        Submit an image to a device to create a job.
        The job will be filterable by its ID if persistJobInRIP is specified to true,
        otherwise the job will be automatically deleted after processing.
      operationId: devices_id_job_POST
      responses:
        '201':
          description: |
            The job has been created, and can be filtered by the returned ID if persistJobInRIP is specified to true.

            Most often, the returned array will contain only one job ID, but in some rare cases (eg. dual side printing) it can contain multiple.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      example: 'bG9jYWxob3N0OjQ1MzQzfmNhbGRlcmFyaXB-Q2FsZGVyYUpldH4x'
        '400':
          description: Bad request. The request cannot be treated successfully due to wrong request (invalid syntax, invalid field, unreachable objects ids, …)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
        '500':
          description: Unknown server error.
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/JobPrintSubmission'
      deprecated: false
  /devices/{device}/information:
    parameters:
      - schema:
          type: string
        name: device
        in: path
        required: true
        description: Device ID
    get:
      tags:
        - Devices
      summary: Return machine information of a specific device
      operationId: devices_id_machine_information_GET
      responses:
        '200':
          description: Show machine information (loading, inks bottles, …) of a device
          headers:
            link:
              $ref: '#/components/headers/link'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MachineInformation'
        '503':
          description: "Service unavailable: the server cannot handle the request (because it is not supported or down)."
      deprecated: false
      description: Fetch machine information
  /jobs:
    get:
      summary: Retrieve job(s)
      tags:
        - Jobs
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Filter'
      responses:
        '200':
          description: OK
          headers:
            caldera-page:
              $ref: '#/components/headers/caldera-page'
            caldera-limit:
              $ref: '#/components/headers/caldera-limit'
            caldera-total-results:
              $ref: '#/components/headers/caldera-total-results'
            caldera-sort:
              $ref: '#/components/headers/caldera-sort'
            caldera-filter:
              $ref: '#/components/headers/caldera-filter'
            caldera-notice:
              schema:
                type: string
              description: Information about the response , e.g. limited results due to licensing.
            link:
              $ref: '#/components/headers/link'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Job'
                description: ''
      operationId: jobs_GET
      description: Returns a list of job(s)
    head:
      summary: Count job(s)
      tags:
        - Jobs
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Filter'
      responses:
        '200':
          description: OK
          headers:
            caldera-page:
              $ref: '#/components/headers/caldera-page'
            caldera-limit:
              $ref: '#/components/headers/caldera-limit'
            caldera-total-results:
              $ref: '#/components/headers/caldera-total-results'
            caldera-sort:
              $ref: '#/components/headers/caldera-sort'
            caldera-filter:
              $ref: '#/components/headers/caldera-filter'
            caldera-notice:
              schema:
                type: string
              description: Information about the response , e.g. limited results due to licensing.
            link:
              $ref: '#/components/headers/link'
      operationId: jobs_HEAD
      description: Count job(s)
  /jobs/{job}:
    parameters:
      - schema:
          type: string
        name: job
        in: path
        required: true
        description: Job ID
    get:
      tags:
        - Jobs
      summary: 'Get job'
      description: Get information about a job
      operationId: jobs_id_GET
      responses:
        '200':
          description: Job information
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '403':
          description: Only for devices from service type `calderarip`, its missing CalderaCare licensing to reply data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
                description: 'Forbidden access, please contact your reseller to buy a license to use the Caldera REST API.'
      deprecated: false
    delete:
        tags:
          - Jobs
        summary: 'Delete job'
        description: Delete an existing job
        operationId: jobs_id_DELETE
        responses:
          '200':
            description: Job successfully deleted
            headers: {}
          '404':
            description: Job not found
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Problem'
          '502':
            description: Remote server responded an error
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Problem'
        deprecated: false
  /jobs/{job}/abort:
    parameters:
      - schema:
          type: string
        name: job
        in: path
        required: true
        description: Job ID
    post:
      tags:
        - Jobs
      summary: 'Abort job'
      description: Abort a running job. Returns the updated job when successfully aborted (200), or no content if the job was already aborted (204).
      operationId: jobs_id_abort_POST
      responses:
        '200':
          description: Job successfully aborted — updated job state returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '204':
          description: Job was already aborted — no content
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Remote server responded an error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      deprecated: false
  /jobs/{job}/release:
    parameters:
      - schema:
          type: string
        name: job
        in: path
        required: true
        description: Job ID
    post:
      tags:
        - Jobs
      summary: 'Release job'
      description: Release a blocked job, returning the updated job state
      operationId: jobs_id_release_POST
      responses:
        '200':
          description: Job successfully released — updated job state returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Remote server responded an error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      deprecated: false
  /jobs/{job}/thumbnail:
    parameters:
      - schema:
          type: string
        name: job
        in: path
        required: true
        description: Job ID
    get:
      tags:
        - Jobs
      summary: Get thumbnail
      description: Get the thumbnail image of a job
      operationId: jobs_id_thumbnail_GET
      responses:
        '200':
          description: Success (thumbnail image)
          content:
            image/png:
              schema:
                type: string
                format: binary
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Remote server responded an error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      deprecated: false
  /jobs/{job}/preview:
    parameters:
      - schema:
          type: string
        name: job
        in: path
        required: true
        description: Job ID
    get:
      tags:
        - Jobs
      summary: Get thumbnail preview
      description: Get the thumbnail image preview of a job
      operationId: jobs_id_thumbnail_preview_GET
      responses:
        '200':
          description: Success (thumbnail preview image)
          content:
            application/octet-stream:
              schema:
                type: string
                format: stream
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Remote server responded an error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      deprecated: false
  /jobs/{job}/export:
    parameters:
      - schema:
          type: string
        name: job
        in: path
        required: true
        description: Job ID
      - schema:
          type: boolean
        name: includeRippedFiles
        in: query
        example: false
        required: false
        description: Include ripped files in the archive
      - schema:
          type: boolean
        name: includeSourceFiles
        in: query
        example: false
        required: false
        description: Include source files in the archive
    get:
      tags:
        - Jobs
      summary: 'Export a job'
      description: Export and download a job archive (.caljob)
      operationId: jobs_id_archive_GET
      responses:
        '200':
          description: Job archive stream
          headers: {}
          content:
            application/octet-stream:
              schema:
                type: string
                format: stream
      deprecated: false
  /jobs/import:
    post:
      tags:
        - Jobs
      summary: Import a job
      description: Import a job archive (.caljob) adding a new job to the target device
      operationId: jobs_archive_POST
      parameters:
        - name: deviceId
          in: query
          required: true
          description: The encoded ID of the target device to import the job into
          schema:
            type: string
            example: ''
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - fileType
                - fileSize
              properties:
                file:
                  type: string
                  format: binary
                  description: The .caljob archive file to import
                fileType:
                  type: string
                  description: Export type of the archive
                  enum:
                    - CALJOB_BASE
                    - CALJOB_WITH_RIP
                    - CALJOB_WITH_SRC
                    - CALJOB_WITH_RIP_AND_SRC
                  example: CALJOB_BASE
                fileSize:
                  type: integer
                  description: Size of the archive file in bytes
                  example: 204800
      responses:
        '200':
          description: Job successfully imported
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobId:
                    type: integer
                    description: Internal job ID assigned by the RIP
                    example: 13552
        '400':
          description: Bad request — missing or invalid fields (file, fileType, fileSize)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Device not found or print server unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Remote RIP server failed to import the job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      deprecated: false
components:
  schemas:
    Service:
      title: Service
      allOf:
        - type: object
          properties:
            id:
              type: string
              example: 'MTI3LjAuMC4xOjQ1MzQzfmNhbGRlcmFyaXA'
            type:
              $ref: '#/components/schemas/ServiceType'
            version:
              description: 'Service version, in [SemVer](https://semver.org/) format.'
              type: string
              example: 3.19.0-beta.2+2022-02-24
            name:
              type: string
              example: Caldera RIP v15.1 build 220109
            host:
              type: string
              example: 127.0.0.1
            port:
              type: number
              example: 45344
          required:
            - id
            - type
            - version
            - name
        - $ref: '#/components/schemas/State'
    ServiceType:
      type: string
      title: Service type
      enum:
        - primecenter
        - calderarip
        - caldera_rest_api
      description: ''
      example: calderarip
    Device:
      title: Device
      type: object
      description: 'Device'
      allOf:
        - oneOf:
          - $ref: '#/components/schemas/Printer'
        - $ref: '#/components/schemas/State'
    DeviceType:
      type: string
      title: Device type
      description: Any kind of element that can be controlled by Caldera
      enum:
        - Cutter
        - Printer
      example: Printer
    Printer:
      title: Printer
      description: 'Printer device'
      type: object
      properties:
        id:
          type: string
          example: 'MTI3LjAuMC4xOjQ1MzQzfmNhbGRlcmFyaXB-SFBfTGF0ZXgtODAwVw'
        idents:
          type: object
          properties:
            internal:
              description: ID used internally by the service the device comes from.
              type: string
              example: 'HP_Latex-800W'
            service:
              description: ID of the service where the device currently sits.
              type: string
              example: 'MTI3LjAuMC4xOjQ1MzQzfmNhbGRlcmFyaXA'
        name:
          type: string
          example: Latex800W for billboard
        type:
          $ref: '#/components/schemas/DeviceType'
        model:
          type: string
          example: Hp-Latex-800W
        version:
          type: string
          example: '1.5'
      required:
        - id
        - name
        - type
        - model
        - version
    Job:
      title: Job
      description: Job is an element that needs _fulfillement_ by any active element
      type: object
      properties:
        id:
          type: string
          example: 'bG9jYWxob3N0OjQ1MzQzfmNhbGRlcmFyaXB-Q2FsZGVyYUpldH4xMzU1Mg'
        idents:
          type: object
          properties:
            internal:
              type: string
              description: ID used internally by the service the job comes from.
              example: '13552'
            service:
              type: string
              description: ID of the service where the job currently sits.
              example: 'bG9jYWxob3N0OjQ1MzQzfmNhbGRlcmFyaXA'
            device:
              type: string
              description: ID of the related device.
              example: 'bG9jYWxob3N0OjQ1MzQzfmNhbGRlcmFyaXB-Q2FsZGVyYUpldA'
        name:
          type: string
          example: 'Print::Customer A::#2453dr3. A beautiful print 4x1m'
        state:
          type: string
          enum:
            - pending
            - blocked
            - running
            - finished
            - aborting
            - aborted
            - error
          example: running
        type:
          type: string
          enum:
            - print
            - rip
            - cut
            - measurement
            - prepress
          example: print
        form:
          oneOf:
            - $ref: '#/components/schemas/JobPrint'
      required:
        - id
        - idents
        - name
        - state
        - type
    JobPrint:
      title: Job Print or Rip
      description: Job specifics information
      type: object
      properties:
        journal:
          type: array
          items:
            type: object
            properties:
              when:
                type: string
                description: 'Event date and time, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.'
                example: '2023-01-15T10:35:45'
              where:
                type: string
                enum:
                  - user
                  - software
                  - device
                example: device
              what:
                type: string
                enum:
                  - print
                  - printed
                  - cancel
                  - cancelled
                  - abort
                  - aborted
                  - waiting
                  - error
                example: print
              more:
                type: object
                properties:
                  key:
                    type: string
                  value:
                    type: string
        copies:
          type: object
          properties:
            total:
              type: number
              example: 3
            completed:
              type: number
              description: Number of copies completed
              example: 1
        thumbnail:
          type: string
          description: URL for thumbnail of this job
        origin:
          type: object
          properties:
            input:
              type: array
              items:
                type: object
                properties:
                  file:
                    type: string
                    description: Filename of the input file
                    example: Design_34244_4m_HQ.pdf
                  printSizeWidth:
                    type: number
                    description: The size width for a file included in a job in mm.
                    example: 20.30
                  printSizeHeight:
                    type: number
                    description: The size height for a file included in a job in mm.
                    example: 300.40
                  printScaleWidth:
                    type: number
                    description: The scale width for a file included in a job in percent. This value can be rounded and may be different from the original service.
                    example: 50
                  printScaleHeight:
                    type: number
                    description: The scale height for a file included in a job in percent. This value can be rounded and may be different from the original service.
                    example: 66.66
        settings:
          type: object
          properties:
            mode:
              type: string
              example: CMYKcm
            resolution:
              type: string
              example: 320x750
            quality:
              type: string
              example: 2 pass - HQ - Bi-dir - Sepcial customer John Doe
            media:
              type: string
              example: 3M Special 345gm Varnish application
        evolution:
          description: Key moments of the job
          type: object
          properties:
            progress:
              type: number
              description: Progress of the operation in percent.
              example: 70
            creation:
              type: string
              description: 'Creation date and time, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.'
              example: '2023-01-15T10:35:45'
            started:
              type: string
              description: 'Print start date and time, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.'
              example: '2023-01-15T10:35:45'
            finished:
              type: string
              description: 'Finish date and time, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.'
              example: '2023-01-15T10:35:45'
        message:
          type: string
          description: Message regarding the job can be general information or help for proceed with the job
          example: Press <Action> then <Initiate> on the printer panel
        context:
          type: object
          description: Data about customer, sales, order id, ... (~ metadata)
          properties:
            key:
              type: string
            value:
              type: string
    JobPrintSubmission:
      type: object
      properties:
        image:
          type: string
          example: 'MTI3LjAuMC4xOjQ1MzQzfmNhbGRlcmFyaXB-aW1nLjEyMzQ1Ng'
          description: The file id we want to submit to the device, as returned by the route "POST /services/{service}/images".
        preset:
          type: string
          description: The preset id, as returned by the route GET /devices/{device}/presets.
          example: 'MTI3LjAuMC4xOjQ1MzQzfmNhbGRlcmFyaXB-Q2FsZGVyYUpldH5bY2FsZGVyYVVzZXJdcHJlc2V0LWZvci1wb3N0ZXJz'
        persistJobInRIP:
          type: boolean
          description: Defines if the job persisted in the spooler of the RIP. Can be omitted, in which case the job is not persisted (like 'true' value).
          example: true
      required:
        - image
        - preset
    Preset:
      type: object
      properties:
        id:
          type: string
          example: 'MTI3LjAuMC4xOjQ1MzQzfmNhbGRlcmFyaXB-Q2FsZGVyYUpldH5bY2FsZGVyYV1DTVlLXzEyMDB4ODAwcHhfOHBhc3M'
          description: The identifier of a preset, unique for this device.
        idents:
          type: object
          properties:
            internal:
              type: string
              description: ID used internally by the service the preset comes from.
              example: '[caldera]CMYK_1200x800px_8pass'
            service:
              type: string
              description: ID of the service where the preset currently sits.
              example: 'MTI3LjAuMC4xOjQ1MzQzfmNhbGRlcmFyaXA'
            device:
              type: string
              description: ID of the related device.
              example: 'MTI3LjAuMC4xOjQ1MzQzfmNhbGRlcmFyaXB-Q2FsZGVyYUpldA'
        name:
          type: string
          example: 'CMYK 1200x800px 8pass'
        user:
          type: string
          example: 'caldera'
      required:
        - id
        - name
    State:
      title: State
      type: object
      properties:
        state:
          type: string
          enum:
            - unreachable
            - running
            - starting
            - aborting
            - stopping
            - sleeping
            - idling
        uptime:
          type: integer
          description: Number of seconds the service is up for.
          example: 812098
          readOnly: true
        current_time:
          description: 'Current service date and time, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.'
          type: string
          example: '2022-01-15T10:35:45'
      required:
        - state
    Problem:
      title: Problem
      description: |
        Error description following [RFC7807 - Problem Details for HTTP APIs](https://datatracker.ietf.org/doc/html/rfc7807).

        The messages should be localized based on the `Content-Language` HTTP header.
      type: object
      properties:
        type:
          description: URI reference that identifies the problem type.
          type: string
          default: 'about:blank'
          example: 'https://helpdesk.caldera.com/articles/err5257.html'
        title:
          description: 'Short, human-readable, summary of the problem type.'
          type: string
          example: Impossible to create the document within the range
        status:
          description: HTTP status code for this occurrence of the problem.
          type: number
          example: 400
        detail:
          description: Human-readable explanation specific to this occurrence of the problem.
          type: string
          example: 'Please provide a valid range. {troubleshooting: value=23 range=45-107}'
        instance:
          description: URI reference that identifies the specific occurrence of the problem.
          type: string
          example: /documents/dst3t459s
      required:
        - type
        - title
        - detail
    MachineInformation:
      title: Machine information
      description: Machine information fetched from the physical machine (if available). Some machine won't return relevant data (for example, most of offline printers).
      type: object
      oneOf:
        - $ref: '#/components/schemas/MachineInformationPrinter'
    MachineInformationPrinter:
      title: Machine information
      description: Machine information specific for printers
      type: object
      properties:
        state:
          type: string
          enum:
            - error
            - ready
            - busy
          example:
            ready
        loadedMedia:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                example: none
              type:
                type: string
                enum:
                  - roll
                  - sheet
              size:
                type: object
                properties:
                  unit:
                    type: string
                    enum:
                      - mm
                      - in
                  width:
                    type: number
                    example: 123
                  length:
                    type: number
                    description: Length of the loading. Will equal to -1 in the case of a roll
                    example: -1
        inkContainerSlots:
          type: number
          example: 8
        loadedInkContainers:
          type: array
          items:
            $ref: '#/components/schemas/MachineInformationPrinterInkBottle'
          example:
            [
              {colorName: CYAN, colorShortName: C, quantity: {"unit": "ml", "current": 0.2, "max": 42}},
              {colorName: MAGENTA, colorShortName: M, quantity: {"unit": "ml", "current": 1.36, "max": 3}},
              {colorName: YELLOW, colorShortName: Y, quantity: {"unit": "ml", "current": 1.01, "max": 3}},
              {colorName: BLACK, colorShortName: K, quantity: {"unit": "ml", "current": 2.5, "max": 5}}
            ]
        wasteInkContainers:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              quantity:
                type: object
                properties:
                  unit:
                    enum:
                      - "ml"
                      - "%"
                    example: "ml"
                  current:
                    type: number
                    example: 0.2
                  max:
                    type: number
                    example: 3
          example: [{"name": "WT1", quantity: {"unit": "%", "current": 50, "max": 100}}]
        heaters:
          type: array
          items:
            $ref: '#/components/schemas/MachineInformationPrinterHeater'
        warnings:
          type: array
          items:
            type: string
            example: "Error: please shake white cartridge"
        misc:
          type: array
          items:
            type: object
            additionalProperties: true
          example:
            [{Model: "CJV300-160Plus, Serial : CD1BE208"}]
    MachineInformationPrinterInkBottle:
      type: object
      properties:
        name:
          type: string
        quantity:
          type: object
          properties:
            unit:
              enum:
                - "ml"
                - "%"
              example: "ml"
            current:
              type: number
              example: 0.2
            max:
              type: number
              example: 3
    MachineInformationPrinterHeater:
      type: object
      properties:
        name:
          type: string
          example: Preheater
        temperature:
          type: object
          properties:
            current:
              type: number
              example: 34
            max:
              type: number
              example: 60
  parameters:
    Limit:
      in: query
      name: limit
      description: 'The maximum number of resources to retrieve in a page.'
      schema:
        type: integer
        minimum: 1
        default: 100
        example: 50
    Sort:
      in: query
      name: sort
      description: |
        Sort expression used to sort returned resources

        The sort expression uses the following syntax: `sort=<field1>:(asc|desc)[,<field2>:(asc|desc)...]`
      schema:
        type: string
        default: ''
        example: 'sort=name:asc,status:desc'
    Filter:
      in: query
      name: filter
      description: |
        Filter expression used to filter the returned resources

        The filter expression uses the following syntax:
        - Basic filtering: `<path-to-field1>=<value1>[&<path-to-field2>=<value2>...]`.
        For example, `GET /v1/devices?name=CalderaJet001&state=running` will return devices whose name **is** `CalderaJet001` and state **is** `running`.
        Note that the filter is applied case-insensitively on values, meaning that in the given example a running device whose name is `calderajet001` will also be returned.
        Rather than a simple property name, you can specify a path to a property using `.` as delimiter, eg. `GET /v1/jobs?idents.service=bG9jYWxob3N0OjEyMzQ3fmRhbW9uYQ`.
        - Advanced filtering: same as basic filtering with the possibility to use `*` as a wilcard for a value, and `|` to specify a union of possible values.
        For example, `GET /v1/devices?name=*Caldera*&state=running|stopping` will return the list of devices whose name **contains** the term `Caldera` and
        state **is either** `running` or `stopping`.
        You can combine these two operators in the same value, eg. `GET /v1/jobs?name=*ShowRoom*|*Reception*`.
      schema:
        type: object
        additionalProperties:
          type: string
        example:
          name: '*Office*|*ShowRoom*'
          state: 'running'
  headers:
    caldera-page:
      description: 'Current page offset (1-based offset)'
      schema:
        type: number
        minimum: 1
        example: 2
    caldera-limit:
      description: 'Maximum number of resources in a page, repeated from the `limit` query parameter'
      schema:
        type: number
        minimum: 1
        example: 50
    caldera-total-results:
      description: 'Total number of resources matching the query'
      schema:
        type: number
        minimum: 0
        example: 1192
    caldera-sort:
      description: Sort expression used to sort the returned resources, repeated from the `sort` query parameter
      schema:
        type: string
        example: 'sort=name:asc,status:desc'
    caldera-filter:
      description: Filter expression used to filter the returned resources, repeated from the query string
      schema:
        type: string
        example: 'name=*ShowRoom*|*Reception*&state=running'
    link:
      description: Links to the next and previous pages (if any), following [RFC 8288 format](https://httpwg.org/specs/rfc8288.html#header)
      schema:
        type: string
        example: '<http://localhost:12340/v1/jobs?page=3&limit=50>; rel="next", <http://localhost:12340/v1/jobs?page=1&limit=50>; rel="previous"'
  securitySchemes: {}
tags:
  - name: Services
  - name: Devices
  - name: Jobs
