Xceptor Jobs API

openapi: 3.1.0
info:
  title: Xceptor Document Upload Authentication Jobs API
  description: API for uploading and processing documents through Xceptor's data extraction engine. Supports intelligent document processing using NLP, OCR, and generative AI to transform unstructured documents including PDFs, emails, spreadsheets, and handwritten forms into structured, trusted data. The API handles document ingestion, classification, field and table extraction, and confidence-scored output for financial services use cases such as trade confirmations, tax documents, loan notices, and client onboarding materials.
  version: '1.0'
  contact:
    name: Xceptor API Support
    url: https://www.xceptor.com/support
    email: api-support@xceptor.com
  termsOfService: https://www.xceptor.com/legal-tcs
servers:
- url: https://api.xceptor.com/v1
  description: Production Server
security:
- bearerAuth: []
tags:
- name: Jobs
  description: Operations for creating, monitoring, and managing data processing jobs that execute within the Xceptor platform.
paths:
  /jobs:
    get:
      operationId: listJobs
      summary: Xceptor List Processing Jobs
      description: Retrieves a paginated list of data processing jobs. Jobs represent units of work executed on the Xceptor platform, such as document ingestion, data extraction, transformation, or export operations. Results can be filtered by status, type, and date range.
      tags:
      - Jobs
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PageSizeParam'
      - name: status
        in: query
        description: Filter jobs by processing status
        schema:
          type: string
          enum:
          - pending
          - running
          - completed
          - failed
          - cancelled
      - name: type
        in: query
        description: Filter jobs by processing type
        schema:
          type: string
          enum:
          - ingestion
          - extraction
          - transformation
          - export
          - workflow
      - name: created_after
        in: query
        description: Filter jobs created after this date-time
        schema:
          type: string
          format: date-time
      - name: created_before
        in: query
        description: Filter jobs created before this date-time
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: A paginated list of jobs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createJob
      summary: Xceptor Create Processing Job
      description: Creates a new data processing job on the Xceptor platform. The job type determines the processing pipeline that will be executed. Jobs are processed asynchronously and their status can be monitored using the job status endpoint.
      tags:
      - Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobCreate'
      responses:
        '201':
          description: Job created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /jobs/{jobId}:
    get:
      operationId: getJob
      summary: Xceptor Get Job Details
      description: Retrieves the details and current status of a specific processing job, including progress information, any errors encountered, and links to output data when the job has completed.
      tags:
      - Jobs
      parameters:
      - $ref: '#/components/parameters/JobIdParam'
      responses:
        '200':
          description: Job details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: cancelJob
      summary: Xceptor Cancel Processing Job
      description: Cancels a pending or running processing job. Completed or already cancelled jobs cannot be cancelled. Cancellation is asynchronous and the job status will transition to cancelled once processing has stopped.
      tags:
      - Jobs
      parameters:
      - $ref: '#/components/parameters/JobIdParam'
      responses:
        '200':
          description: Job cancellation initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Job:
      type: object
      description: A data processing job that executes on the Xceptor platform. Jobs represent units of work such as document ingestion, data extraction, transformation, or export operations.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the job
        type:
          type: string
          description: The type of processing job
          enum:
          - ingestion
          - extraction
          - transformation
          - export
          - workflow
        status:
          type: string
          description: The current processing status of the job
          enum:
          - pending
          - running
          - completed
          - failed
          - cancelled
        progress:
          type: integer
          description: The processing progress as a percentage (0-100)
          minimum: 0
          maximum: 100
        created_at:
          type: string
          format: date-time
          description: The date and time the job was created
        updated_at:
          type: string
          format: date-time
          description: The date and time the job was last updated
        completed_at:
          type: string
          format: date-time
          description: The date and time the job completed processing
        error:
          $ref: '#/components/schemas/Error'
        metadata:
          type: object
          description: Additional metadata associated with the job
          additionalProperties: true
    JobCreate:
      type: object
      description: Request body for creating a new processing job
      required:
      - type
      properties:
        type:
          type: string
          description: The type of processing job to create
          enum:
          - ingestion
          - extraction
          - transformation
          - export
          - workflow
        workflow_id:
          type: string
          format: uuid
          description: The identifier of the workflow to execute, required when type is workflow
        datasource_id:
          type: string
          format: uuid
          description: The identifier of the data source to process from
        parameters:
          type: object
          description: Job-specific configuration parameters
          additionalProperties: true
        metadata:
          type: object
          description: Additional metadata to associate with the job
          additionalProperties: true
    Error:
      type: object
      description: An error response from the Xceptor API
      properties:
        code:
          type: string
          description: A machine-readable error code
        message:
          type: string
          description: A human-readable description of the error
        details:
          type: object
          description: Additional error details when available
          additionalProperties: true
    JobList:
      type: object
      description: A paginated list of processing jobs
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Job'
          description: The list of jobs for the current page
        pagination:
          $ref: '#/components/schemas/Pagination'
    Pagination:
      type: object
      description: Pagination information for list responses
      properties:
        page:
          type: integer
          description: The current page number
        page_size:
          type: integer
          description: The number of items per page
        total_items:
          type: integer
          description: The total number of items across all pages
        total_pages:
          type: integer
          description: The total number of pages
  parameters:
    PageParam:
      name: page
      in: query
      description: The page number for pagination (1-based)
      schema:
        type: integer
        minimum: 1
        default: 1
    JobIdParam:
      name: jobId
      in: path
      required: true
      description: The unique identifier of the processing job
      schema:
        type: string
        format: uuid
    PageSizeParam:
      name: page_size
      in: query
      description: The number of items per page
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth2 access token obtained via the client credentials flow. Include as a Bearer token in the Authorization header.
externalDocs:
  description: Xceptor Document Upload API Documentation
  url: https://docs.xceptor.com/api/documents