openapi: 3.1.0
info:
  title: Ataccama ONE Agentic Public API - Processing
  version: 1.0.0
  license:
    name: ATACCAMA PROPRIETARY/CONFIDENTIAL
    url: https://www.ataccama.com
servers:
  - url: https://server1.com/api
security:
  - JWT: []
paths:
  /processing/v1/workflows:
    get:
      description: Get list of processing workflows
      summary: List workflows
      operationId: ListWorkflows
      tags:
        - Workflows
      parameters:
        - in: query
          name: after
          description: Cursor for fetching the next page of results (forward pagination)
          schema:
            type: string
        - in: query
          name: before
          description: Cursor for fetching the previous page of results (backward pagination)
          schema:
            type: string
        - in: query
          name: size
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - in: query
          name: status
          description: Filter by workflow status
          schema:
            type: string
        - in: query
          name: type
          description: Filter by workflow type
          schema:
            type: string
        - in: query
          name: name
          description: Filter by workflow name
          schema:
            type: string
        - in: query
          name: sort
          description: Comma-separated field names (e.g., "sort=status,-finishedAt"), where fields prefixed with "-" sort descending
          schema:
            type: string
            default: -startedAt
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/CursorPaginationMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProcessingWorkflow'
                required:
                  - meta
                  - data
        '403':
          $ref: '#/components/responses/Forbidden'
  /processing/v1/workflows/{workflowUrn}:
    get:
      description: Get processing workflow by urn
      summary: Get workflow
      operationId: GetWorkflow
      tags:
        - Workflows
      parameters:
        - name: workflowUrn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ProcessingWorkflowUrn'
      responses:
        '200':
          description: OK
          headers:
            Retry-After:
              schema:
                type: integer
              description: |
                Number of seconds to wait before retrying the request. This header is returned until the processing  
                workflow reaches a terminal state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingWorkflow'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /processing/v1/workflows/cancel:
    post:
      description: Cancel processing workflow by urn
      summary: Cancel workflow
      operationId: CancelWorkflow
      tags:
        - Workflows
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - workflows
              properties:
                workflows:
                  type: array
                  items:
                    $ref: '#/components/schemas/ProcessingWorkflowUrn'
                  description: List of workflow urn
              example:
                workflows:
                  - urn:ata:acme-corp:processing:workflow:123e4567-e89b-12d3-a456-426614174000
                  - urn:ata:acme-corp:processing:workflow:db41cc48-47b3-3707-8eac-e471885f9315
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingWorkflowCancellation'
        '403':
          $ref: '#/components/responses/Forbidden'
  /processing/v1/jobs:
    get:
      description: Get list of processing jobs
      summary: List of workflow jobs
      operationId: ListJobs
      tags:
        - Jobs
      parameters:
        - in: query
          name: after
          description: Cursor for fetching the next page of results (forward pagination)
          schema:
            type: string
        - in: query
          name: before
          description: Cursor for fetching the previous page of results (backward pagination)
          schema:
            type: string
        - in: query
          name: size
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - in: query
          name: workflow
          description: Filter by workflow
          schema:
            $ref: '#/components/schemas/ProcessingWorkflowUrn'
        - in: query
          name: type
          description: Filter by job type
          schema:
            type: string
        - in: query
          name: status
          description: Filter by job status
          schema:
            type: string
        - in: query
          name: name
          description: Filter by job name
          schema:
            type: string
        - in: query
          name: sort
          description: Comma-separated field names (e.g., "sort=status,-finishedAt"), where fields prefixed with "-" sort descending
          schema:
            type: string
            default: -submittedAt
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/CursorPaginationMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProcessingJob'
                required:
                  - meta
                  - data
        '403':
          $ref: '#/components/responses/Forbidden'
  /processing/v1/jobs/{jobUrn}:
    get:
      description: Get a processing job
      summary: Get a processing job description
      operationId: GetJob
      tags:
        - Jobs
      parameters:
        - name: jobUrn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ProcessingJobUrn'
      responses:
        '200':
          description: OK
          headers:
            Retry-After:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingJob'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    CursorPaginationMetadata:
      type: object
      description: Pagination metadata for cursor-based pagination
      properties:
        prev:
          type:
            - string
            - 'null'
          description: Cursor for previous page. Use with 'before' query parameter. Null on first page.
        next:
          type:
            - string
            - 'null'
          description: Cursor for next page. Use with 'after' query parameter. Null on last page.
        total:
          type: integer
          description: Optional total count of items.
      required:
        - prev
        - next
    ProcessingWorkflowUrn:
      type: string
      format: uri
      pattern: ^urn:ata:[a-z0-9][a-z0-9\-]{0,62}:processing:workflow:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      description: |
        A URN identifying a Processing Workflow.

        Format: urn:ata:{tenant}:processing:workflow:{uuid}

        Example: urn:ata:acme-corp:processing:workflow:123e4567-e89b-12d3-a456-426614174000
      example: urn:ata:acme-corp:processing:workflow:123e4567-e89b-12d3-a456-426614174000
    ProcessingJobUrn:
      type: string
      format: uri
      pattern: ^urn:ata:[a-z0-9][a-z0-9\-]{0,62}:processing:job:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      description: |
        A URN identifying a Processing Job.

        Format: urn:ata:{tenant}:processing:job:{uuid}

        Example: urn:ata:acme-corp:processing:job:123e4567-e89b-12d3-a456-426614174000
      example: urn:ata:acme-corp:processing:job:123e4567-e89b-12d3-a456-426614174000
    ProcessingWorkflow:
      type: object
      properties:
        urn:
          $ref: '#/components/schemas/ProcessingWorkflowUrn'
        type:
          type: string
        name:
          type: string
        owner:
          type: string
        startedAt:
          type: string
          format: date-time
        finishedAt:
          type: string
          format: date-time
        duration:
          type: integer
        status:
          type: string
          examples:
            - PENDING
            - RUNNING
            - FINISHED
            - FAILED
            - CANCELED
            - SKIPPED
          description: '@ExtensibleEnum The current status of the processing workflow'
        errors:
          type: array
          items:
            type: object
            properties:
              job:
                $ref: '#/components/schemas/ProcessingJobUrn'
              reason:
                type: string
            required:
              - job
              - reason
      required:
        - urn
        - status
        - type
        - startedAt
    ProblemDetail:
      type: object
      properties:
        type:
          type: string
          description: Error type identifier
          example: RESOURCE_NOT_FOUND
        title:
          type: string
          description: Short, human-readable summary of the problem type
          example: Resource Not Found
        detail:
          type: string
          description: Detailed specific explanation of the problem
          example: Table 'urn:ata:acme:reference-data:table:01924b84-6f7e-7c0c-8f9d-3a2b4c5d6e7f' was not found
      required:
        - type
        - title
        - detail
    ProcessingWorkflowCancellation:
      type: object
      properties:
        workflows:
          type: array
          items:
            type: object
            properties:
              urn:
                $ref: '#/components/schemas/ProcessingWorkflowUrn'
              cancelled:
                type: boolean
    ProcessingJob:
      type: object
      properties:
        urn:
          $ref: '#/components/schemas/ProcessingJobUrn'
        type:
          type: string
        name:
          type: string
        submittedAt:
          type: string
          format: date-time
        startedAt:
          type: string
          format: date-time
        finishedAt:
          type: string
          format: date-time
        duration:
          type: integer
        status:
          type: string
          examples:
            - PENDING
            - RUNNING
            - FINISHED
            - FAILED
            - CANCELED
            - SKIPPED
          description: '@ExtensibleEnum The current status of the processing job'
        error:
          type: object
          properties:
            reason:
              type: string
      required:
        - urn
        - status
        - type
        - submittedAt
  responses:
    Forbidden:
      description: Forbidden - insufficient permissions to access the requested resource
      content:
        application/problem+json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ProblemDetail'
              - type: object
                properties:
                  type:
                    type: string
                    const: FORBIDDEN
                    description: Error type identifier for forbidden access
                  title:
                    type: string
                    const: Forbidden
                    description: Short, human-readable summary of the problem type
                required:
                  - type
                  - title
          example:
            type: FORBIDDEN
            title: Forbidden
            detail: You do not have permission to access this resource.
    NotFound:
      description: Resource not found
      content:
        application/problem+json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ProblemDetail'
              - type: object
                properties:
                  type:
                    type: string
                    const: RESOURCE_NOT_FOUND
                    description: Error type identifier for not found resources
                  title:
                    type: string
                    const: Resource Not Found
                    description: Short, human-readable summary of the problem type
                required:
                  - type
                  - title
          example:
            type: RESOURCE_NOT_FOUND
            title: Resource Not Found
            detail: Table 'urn:ata:acme:reference-data:table:01924b84-6f7e-7c0c-8f9d-3a2b4c5d6e7f' was not found
