Algenta Decision Workflow API

openapi: 3.2.0
info:
  title: Algenta Ai Decision Workflow API
  version: 1.0.0
  description: 'Operations tagged Decision Workflow across 2 of this provider''s published API definitions: api.algenta.ai-openapi.json, gateway.algenta.ai-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.algenta.ai
- url: /
tags:
- name: Decision Workflow
paths:
  /v1/decision-cases:
    post:
      tags:
      - Decision Workflow
      summary: Frame a decision (create a case + immutable revision 1)
      operationId: create_decision_case_v1_decision_cases_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDecisionCaseRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionCaseResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - LegacyApiKey: []
    servers:
    - url: https://api.algenta.ai
  /v1/decision-cases/{case_id}:
    put:
      tags:
      - Decision Workflow
      summary: Re-frame a decision (material change → new immutable revision)
      operationId: update_decision_case_v1_decision_cases__case_id__put
      security:
      - BearerAuth: []
      - LegacyApiKey: []
      parameters:
      - name: case_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Case Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDecisionCaseRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionCaseResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Decision Workflow
      summary: Get a decision case
      operationId: get_decision_case_v1_decision_cases__case_id__get
      security:
      - BearerAuth: []
      - LegacyApiKey: []
      parameters:
      - name: case_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Case Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionCaseResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.algenta.ai
  /v1/decision-cases/{case_id}/analysis-runs:
    post:
      tags:
      - Decision Workflow
      summary: 'Run the governed analysis (async: poll for the result)'
      operationId: start_analysis_run_v1_decision_cases__case_id__analysis_runs_post
      security:
      - BearerAuth: []
      - LegacyApiKey: []
      parameters:
      - name: case_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Case Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/StartAnalysisRequest'
              - type: 'null'
              title: Payload
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisRunAccepted'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.algenta.ai
  /v1/decision-cases/{case_id}/refresh:
    post:
      tags:
      - Decision Workflow
      summary: 'Manually refresh: re-run the current revision with fresh evidence'
      operationId: refresh_decision_v1_decision_cases__case_id__refresh_post
      security:
      - BearerAuth: []
      - LegacyApiKey: []
      parameters:
      - name: case_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Case Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/StartAnalysisRequest'
              - type: 'null'
              title: Payload
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisRunAccepted'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.algenta.ai
  /v1/analysis-runs/{run_id}:
    get:
      tags:
      - Decision Workflow
      summary: Poll an analysis run
      operationId: get_analysis_run_v1_analysis_runs__run_id__get
      security:
      - BearerAuth: []
      - LegacyApiKey: []
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Run Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisRunStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.algenta.ai
  /v1/analysis-runs/{run_id}/result:
    get:
      tags:
      - Decision Workflow
      summary: Fetch the analysis result (host-independent object)
      operationId: get_analysis_result_v1_analysis_runs__run_id__result_get
      security:
      - BearerAuth: []
      - LegacyApiKey: []
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Run Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisResultResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.algenta.ai
  /v1/analysis-runs/{run_id}/evidence:
    get:
      tags:
      - Decision Workflow
      summary: Inspect evidence + provenance (what was accessed, under which retention mode)
      operationId: inspect_evidence_v1_analysis_runs__run_id__evidence_get
      security:
      - BearerAuth: []
      - LegacyApiKey: []
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Run Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvidenceResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.algenta.ai
  /v1/analysis-runs/{run_id}/action-plans:
    post:
      tags:
      - Decision Workflow
      summary: Propose a safe execution plan (returns the plan_hash + single-use approval…
      operationId: propose_action_plan_v1_analysis_runs__run_id__action_plans_post
      security:
      - BearerAuth: []
      - LegacyApiKey: []
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Run Id
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionPlanResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.algenta.ai
  /v1/decision-plans/{plan_id}/approve:
    post:
      tags:
      - Decision Workflow
      summary: Approve a proposed plan (separately authenticated; plan_hash + single-use nonce)
      description: Approval is an explicit, credentialed operation bound to the exact plan hash and a single-use nonce. It is intentionally not exposed as an MCP/LLM tool. Approving does NOT execute the plan (approve != execute).
      operationId: approve_plan_v1_decision_plans__plan_id__approve_post
      security:
      - BearerAuth: []
      - LegacyApiKey: []
      parameters:
      - name: plan_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Plan Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/apps__api_server__schemas__decision_workflow__ApproveRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.algenta.ai
  /v1/decision-plans/{plan_id}/execute:
    post:
      tags:
      - Decision Workflow
      summary: Execute an APPROVED plan (safe MVP actions only)
      operationId: execute_plan_v1_decision_plans__plan_id__execute_post
      security:
      - BearerAuth: []
      - LegacyApiKey: []
      parameters:
      - name: plan_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Plan Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionPlanResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.algenta.ai
  /v1/decision-cases/{case_id}/outcomes:
    post:
      tags:
      - Decision Workflow
      summary: Record what actually happened (closes the learning loop)
      operationId: record_outcome_v1_decision_cases__case_id__outcomes_post
      security:
      - BearerAuth: []
      - LegacyApiKey: []
      parameters:
      - name: case_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Case Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/apps__api_server__schemas__decision_workflow__RecordOutcomeRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutcomeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.algenta.ai
components:
  schemas:
    AnalysisRunAccepted:
      properties:
        run_id:
          type: string
          format: uuid
          title: Run Id
        case_id:
          type: string
          format: uuid
          title: Case Id
        status:
          type: string
          title: Status
        poll_url:
          type: string
          title: Poll Url
        result_url:
          type: string
          title: Result Url
      type: object
      required:
      - run_id
      - case_id
      - status
      - poll_url
      - result_url
      title: AnalysisRunAccepted
    ApprovalResponse:
      properties:
        approval_id:
          type: string
          format: uuid
          title: Approval Id
        case_id:
          type: string
          format: uuid
          title: Case Id
        plan_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Plan Id
        status:
          type: string
          title: Status
        approver_principal:
          anyOf:
          - type: string
          - type: 'null'
          title: Approver Principal
        decided_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Decided At
      type: object
      required:
      - approval_id
      - case_id
      - plan_id
      - status
      - approver_principal
      - decided_at
      title: ApprovalResponse
    apps__api_server__schemas__decision_workflow__ApproveRequest:
      properties:
        plan_hash:
          type: string
          maxLength: 64
          minLength: 16
          title: Plan Hash
        nonce:
          type: string
          maxLength: 64
          minLength: 8
          title: Nonce
        idempotency_key:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Idempotency Key
      type: object
      required:
      - plan_hash
      - nonce
      title: ApproveRequest
    ExecutionReceipt:
      properties:
        receipt_version:
          type: string
          title: Receipt Version
          description: Receipt schema version. Bumped only on a breaking change.
          default: '1'
        status:
          type: string
          enum:
          - executed
          - denied
          - approval_required
          - failed
          title: Status
          description: Terminal state of the governed operation this receipt describes.
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
          description: Machine-readable reason when status is not 'executed' -- the same DecisionServiceError code the HTTP layer maps (e.g. plan_hash_mismatch, invalid_nonce, approval_expired).
        retryable:
          type: boolean
          title: Retryable
          description: Whether re-issuing the identical request could succeed. A policy denial is NOT retryable; an upstream timeout is. Stated explicitly so a caller does not have to infer intent from an HTTP status.
          default: false
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Request Id
          description: Identifies the single HTTP call that produced this receipt.
        trace_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Trace Id
          description: W3C trace-id of the wider operation. One agent turn may produce several receipts; this is what lets them be reassembled afterwards.
        idempotency_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency Key
          description: The Idempotency-Key the caller supplied, echoed so a retry can be matched to its original outcome. None when the caller sent none.
        execution_id:
          type: string
          format: uuid
          title: Execution Id
          description: 'Unique id for this execution attempt, minted at execute time and persisted with the receipt. Distinct from plan_id: the plan is what was authorised, this is the act.'
        plan_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Plan Hash
          description: Hash of the approved plan. An approval is bound to this exact value.
        approval_state:
          anyOf:
          - type: string
            enum:
            - approved
            - not_required
            - pending
            - rejected
            - expired
          - type: 'null'
          title: Approval State
          description: Approval status at the moment of execution.
        policy_snapshot_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Policy Snapshot Hash
          description: Content hash of the policy snapshot in force. None on the decision-plan path, which carries no policy snapshot -- deliberately null rather than filled with a value that is not a policy hash.
        executed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Executed At
          description: When execution completed.
        result:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Result
          description: Operation-specific result. Everything above is stable across operations.
      type: object
      required:
      - status
      - execution_id
      title: ExecutionReceipt
      description: Evidence that one approved plan executed exactly once, and under what authority.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
    AnalysisResultResponse:
      properties:
        status:
          type: string
          title: Status
        reproducibility_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Reproducibility Id
        model_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Version
        result:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Result
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      type: object
      required:
      - status
      title: AnalysisResultResponse
    EvidenceResponse:
      properties:
        evidence:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Evidence
        provenance:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Provenance
        reproducibility_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Reproducibility Id
      type: object
      required:
      - evidence
      - provenance
      - reproducibility_id
      title: EvidenceResponse
    StartAnalysisRequest:
      properties:
        retention_mode:
          type: string
          pattern: ^(exploratory|governed)$
          title: Retention Mode
          description: exploratory = refs + hashes only; governed = retain inputs for reproduction
          default: exploratory
      type: object
      title: StartAnalysisRequest
    AnalysisRunStatusResponse:
      properties:
        run_id:
          type: string
          format: uuid
          title: Run Id
        case_id:
          type: string
          format: uuid
          title: Case Id
        revision_id:
          type: string
          format: uuid
          title: Revision Id
        status:
          type: string
          title: Status
        model_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Version
        reproducibility_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Reproducibility Id
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
        finished_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Finished At
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      type: object
      required:
      - run_id
      - case_id
      - revision_id
      - status
      title: AnalysisRunStatusResponse
    OutcomeResponse:
      properties:
        outcome_id:
          type: string
          format: uuid
          title: Outcome Id
        case_id:
          type: string
          format: uuid
          title: Case Id
        run_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Run Id
        actual_metrics:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Actual Metrics
        delta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Delta
        recorded_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Recorded At
      type: object
      required:
      - outcome_id
      - case_id
      - run_id
      - actual_metrics
      - delta
      - recorded_at
      title: OutcomeResponse
    DecisionCaseResponse:
      properties:
        case_id:
          type: string
          format: uuid
          title: Case Id
        pack_id:
          type: string
          title: Pack Id
        title:
          type: string
          title: Title
        owner:
          anyOf:
          - type: string
          - type: 'null'
          title: Owner
        status:
          type: string
          title: Status
        current_revision_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Current Revision Id
        current_revision_number:
          type: integer
          title: Current Revision Number
        inputs_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Inputs Hash
      type: object
      required:
      - case_id
      - pack_id
      - title
      - owner
      - status
      - current_revision_id
      - current_revision_number
      title: DecisionCaseResponse
    ExecutionPlanResponse:
      properties:
        plan_id:
          type: string
          format: uuid
          title: Plan Id
        case_id:
          type: string
          format: uuid
          title: Case Id
        run_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Run Id
        lifecycle_state:
          type: string
          title: Lifecycle State
        plan_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Plan Hash
        nonce:
          anyOf:
          - type: string
          - type: 'null'
          title: Nonce
          description: Single-use approval challenge (present only at propose time)
        actions:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Actions
        receipt:
          anyOf:
          - $ref: '#/components/schemas/ExecutionReceipt'
          - type: 'null'
      type: object
      required:
      - plan_id
      - case_id
      - run_id
      - lifecycle_state
      - plan_hash
      - actions
      title: ExecutionPlanResponse
    CreateDecisionCaseRequest:
      properties:
        pack_id:
          type: string
          maxLength: 128
          minLength: 1
          title: Pack Id
          examples:
          - renewal_capacity_allocation
        title:
          type: string
          maxLength: 200
          minLength: 1
          title: Title
        pack_input:
          additionalProperties: true
          type: object
          title: Pack Input
          description: The pack's contract input (validated)
        owner:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Owner
        objective:
          anyOf:
          - type: string
          - type: 'null'
          title: Objective
        horizon_days:
          anyOf:
          - type: integer
            maximum: 730.0
            minimum: 1.0
          - type: 'null'
          title: Horizon Days
      type: object
      required:
      - pack_id
      - title
      - pack_input
      title: CreateDecisionCaseRequest
    apps__api_server__schemas__decision_workflow__RecordOutcomeRequest:
      properties:
        run_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Run Id
        actual_metrics:
          additionalProperties: true
          type: object
          title: Actual Metrics
          description: 'e.g. {''retained_arr'': 400000}'
        notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Notes
      type: object
      required:
      - actual_metrics
      title: RecordOutcomeRequest
    ExecutionPlanResponse_2:
      properties:
        plan_id:
          type: string
          format: uuid
          title: Plan Id
        case_id:
          type: string
          format: uuid
          title: Case Id
        run_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Run Id
        lifecycle_state:
          type: string
          title: Lifecycle State
        plan_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Plan Hash
        nonce:
          anyOf:
          - type: string
          - type: 'null'
          title: Nonce
          description: Single-use approval challenge (present only at propose time)
        actions:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Actions
        receipt:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Receipt
      type: object
      required:
      - plan_id
      - case_id
      - run_id
      - lifecycle_state
      - plan_hash
      - actions
      title: ExecutionPlanResponse
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: APIKey
      description: 'Canonical v1 authentication. Use Authorization: Bearer <api_key>.'
    LegacyApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Legacy compatibility header for existing v1 clients.
x-refined-from:
- api.algenta.ai-openapi.json


# --- truncated at 32 KB (37 KB total) ---
# Full source: https://artifacts.apis.io/algenta-ai/openapi/algenta-ai-decision-workflow-api-openapi.yml