Reelables Print Jobs API

openapi: 3.2.0
info:
  title: Reelables Print Jobs API
  description: RESTful API for communicating with the Reelables Platform.
  contact:
    email: team@reelables.com
  version: 1.3.11
servers:
- url: https://api.reelables.com/{basePath}
  variables:
    basePath:
      default: v1
  description: The production URL for sending requests to the Reelables API.
security:
- AuthEndpoint:
  - https://auth.reelables.com/full-access
tags:
- name: Print Jobs
paths:
  /print-jobs/{printJobId}:
    get:
      tags:
      - Print Jobs
      summary: Get a Print Job
      parameters:
      - name: request-id
        in: header
        description: 'Unique identifier for the API request. Example: f7ecf495-ca1c-4468-a6c2-6ee3f723fa00'
        schema:
          type: string
      - name: printJobId
        in: path
        description: The identifier of the Print Job
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintJob'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Printer or Print Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - AuthEndpoint:
        - https://auth.reelables.com/full-access
      operationId: getPrintJobsByPrintJobId
      x-operation-id-source: derived
    delete:
      tags:
      - Print Jobs
      summary: Cancel a Print Job
      parameters:
      - name: request-id
        in: header
        description: 'Unique identifier for the API request. Example: f7ecf495-ca1c-4468-a6c2-6ee3f723fa00'
        schema:
          type: string
      - name: printJobId
        in: path
        description: The identifier of the Print Job
        required: true
        schema:
          type: string
      responses:
        '204':
          description: 204 response
          content: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Printer or Print Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - AuthEndpoint:
        - https://auth.reelables.com/full-access
      operationId: deletePrintJobsByPrintJobId
      x-operation-id-source: derived
  /printers/{printerId}/print-jobs:
    get:
      tags:
      - Print Jobs
      summary: Get Print Jobs for a Printer
      parameters:
      - name: request-id
        in: header
        description: 'Unique identifier for the API request. Example: f7ecf495-ca1c-4468-a6c2-6ee3f723fa00'
        schema:
          type: string
      - name: printerId
        in: path
        description: The identifier of the Printer
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: 'Number of items to return. Default: 10. Maximum: 10000'
        schema:
          type: string
      - name: nextToken
        in: query
        description: Pagination token to get next page of items
        schema:
          type: string
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintJobs'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Printer not found in workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - AuthEndpoint:
        - https://auth.reelables.com/full-access
      operationId: getPrintersByPrinterIdPrintJobs
      x-operation-id-source: derived
    post:
      tags:
      - Print Jobs
      summary: Send Print Jobs to a Printer
      parameters:
      - name: request-id
        in: header
        description: 'Unique identifier for the API request. Example: f7ecf495-ca1c-4468-a6c2-6ee3f723fa00'
        schema:
          type: string
      - name: printerId
        in: path
        description: The identifier of the Printer
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrintJobsInput'
        required: true
      responses:
        '201':
          description: 201 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintJobs'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Printer not found in workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - AuthEndpoint:
        - https://auth.reelables.com/full-access
      operationId: postPrintersByPrinterIdPrintJobs
      x-operation-id-source: derived
