openapi: 3.1.0
info:
  title: Xceptor Document Upload Authentication Workflow Runs 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: Workflow Runs
  description: Operations for executing workflows, monitoring run status, and retrieving run history and output.
paths:
  /workflows/{workflowId}/runs:
    get:
      operationId: listWorkflowRuns
      summary: Xceptor List Workflow Runs
      description: Retrieves a paginated list of execution runs for a specific workflow. Each run represents a single execution of the workflow and includes status, timing, and output information.
      tags:
      - Workflow Runs
      parameters:
      - $ref: '#/components/parameters/WorkflowIdParam'
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PageSizeParam'
      - name: status
        in: query
        description: Filter runs by execution status
        schema:
          type: string
          enum:
          - pending
          - running
          - completed
          - failed
          - cancelled
      responses:
        '200':
          description: A paginated list of workflow runs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRunList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: executeWorkflow
      summary: Xceptor Execute Workflow
      description: Triggers an execution run of the specified workflow. The workflow is executed asynchronously and the run status can be monitored using the run details endpoint. Input parameters can be provided to configure the execution context.
      tags:
      - Workflow Runs
      parameters:
      - $ref: '#/components/parameters/WorkflowIdParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowRunCreate'
      responses:
        '201':
          description: Workflow run initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRun'
        '400':
          description: Invalid request body or workflow is not active
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /workflows/{workflowId}/runs/{runId}:
    get:
      operationId: getWorkflowRun
      summary: Xceptor Get Workflow Run Details
      description: Retrieves the details and current status of a specific workflow run, including step-level progress, timing information, any errors encountered, and output references.
      tags:
      - Workflow Runs
      parameters:
      - $ref: '#/components/parameters/WorkflowIdParam'
      - $ref: '#/components/parameters/RunIdParam'
      responses:
        '200':
          description: Workflow run details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRun'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Workflow or run not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: cancelWorkflowRun
      summary: Xceptor Cancel Workflow Run
      description: Cancels a pending or running workflow execution. The cancellation is asynchronous and the run status will transition to cancelled once all active steps have stopped processing.
      tags:
      - Workflow Runs
      parameters:
      - $ref: '#/components/parameters/WorkflowIdParam'
      - $ref: '#/components/parameters/RunIdParam'
      responses:
        '200':
          description: Workflow run cancellation initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRun'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Workflow or run not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    PageParam:
      name: page
      in: query
      description: The page number for pagination (1-based)
      schema:
        type: integer
        minimum: 1
        default: 1
    WorkflowIdParam:
      name: workflowId
      in: path
      required: true
      description: The unique identifier of the workflow
      schema:
        type: string
        format: uuid
    RunIdParam:
      name: runId
      in: path
      required: true
      description: The unique identifier of the workflow run
      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
  schemas:
    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
    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
    WorkflowRunList:
      type: object
      description: A paginated list of workflow runs
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowRun'
          description: The list of workflow runs for the current page
        pagination:
          $ref: '#/components/schemas/Pagination'
    StepResult:
      type: object
      description: The result of executing a single workflow step
      properties:
        step_id:
          type: string
          format: uuid
          description: The identifier of the workflow step
        step_name:
          type: string
          description: The name of the workflow step
        status:
          type: string
          description: The execution status of the step
          enum:
          - pending
          - running
          - completed
          - failed
          - skipped
        started_at:
          type: string
          format: date-time
          description: The date and time the step started
        completed_at:
          type: string
          format: date-time
          description: The date and time the step completed
        records_processed:
          type: integer
          description: The number of data records processed by the step
          minimum: 0
        records_failed:
          type: integer
          description: The number of records that failed processing
          minimum: 0
        error:
          $ref: '#/components/schemas/Error'
    WorkflowRun:
      type: object
      description: A single execution instance of a workflow. Tracks the progress and outcome of running a workflow's processing pipeline.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the run
        workflow_id:
          type: string
          format: uuid
          description: The identifier of the workflow that was executed
        status:
          type: string
          description: The current execution status of the run
          enum:
          - pending
          - running
          - completed
          - failed
          - cancelled
        triggered_by:
          type: string
          description: How this run was triggered
          enum:
          - manual
          - schedule
          - event
          - api
        started_at:
          type: string
          format: date-time
          description: The date and time the run started executing
        completed_at:
          type: string
          format: date-time
          description: The date and time the run completed
        duration_ms:
          type: integer
          description: The total run duration in milliseconds
          minimum: 0
        step_results:
          type: array
          items:
            $ref: '#/components/schemas/StepResult'
          description: The results of each step in the workflow run
        input_parameters:
          type: object
          description: The input parameters provided for this run
          additionalProperties: true
        error:
          $ref: '#/components/schemas/Error'
    WorkflowRunCreate:
      type: object
      description: Request body for triggering a workflow execution
      properties:
        parameters:
          type: object
          description: Input parameters for the workflow execution
          additionalProperties: true
  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