Validere transactions API

openapi: 3.0.1
info:
  description: Activity Log
  title: CarbonHub activities transactions API
  version: 1.0.0
servers:
- url: https://api.validere.io
security:
- Staging: []
- Integration: []
- Local: []
tags:
- name: transactions
paths:
  /transactions:
    get:
      tags:
      - transactions
      summary: List All Transactions
      description: 'Returns a list of transactions submitted to the Data Platform


        The following fields should be passed as query parameters:


        * `submitted_after` (datetime) - Optional, otherwise defaults to 1 week before current datetime. Required in isoformat i.e. %Y-%m-%dT%H:%M:%S%Z

        * `submitted_before` (datetime) -  Optional, otherwise defaults to current datetime. Required in isoformat i.e. %Y-%m-%dT%H:%M:%S%Z'
      operationId: list_all_transactions_transactions_get
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: filter_out_file_uploads
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          default: true
          title: Filter Out File Uploads
      - name: dataset_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Dataset Id
      - name: submitted_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Submitted After
      - name: submitted_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Submitted Before
      - name: step
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/TransactionStep'
          - type: 'null'
          title: Step
      - name: source
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/Source'
          - type: 'null'
          title: Source
      - name: bucket
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Bucket
      - name: file_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: File Key
      - name: state
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/TransactionState'
          - type: 'null'
          title: State
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/TransactionStatus'
          - type: 'null'
          title: Status
      - name: only_latest
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Only Latest
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
              example:
                meta:
                  type: TransactionsData
                  total: 1
                data:
                - transaction_id: 3986cdbd-46b9-40c2-93fe-4d772f13a835
                  client_id: 643760c2-1665-441b-bb74-97f26e936248
                  dataset_id: ae977bba-ed9b-4ca5-b232-52ba826b5a37
                  source: api
                  total_count: 60
                  step: sink
                  bucket: bucket
                  file_key: a/b/c.csv
                  successful_count: 50
                  state: success
                  created_at: '2023-07-01T00:00:00Z'
                  archived_status: pending
                  status: completed
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /transactions/{transaction_id}:
    get:
      tags:
      - transactions
      summary: Get Transaction By Id
      description: Fetches details/status of a transaction based on its UUID.
      operationId: get_transaction_by_id_transactions__transaction_id__get
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: transaction_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Transaction Id
      - name: history
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: History
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
              example:
                meta:
                  type: Transaction
                  total: 1
                data:
                - transaction_id: 3986cdbd-46b9-40c2-93fe-4d772f13a835
                  client_id: 643760c2-1665-441b-bb74-97f26e936248
                  dataset_id: ae977bba-ed9b-4ca5-b232-52ba826b5a37
                  source: api
                  total_count: 60
                  step: sink
                  bucket: bucket
                  file_key: a/b/c.csv
                  successful_count: 50
                  state: success
                  created_at: '2023-07-01T00:00:00Z'
                  archived_status: pending
                  status: completed
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /transactions/{transaction_id}/download:
    get:
      tags:
      - transactions
      summary: Download Transaction File Version
      operationId: download_transaction_file_version_transactions__transaction_id__download_get
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: transaction_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Transaction Id
      - name: error_only
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Error Only
      - name: version
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/TransactionDownloadVersion'
          default: submitted
      responses:
        '200':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /transactions/{transaction_id}/sink/summary:
    get:
      tags:
      - transactions
      summary: Get Sink Summary By Transaction By Id
      description: 'Fetches details/status of a transaction based on its UUID.

        Soft deprecation in favour of GET /{transaction_id}/details"'
      operationId: get_sink_summary_by_transaction_by_id_transactions__transaction_id__sink_summary_get
      deprecated: true
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: transaction_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Transaction Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDetailsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /transactions/{transaction_id}/retry:
    post:
      tags:
      - transactions
      summary: Retry Transaction By Id
      operationId: retry_transaction_by_id_transactions__transaction_id__retry_post
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: transaction_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Transaction Id
      - name: transaction_retry_stage
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/TransactionStage'
          - type: 'null'
          description: Optional. Will default to latest transaction step if not provided
          title: Transaction Retry Stage
        description: Optional. Will default to latest transaction step if not provided
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
              example:
                meta:
                  type: TransactionsData
                  total: 1
                data:
                - transaction_id: 3986cdbd-46b9-40c2-93fe-4d772f13a835
                  client_id: 643760c2-1665-441b-bb74-97f26e936248
                  dataset_id: ae977bba-ed9b-4ca5-b232-52ba826b5a37
                  source: api
                  total_count: 60
                  step: sink
                  bucket: bucket
                  file_key: a/b/c.csv
                  successful_count: 50
                  state: success
                  created_at: '2023-07-01T00:00:00Z'
                  archived_status: pending
                  status: completed
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /transactions/{transaction_id}/details:
    get:
      tags:
      - transactions
      summary: Get Transaction Details By Id
      description: Fetches details/status of a transaction based on its UUID.
      operationId: get_transaction_details_by_id_transactions__transaction_id__details_get
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: transaction_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Transaction Id
      - name: include_data
        in: query
        required: false
        schema:
          type: boolean
          default: true
          title: Include Data
      - name: status_filter
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/EntityIngestionStatus'
          - type: 'null'
          title: Status Filter
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: -1
          title: Page
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          default: 20
          title: Page Size
      - name: accept
        in: header
        required: false
        schema:
          type: string
          default: application/json
          title: Accept
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDetailsResponse'
            text/csv: {}
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/transactions/{transaction_id}/details:
    get:
      tags:
      - transactions
      summary: Get Transaction Details Page V2
      description: 'Returns one page of transaction detail rows from DynamoDB using cursor-based pagination.


        Pass `continuation_token` from the previous response to advance to the next page.

        When `status_filter` is supplied, DynamoDB applies the filter after reading

        `page_size` rows, so a page may return fewer rows than requested — keep paging

        until `continuation_token` is null.'
      operationId: get_transaction_details_page_v2_v2_transactions__transaction_id__details_get
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: transaction_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Transaction Id
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 20
          title: Page Size
      - name: continuation_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Continuation Token
      - name: status_filter
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/EntityIngestionStatus'
          - type: 'null'
          title: Status Filter
      - name: include_data
        in: query
        required: false
        schema:
          type: boolean
          default: true
          title: Include Data
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDetailsV2Response'
              example:
                meta:
                  type: TransactionDetails
                data:
                - success_count: 48
                  failure_count: 2
                  details: []
                  page_size: 20
                  total_entries: 50
                  total_pages: 3
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    TransactionDetailsV2Response:
      properties:
        meta:
          $ref: '#/components/schemas/TransactionDetailsMeta'
        data:
          items:
            $ref: '#/components/schemas/TransactionDetailsV2Data'
          type: array
          title: Data
      type: object
      required:
      - meta
      - data
      title: TransactionDetailsV2Response
    Transaction:
      properties:
        transaction_id:
          type: string
          format: uuid
          title: Transaction Id
        client_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Client Id
        company_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Company Id
        dataset_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Dataset Id
        user_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: User Id
        source:
          anyOf:
          - $ref: '#/components/schemas/Source'
          - type: 'null'
          default: unknown
        original_file_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Original File Name
        total_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Count
        step:
          $ref: '#/components/schemas/TransactionStep'
        bucket:
          type: string
          title: Bucket
        file_key:
          type: string
          title: File Key
        successful_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Successful Count
        state:
          $ref: '#/components/schemas/TransactionState'
        details:
          anyOf:
          - type: string
          - type: 'null'
          title: Details
        created_at:
          type: string
          title: Created At
          default: '2026-07-21T12:22:54.927561Z'
        archived_status:
          $ref: '#/components/schemas/TransactionState'
          default: pending
        status:
          $ref: '#/components/schemas/TransactionStatus'
          default: pending
      type: object
      required:
      - step
      - bucket
      - file_key
      - state
      title: Transaction
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TransactionDetailsResponse:
      properties:
        meta:
          $ref: '#/components/schemas/TransactionDetailsMeta'
        data:
          items:
            $ref: '#/components/schemas/TransactionDetailsData'
          type: array
          title: Data
      type: object
      required:
      - meta
      - data
      title: TransactionDetailsResponse
    TransactionDetailsMeta:
      properties:
        type:
          type: string
          title: Type
          default: TransactionDetails
        transaction_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Transaction Id
        info:
          anyOf:
          - type: string
          - type: 'null'
          title: Info
        total:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total
      type: object
      title: TransactionDetailsMeta
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    TransactionState:
      type: string
      enum:
      - pending
      - success
      - partial_success
      - partial_failure
      - failed
      - retried
      title: TransactionState
    TransactionDetailsData:
      properties:
        success_count:
          type: integer
          title: Success Count
        failure_count:
          type: integer
          title: Failure Count
        summary:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Summary
        details:
          items:
            $ref: '#/components/schemas/RowSummary'
          type: array
          title: Details
        page_number:
          anyOf:
          - type: integer
          - type: 'null'
          title: Page Number
        page_size:
          anyOf:
          - type: integer
          - type: 'null'
          title: Page Size
        total_entries:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Entries
        total_pages:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Pages
      type: object
      required:
      - success_count
      - failure_count
      - details
      title: TransactionDetailsData
    TransactionDetailsV2Data:
      properties:
        success_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Success Count
        failure_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Failure Count
        summary:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Summary
        details:
          items:
            $ref: '#/components/schemas/RowSummary'
          type: array
          title: Details
        page_size:
          type: integer
          title: Page Size
        continuation_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Continuation Token
        total_entries:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Entries
        total_pages:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Pages
      type: object
      required:
      - details
      - page_size
      title: TransactionDetailsV2Data
    TransactionStage:
      type: string
      enum:
      - transformation
      - ingestion
      title: TransactionStage
    TransactionStep:
      type: string
      enum:
      - email_validator
      - transaction_recorder
      - vulnerability_scanner
      - archiver
      - validator
      - operator
      - sink
      title: TransactionStep
    TransactionResponse:
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        data:
          items:
            $ref: '#/components/schemas/Transaction'
          type: array
          title: Data
      type: object
      required:
      - meta
      - data
      title: TransactionResponse
      description: Transaction response envelope
    EntityIngestionStatus:
      type: string
      enum:
      - created
      - updated
      - failed
      - unchanged
      title: EntityIngestionStatus
    TransactionDownloadVersion:
      type: string
      enum:
      - submitted
      - transformed
      title: TransactionDownloadVersion
    Source:
      type: string
      enum:
      - api
      - sftp
      - email
      - iot
      - kafka
      - upload
      - unknown
      - connectors
      - petrinex
      title: Source
    RowSummary:
      properties:
        index:
          type: string
          title: Index
        status:
          type: string
          title: Status
        data:
          anyOf:
          - type: string
          - type: 'null'
          title: Data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        error_msg:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Msg
        entity_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Entity Type
        error_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Error Count
        error_details:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Error Details
      type: object
      required:
      - index
      - status
      title: RowSummary
    ResponseMeta:
      properties:
        type:
          type: string
          title: Type
        transaction_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Transaction Id
        info:
          anyOf:
          - type: string
          - type: 'null'
          title: Info
        total:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total
      type: object
      required:
      - type
      title: ResponseMeta
      description: Standard response envelope meta object
    TransactionStatus:
      type: string
      enum:
      - pending
      - failed
      - completed
      - completed_with_partial_success
      title: TransactionStatus