components:
  schemas:
    ErrorResponse:
      required:
      - errors
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                maxLength: 100
                pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/"]*$
                type: string
                description: An application-specific error code, expressed as a string value
              id:
                maxLength: 100
                pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/"]*$
                type: string
                description: A unique identifier for this particular occurrence of the problem
              detail:
                maxLength: 500
                pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/" ]*$
                type: string
                description: A human-readable explanation specific to this occurrence of the problem
              title:
                maxLength: 100
                pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/" ]*$
                type: string
                description: A short, human-readable summary of the problem
              status:
                maxLength: 3
                pattern: ^[0-9]*$
                type: string
                description: The HTTP status code applicable to this problem, expressed as a string value
            additionalProperties: false
      additionalProperties: false
      description: This is an error
    PrintJobsInput:
      required:
      - printJobs
      type: object
      properties:
        printJobs:
          type: array
          items:
            maxItems: 1000
            required:
            - assetId
            type: object
            properties:
              assetId:
                maxLength: 20
                pattern: ^[-_A-Za-z0-9]*$
                type: string
                description: 'Unique identifier of the Asset. Example: ''00Es43YBJfNRXNSvLmni'''
              replaceExistingLabel:
                type: boolean
                description: Indicate whether to replace the existing Label, in the case where the Asset is already linked to a Label
              templateParams:
                type: object
                additionalProperties: true
                description: Dynamic object that is used to pass any params for the Print Template
              templateId:
                maxLength: 36
                type: string
                description: The indentifier of the Print Template
            additionalProperties: false
      additionalProperties: false
      description: Print Jobs to send to Printer
    PrintJobs:
      required:
      - items
      type: object
      properties:
        nextToken:
          maxLength: 5000
          pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/"]*$
          type: string
          description: Pagination token
        items:
          type: array
          items:
            $ref: '#/components/schemas/PrintJob'
      additionalProperties: false
    PrintJob:
      required:
      - assetId
      - createdAt
      - id
      - origin
      - printerId
      - status
      - workspaceId
      type: object
      properties:
        origin:
          maxLength: 100
          pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/" ]*$
          type: string
          description: The origin of the Print Job (e.g. Remote or Local Barcode)
        replaceExistingLabel:
          type: boolean
          description: Indicate whether to replace the existing Label, in the case where the Asset is already linked to a Label
        includeCutLine:
          type: boolean
          description: Indicates whether the Print Job has a cut line (where to cut a label to de-activate) included
        templateId:
          maxLength: 36
          type: string
          description: The indentifier of the Print Template
        createdAt:
          maxLength: 20
          pattern: ^[0-9TZ:-]*$
          type: string
          description: 'Date that the item was created, in UTC. Example: ''2019-07-21T17:32:28Z'''
          format: date-time
        isSuccessful:
          type: boolean
          description: Indicates whether the Print Job was successful
        assetId:
          maxLength: 20
          pattern: ^[-_A-Za-z0-9]*$
          type: string
          description: 'Unique identifier of the Asset. Example: ''00Es43YBJfNRXNSvLmni'''
        failureReason:
          maxLength: 100
          pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/" ]*$
          type: string
          description: Describes the failure if the Print Job was unsuccessful
        printerId:
          maxLength: 50
          pattern: ^[-_A-Za-z0-9]*$
          type: string
          description: 'Printer identifier - the serial number of the Printer. Example: ''abcdefgh123456789'''
        id:
          maxLength: 36
          pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
          type: string
          description: 'Unique identifier of the Print Job. Example: ''d290f1ee-6c54-4b01-90e6-d701748f0851'''
          format: uuid
        workspaceId:
          maxLength: 36
          pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
          type: string
          description: 'Unique identifier of the workspace. Example: ''d290f1ee-6c54-4b01-90e6-d701748f0851'''
          format: uuid
        updatedAt:
          maxLength: 20
          pattern: ^[0-9TZ:-]*$
          type: string
          description: 'Date that the item was last updated, in UTC. Example: ''2019-07-21T17:32:28Z'''
          format: date-time
        status:
          maxLength: 100
          pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/" ]*$
          type: string
          description: The status of the Print Job
        isComplete:
          type: boolean
          description: Indicates whether the Print Job is complete
      additionalProperties: false
  securitySchemes:
    AuthEndpoint:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.reelables.com/oauth2/token
          scopes:
            https://auth.reelables.com/full-access: Full access to the Public API
x-topics:
- title: Getting started
  content: Before using the Reelables API, you require a `CLIENT_ID` and `CLIENT_SECRET` to authenticate your requests. You can obtain these by contacting [Reelables Support](mailto:support@reelables.com)
