openapi: 3.1.0
info:
  title: Xceptor Document Upload Authentication Workflows 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: Workflows
  description: Operations for creating, updating, listing, and deleting workflow definitions.
paths:
  /workflows:
    get:
      operationId: listWorkflows
      summary: Xceptor List Workflows
      description: Retrieves a paginated list of workflow definitions configured in the Xceptor platform. Workflows can be filtered by status, category, and name. Each workflow defines a multi-step data processing pipeline.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PageSizeParam'
      - name: status
        in: query
        description: Filter workflows by their activation status
        schema:
          type: string
          enum:
          - active
          - inactive
          - draft
      - name: category
        in: query
        description: Filter workflows by category
        schema:
          type: string
      - name: search
        in: query
        description: Search workflows by name or description
        schema:
          type: string
      responses:
        '200':
          description: A paginated list of workflows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createWorkflow
      summary: Xceptor Create Workflow
      description: Creates a new workflow definition in the Xceptor platform. A workflow defines a sequence of processing steps that are executed in order to transform, validate, enrich, and route data through the automation pipeline.
      tags:
      - Workflows
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowCreate'
      responses:
        '201':
          description: Workflow created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /workflows/{workflowId}:
    get:
      operationId: getWorkflow
      summary: Xceptor Get Workflow Details
      description: Retrieves the full definition of a specific workflow, including its steps, trigger configuration, and associated metadata.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/WorkflowIdParam'
      responses:
        '200':
          description: Workflow details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateWorkflow
      summary: Xceptor Update Workflow
      description: Updates an existing workflow definition. Changes to active workflows take effect on subsequent runs. Running instances continue to use the previous version until completion.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/WorkflowIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowUpdate'
      responses:
        '200':
          description: Workflow updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          description: Invalid request body
          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'
    delete:
      operationId: deleteWorkflow
      summary: Xceptor Delete Workflow
      description: Deletes a workflow definition. Active workflows must be deactivated before deletion. Any running instances will complete before the workflow is removed.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/WorkflowIdParam'
      responses:
        '204':
          description: Workflow deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Workflow 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
    PageSizeParam:
      name: page_size
      in: query
      description: The number of items per page
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
  schemas:
    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
    WorkflowUpdate:
      type: object
      description: Request body for updating an existing workflow
      properties:
        name:
          type: string
          description: The display name of the workflow
          minLength: 1
          maxLength: 255
        description:
          type: string
          description: A detailed description of what the workflow does
          maxLength: 2000
        status:
          type: string
          description: The activation status of the workflow
          enum:
          - active
          - inactive
          - draft
        category:
          type: string
          description: The category or group for the workflow
        trigger_type:
          type: string
          description: How the workflow is triggered for execution
          enum:
          - manual
          - scheduled
          - event
          - api
        schedule:
          type: string
          description: Cron expression for scheduled workflows. Required when trigger_type is scheduled.
    Workflow:
      type: object
      description: A workflow definition that describes a multi-step data processing pipeline in the Xceptor platform.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the workflow
        name:
          type: string
          description: The display name of the workflow
        description:
          type: string
          description: A detailed description of what the workflow does
        status:
          type: string
          description: The activation status of the workflow
          enum:
          - active
          - inactive
          - draft
        category:
          type: string
          description: The category or group the workflow belongs to
        trigger_type:
          type: string
          description: How the workflow is triggered for execution
          enum:
          - manual
          - scheduled
          - event
          - api
        schedule:
          type: string
          description: The cron expression for scheduled workflows, applicable when trigger_type is scheduled
        steps:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowStep'
          description: The ordered list of processing steps in the workflow
        created_at:
          type: string
          format: date-time
          description: The date and time the workflow was created
        updated_at:
          type: string
          format: date-time
          description: The date and time the workflow was last updated
        created_by:
          type: string
          description: The identifier of the user who created the workflow
    WorkflowList:
      type: object
      description: A paginated list of workflows
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Workflow'
          description: The list of workflows for the current page
        pagination:
          $ref: '#/components/schemas/Pagination'
    WorkflowCreate:
      type: object
      description: Request body for creating a new workflow
      required:
      - name
      - trigger_type
      properties:
        name:
          type: string
          description: The display name of the workflow
          minLength: 1
          maxLength: 255
        description:
          type: string
          description: A detailed description of what the workflow does
          maxLength: 2000
        category:
          type: string
          description: The category or group for the workflow
        trigger_type:
          type: string
          description: How the workflow is triggered for execution
          enum:
          - manual
          - scheduled
          - event
          - api
        schedule:
          type: string
          description: Cron expression for scheduled workflows. Required when trigger_type is scheduled.
    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
    WorkflowStep:
      type: object
      description: A single processing step within a workflow. Steps are executed in sequence and each performs a specific data processing operation.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the step
        name:
          type: string
          description: The display name of the step
        type:
          type: string
          description: The type of processing operation the step performs
          enum:
          - extraction
          - transformation
          - validation
          - enrichment
          - routing
          - notification
          - export
          - custom
        position:
          type: integer
          description: The position of the step in the workflow sequence (0-based)
          minimum: 0
        configuration:
          type: object
          description: Type-specific configuration parameters for the step
          additionalProperties: true
        enabled:
          type: boolean
          description: Whether the step is enabled for execution
          default: 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