openapi: 3.1.0
info:
  title: Xerox Public Print API
  description: >-
    REST API for managing print jobs through the Xerox Public Print Service.
    Provides endpoints for job creation, status monitoring, site discovery,
    provider management, EULA handling, and print history management.
    All secure calls require xrxauth, user-email, and appid headers.
    If user-email is omitted the request is treated as an application request.
  version: 5.5.0
  contact:
    name: Xerox Developer Program
    url: https://www.xerox.com/en-us/about/developer-program
    email: xerox.global.developer.program@xerox.com
  termsOfService: https://www.xerox.com/en-us/about/legal
externalDocs:
  description: Xerox Public Print API Documentation
  url: https://publicprintapi.services.xerox.com/
servers:
  - url: https://publicprintapi.services.xerox.com/api/v1
    description: Xerox Public Print API Production Server
security:
  - xrxauth: []
tags:
  - name: Jobs
    description: Print job creation, management, and history operations
  - name: Sites
    description: Site discovery and management for print locations
  - name: Providers
    description: Provider management operations
  - name: EULA
    description: End-user license agreement management
  - name: Provider Types
    description: Provider type listing and management
  - name: Status
    description: Health and status monitoring
paths:
  /Job:
    put:
      operationId: createJob
      summary: Create Print Job
      description: >-
        Creates a new print job in the Xerox Public Print Service.
        Returns Resource-Id, Details-Uri, and Status-Uri response headers.
      tags:
        - Jobs
      security:
        - xrxauth: []
          userEmail: []
          appId: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJobRequest'
      responses:
        '201':
          description: Job created successfully
          headers:
            Resource-Id:
              description: The ID of the newly created job
              schema:
                type: string
            Details-Uri:
              description: URI to retrieve job details
              schema:
                type: string
            Status-Uri:
              description: URI to retrieve job status
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          description: Bad request - missing required headers or invalid input
    get:
      operationId: getJob
      summary: Get Print Job
      description: Retrieves the details of a specific print job by ID.
      tags:
        - Jobs
      security:
        - xrxauth: []
          userEmail: []
          appId: []
      parameters:
        - name: id
          in: query
          required: true
          description: The unique identifier of the job
          schema:
            type: string
      responses:
        '200':
          description: Job details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          description: Bad request
        '404':
          description: Job not found
  /Job/Status:
    get:
      operationId: getJobStatus
      summary: Get Job Status
      description: Retrieves the current status of a print job.
      tags:
        - Jobs
      security:
        - xrxauth: []
          userEmail: []
          appId: []
      parameters:
        - name: jobId
          in: query
          required: true
          description: The unique identifier of the job
          schema:
            type: string
      responses:
        '200':
          description: Job status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
        '400':
          description: Bad request
        '404':
          description: Job not found
    post:
      operationId: updateJobStatus
      summary: Update Job Status
      description: Updates the status of a print job.
      tags:
        - Jobs
      security:
        - xrxauth: []
          userEmail: []
          appId: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateJobStatusRequest'
      responses:
        '200':
          description: Job status updated successfully
        '400':
          description: Bad request
  /Job/History:
    get:
      operationId: getJobHistory
      summary: Get Job History
      description: >-
        Retrieves the print history for the current user with pagination support.
      tags:
        - Jobs
      security:
        - xrxauth: []
          userEmail: []
          appId: []
      parameters:
        - name: $skip
          in: query
          required: false
          description: Number of records to skip for pagination
          schema:
            type: integer
        - name: $take
          in: query
          required: false
          description: Number of records to return
          schema:
            type: integer
      responses:
        '200':
          description: Job history retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobHistoryResponse'
        '400':
          description: Bad request
    delete:
      operationId: clearJobHistory
      summary: Clear Job History
      description: Clears the print job history for the current user.
      tags:
        - Jobs
      security:
        - xrxauth: []
          userEmail: []
          appId: []
      responses:
        '204':
          description: Job history cleared successfully
        '400':
          description: Bad request
  /Job/Options:
    get:
      operationId: getJobOptions
      summary: Get Job Options
      description: Lists all supported job options for print job creation.
      tags:
        - Jobs
      security:
        - xrxauth: []
          userEmail: []
          appId: []
      responses:
        '200':
          description: Job options retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobOptionsResponse'
  /EULA:
    get:
      operationId: getEULA
      summary: Get Provider EULA
      description: Retrieves the end-user license agreement for a specific provider.
      tags:
        - EULA
      security:
        - xrxauth: []
          appId: []
      parameters:
        - name: providerId
          in: query
          required: true
          description: The unique identifier of the provider
          schema:
            type: string
      responses:
        '200':
          description: EULA retrieved successfully
          headers:
            Agree-Uri:
              description: URI for the user to agree to the EULA
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EULA'
        '404':
          description: Provider not found
    post:
      operationId: createOrUpdateEULA
      summary: Create or Update Provider EULA
      description: Creates or updates the end-user license agreement for a provider.
      tags:
        - EULA
      security:
        - xrxauth: []
          appId: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EULA'
      responses:
        '200':
          description: EULA created or updated successfully
        '400':
          description: Bad request
  /EULA/Agree:
    put:
      operationId: agreeToEULA
      summary: Agree To EULA
      description: Records user agreement to a provider's end-user license agreement.
      tags:
        - EULA
      security:
        - xrxauth: []
          userEmail: []
          appId: []
      parameters:
        - name: providerId
          in: query
          required: true
          description: The unique identifier of the provider
          schema:
            type: string
      responses:
        '200':
          description: EULA agreement recorded successfully
        '400':
          description: Bad request
  /ProviderTypes:
    get:
      operationId: listProviderTypes
      summary: List Provider Types
      description: Lists all supported provider types with pagination support.
      tags:
        - Provider Types
      security:
        - xrxauth: []
          appId: []
      parameters:
        - name: $skip
          in: query
          required: false
          description: Number of records to skip
          schema:
            type: integer
        - name: $take
          in: query
          required: false
          description: Number of records to return
          schema:
            type: integer
      responses:
        '200':
          description: Provider types retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderTypeListResponse'
    put:
      operationId: createProviderType
      summary: Create Provider Type
      description: Creates a new provider type in the system.
      tags:
        - Provider Types
      security:
        - xrxauth: []
          appId: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProviderType'
      responses:
        '201':
          description: Provider type created successfully
        '400':
          description: Bad request
  /Sites:
    get:
      operationId: getSite
      summary: Get Site
      description: Retrieves details of a specific print site.
      tags:
        - Sites
      security:
        - xrxauth: []
          appId: []
      parameters:
        - name: id
          in: query
          required: true
          description: The unique identifier of the site
          schema:
            type: string
        - name: filterDeleted
          in: query
          required: false
          description: Filter out deleted sites
          schema:
            type: boolean
      responses:
        '200':
          description: Site details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Site'
        '404':
          description: Site not found
    put:
      operationId: createSite
      summary: Create Site
      description: Creates a new print site.
      tags:
        - Sites
      security:
        - xrxauth: []
          appId: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Site'
      responses:
        '201':
          description: Site created successfully
        '400':
          description: Bad request
    post:
      operationId: updateSite
      summary: Update Site
      description: Updates an existing print site.
      tags:
        - Sites
      security:
        - xrxauth: []
          appId: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Site'
      responses:
        '200':
          description: Site updated successfully
        '400':
          description: Bad request
    delete:
      operationId: deleteSite
      summary: Delete Site
      description: Deletes a specified print site.
      tags:
        - Sites
      security:
        - xrxauth: []
          appId: []
      parameters:
        - name: id
          in: query
          required: true
          description: The unique identifier of the site to delete
          schema:
            type: string
      responses:
        '204':
          description: Site deleted successfully
        '404':
          description: Site not found
  /Sites/Search:
    get:
      operationId: searchSitesByLocation
      summary: Search Sites By Location
      description: Searches for print sites within a specified radius of a location.
      tags:
        - Sites
      security:
        - xrxauth: []
          appId: []
      parameters:
        - name: longitude
          in: query
          required: true
          description: Longitude of the center point
          schema:
            type: number
            format: double
        - name: latitude
          in: query
          required: true
          description: Latitude of the center point
          schema:
            type: number
            format: double
        - name: range
          in: query
          required: true
          description: Search radius in meters
          schema:
            type: number
      responses:
        '200':
          description: Sites found within range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiteListResponse'
  /Sites/SearchByName:
    get:
      operationId: searchSitesByName
      summary: Search Sites By Name
      description: Searches for print sites by name with pagination.
      tags:
        - Sites
      security:
        - xrxauth: []
          appId: []
      parameters:
        - name: name
          in: query
          required: true
          description: Site name to search for
          schema:
            type: string
        - name: $skip
          in: query
          required: false
          schema:
            type: integer
        - name: $take
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Matching sites retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiteListResponse'
  /Sites/SearchByRemoteId:
    get:
      operationId: searchSitesByRemoteId
      summary: Search Sites By Remote Id
      description: Searches for a site by its ID in a remote system.
      tags:
        - Sites
      security:
        - xrxauth: []
          appId: []
      parameters:
        - name: remoteId
          in: query
          required: true
          description: The remote system identifier
          schema:
            type: string
      responses:
        '200':
          description: Matching site retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Site'
  /Sites/Favorite:
    put:
      operationId: addFavoriteSite
      summary: Add Favorite Site
      description: Marks a site as a favorite for the current user.
      tags:
        - Sites
      security:
        - xrxauth: []
          userEmail: []
          appId: []
      parameters:
        - name: id
          in: query
          required: true
          description: The unique identifier of the site
          schema:
            type: string
      responses:
        '200':
          description: Site added to favorites
    delete:
      operationId: removeFavoriteSite
      summary: Remove Favorite Site
      description: Removes a site from the current user's favorites.
      tags:
        - Sites
      security:
        - xrxauth: []
          userEmail: []
          appId: []
      parameters:
        - name: id
          in: query
          required: true
          description: The unique identifier of the site
          schema:
            type: string
      responses:
        '204':
          description: Site removed from favorites
  /Sites/Favorites:
    get:
      operationId: listFavoriteSites
      summary: List Favorite Sites
      description: Lists all sites marked as favorites by the current user.
      tags:
        - Sites
      security:
        - xrxauth: []
          userEmail: []
          appId: []
      responses:
        '200':
          description: Favorite sites retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiteListResponse'
  /Sites/Sync:
    post:
      operationId: syncSites
      summary: Sync Sites
      description: Merges site data with the system.
      tags:
        - Sites
      security:
        - xrxauth: []
          appId: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncSitesRequest'
      responses:
        '200':
          description: Sites synced successfully
  /Sites/UpdateSites:
    get:
      operationId: updateSitesFromProvider
      summary: Update Sites From Provider
      description: Synchronizes sites from a provider into the system.
      tags:
        - Sites
      security:
        - xrxauth: []
          appId: []
      parameters:
        - name: providerId
          in: query
          required: true
          description: The unique identifier of the provider
          schema:
            type: string
      responses:
        '200':
          description: Sites updated from provider
  /Provider:
    put:
      operationId: createProvider
      summary: Create Provider
      description: Creates a new print provider.
      tags:
        - Providers
      security:
        - xrxauth: []
          appId: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Provider'
      responses:
        '201':
          description: Provider created successfully
        '400':
          description: Bad request
    post:
      operationId: updateProvider
      summary: Update Provider
      description: Updates an existing print provider.
      tags:
        - Providers
      security:
        - xrxauth: []
          appId: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Provider'
      responses:
        '200':
          description: Provider updated successfully
    get:
      operationId: getProvider
      summary: Get Provider
      description: Retrieves details of a specific print provider.
      tags:
        - Providers
      security:
        - xrxauth: []
          appId: []
      parameters:
        - name: id
          in: query
          required: true
          description: The unique identifier of the provider
          schema:
            type: string
      responses:
        '200':
          description: Provider details retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Provider'
        '404':
          description: Provider not found
  /Provider/Delete:
    delete:
      operationId: deleteProvider
      summary: Delete Provider
      description: Deletes a specific print provider.
      tags:
        - Providers
      security:
        - xrxauth: []
          appId: []
      parameters:
        - name: id
          in: query
          required: true
          description: The unique identifier of the provider to delete
          schema:
            type: string
      responses:
        '204':
          description: Provider deleted
        '404':
          description: Provider not found
  /Provider/Search:
    get:
      operationId: searchProviders
      summary: Search Providers
      description: Searches for providers with optional filtering.
      tags:
        - Providers
      security:
        - xrxauth: []
          appId: []
      parameters:
        - name: name
          in: query
          required: false
          description: Provider name to search for
          schema:
            type: string
        - name: $skip
          in: query
          required: false
          schema:
            type: integer
        - name: $take
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Matching providers retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderListResponse'
  /Status:
    get:
      operationId: getStatus
      summary: Get API Status
      description: Health check endpoint for monitoring the Xerox Public Print API status.
      tags:
        - Status
      responses:
        '200':
          description: API is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