- title: Authentication
  content: 'Our authentication is based on the Client Credentials flow of the OAuth 2.0 authentication framework ([Client Credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.4)).


    You need to retrieve an access token (`ACCESS_TOKEN`) from our authentication endpoint to then send in the header (`"Authorization: Bearer ACCESS_TOKEN"`) of subsequent requests.


    **To obtain an `ACCESS_TOKEN`, send a POST request to https://auth.reelables.com/oauth2/token?grant_type=client_credentials with headers:**

    - `"Content-Type": "application/x-www-form-urlencoded"`

    - `"Authorization": "Basic base64(CLIENT_ID>:<CLIENT_SECRET>)"`

    where base64() is the base64-encoded representation of the `<CLIENT_ID>:<CLIENT_SECRET>` combination.


    **Using the `ACCESS_TOKEN` in requests:**

    - add an `Authorization` header to your request including the `ACCESS_TOKEN` as the value: `"Authorization: Bearer ACCESS_TOKEN"`

    - the `ACCESS_TOKEN` is valid for 1 hour. Once it has expired, re-authenticate to obtain a fresh `ACCESS_TOKEN`

    '
  example: '_Example Authentication request_

    ```curl --request POST --url ''https://auth.reelables.com/oauth2/token?grant_type=client_credentials'' --user CLIENT_ID:CLIENT_SECRET --header ''Content-Type: application/x-www-form-urlencoded''```

    - Note: using the curl --user option adds an `Authorization` header with value `Basic Base64(CLIENT_ID:CLIENT_SECRET)`'
- title: Errors
  content: 'The API uses standard HTTP response codes to indicate the success or failure of requests. Statuses in the `2xx` range indicate success; statuses in the `4xx` and `5xx` ranges indicate errors. The format of error messages is unified, and can be distinguished by their `status` key. The `title` and `detail` are plain English explanations of the problem.

    '
  example: "```json\n{\n  \"status\": \"status_code\",\n  \"id\": \"A unique identifier for this particular occurrence of the problem.\",\n  \"title\": \"A short, human-readable summary of the problem.\",\n  \"detail\": \"A human-readable explanation specific to this occurrence of the problem.\",\n}\n```\n"
- title: Versioning and backwards compatibility
  content: 'The API is versioned by path (`/v1/...`). When we introduce breaking changes, we will increase this version number. We will of course continually make backward-compatible changes without increasing the version number.


    Examples of things we do **not** consider breaking include:

    * Adding new API resources.

    * Adding new optional request parameters to existing API methods.

    * Adding new properties to existing API responses. We will occasionally move response fields in the API, and will continue to return the existing field in its previous location, while removing it from this documentation.

    * Changing the order of properties in existing API responses.

    * Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings. Strings that are marked as const or enum in this documentation will not change.

    '
- title: Rate limiting
  content: 'We enforce a rate limit on how many HTTP requests can be made in a given period. When the limit is reached, the API will return an error `429 Too Many Requests`.

    '
- title: Data Entities
  content: 'The core entities in the Reelables API are:

    - **`Workspace`**: a permissions boundary within the Reelables Platform.

    Typically this is an organization or team but it can also represent an application across several organizations, for example when multiple parties have visibility of `Assets` through a supply chain.


    `Assets`, `Spaces`, `Printers`, `Consignments` and `Facilities` all exist within the context of a `Workspace`. `Users` can have permissions in more than one `Workspace`.

    - **`Asset`**: a physical item that can be tracked. Reelables `Labels` are activated (typically by a `Printer`) and attached to `Assets`.

    - **`Space`**: a physical area within which `Assets` can be detected. A `Space` can be static (e.g. a receiving bay in a `Facility`) or mobile (e.g. in the trailer of a truck). A `Space` is characterized in the real world by a `Gateway`, a physical device that listens for signals from Reelables `Labels`.

    - **`Consignment`**: A collection of pieces that are being tracked. In the context of a `Consignment` a piece is an `Asset`.

    - **`Facility`**: A physical location, comprised of one or more `Spaces` where `Assets` are stored or transit through. E.g. a warehouse or distribution center.

    - **`Label`**: A Reelables smart label that produces signals that are detected by a `Gateway`.

    - **`Gateway`**: A device that listens for signals from `Labels`.

    - **`Printer`**: a physcial device that enables customers to use Reelables `Labels` at scale. `Printers` are linked to a `Workspace` and are used to print `Labels` for `Assets`.

    - **`User`**: can be a part of one or more `Workspaces`, their permissions within those `Workspaces` are role-based.'