components:
  securitySchemes:
    xrxauth:
      type: apiKey
      in: header
      name: xrxauth
      description: Xerox authentication credentials
    userEmail:
      type: apiKey
      in: header
      name: user-email
      description: User email address for user-context requests
    appId:
      type: apiKey
      in: header
      name: appid
      description: Application identifier
  schemas:
    CreateJobRequest:
      type: object
      description: Request body for creating a new print job
      properties:
        documentUrl:
          type: string
          description: URL of the document to print
        providerId:
          type: string
          description: ID of the print provider
        siteId:
          type: string
          description: ID of the print site
        options:
          type: object
          description: Print job options
          additionalProperties: true
      required:
        - documentUrl
    Job:
      type: object
      description: A print job
      properties:
        id:
          type: string
          description: Unique identifier of the job
        status:
          type: string
          description: Current status of the job
          enum:
            - Pending
            - Processing
            - Ready
            - Printed
            - Failed
            - Expired
        providerId:
          type: string
          description: ID of the print provider
        siteId:
          type: string
          description: ID of the print site
        createdAt:
          type: string
          format: date-time
          description: Job creation timestamp
        expiresAt:
          type: string
          format: date-time
          description: Job expiration timestamp
        options:
          type: object
          description: Print job options
          additionalProperties: true
    JobStatus:
      type: object
      description: Status of a print job
      properties:
        jobId:
          type: string
          description: ID of the job
        status:
          type: string
          description: Current status
          enum:
            - Pending
            - Processing
            - Ready
            - Printed
            - Failed
            - Expired
        message:
          type: string
          description: Status message
    UpdateJobStatusRequest:
      type: object
      description: Request to update job status
      properties:
        jobId:
          type: string
          description: ID of the job to update
        status:
          type: string
          description: New status value
      required:
        - jobId
        - status
    JobHistoryResponse:
      type: object
      description: Paginated list of job history
      properties:
        total:
          type: integer
          description: Total number of records
        items:
          type: array
          items:
            $ref: '#/components/schemas/Job'
    JobOptionsResponse:
      type: object
      description: Available print job options
      properties:
        options:
          type: array
          items:
            $ref: '#/components/schemas/JobOption'
    JobOption:
      type: object
      description: A supported print job option
      properties:
        name:
          type: string
          description: Option name
        type:
          type: string
          description: Option data type
        values:
          type: array
          items:
            type: string
          description: Allowed values for this option
    EULA:
      type: object
      description: End-user license agreement
      properties:
        providerId:
          type: string
          description: ID of the provider
        content:
          type: string
          description: EULA text content
        version:
          type: string
          description: Version of the EULA
        effectiveDate:
          type: string
          format: date
          description: Date EULA becomes effective
    ProviderType:
      type: object
      description: A type of print provider
      properties:
        id:
          type: string
          description: Unique identifier
        name:
          type: string
          description: Provider type name
        description:
          type: string
          description: Provider type description
    ProviderTypeListResponse:
      type: object
      description: Paginated list of provider types
      properties:
        total:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/ProviderType'
    Provider:
      type: object
      description: A print provider
      properties:
        id:
          type: string
          description: Unique identifier
        name:
          type: string
          description: Provider name
        typeId:
          type: string
          description: Provider type ID
        contactEmail:
          type: string
          description: Contact email for the provider
        websiteUrl:
          type: string
          description: Provider website URL
    ProviderListResponse:
      type: object
      description: Paginated list of providers
      properties:
        total:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/Provider'
    Site:
      type: object
      description: A print site (location with printers)
      properties:
        id:
          type: string
          description: Unique identifier
        name:
          type: string
          description: Site name
        providerId:
          type: string
          description: ID of the provider managing this site
        address:
          $ref: '#/components/schemas/Address'
        location:
          $ref: '#/components/schemas/GeoLocation'
        remoteId:
          type: string
          description: ID in the remote provider system
        isDeleted:
          type: boolean
          description: Whether the site has been deleted
    SiteListResponse:
      type: object
      description: List of sites
      properties:
        total:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/Site'
    SyncSitesRequest:
      type: object
      description: Request to sync site data
      properties:
        sites:
          type: array
          items:
            $ref: '#/components/schemas/Site'
    Address:
      type: object
      description: Physical address
      properties:
        street:
          type: string
        city:
          type: string
        state:
          type: string
        postalCode:
          type: string
        country:
          type: string
    GeoLocation:
      type: object
      description: Geographic coordinates
      properties:
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
    StatusResponse:
      type: object
      description: API health status
      properties:
        status:
          type: string
          description: Health status (OK, Degraded, etc.)
        timestamp:
          type: string
          format: date-time
          description: Time of status check