openapi: 3.1.0
info:
  title: Atmakosh Agent Veda — Governance API
  version: "1.0.0"
  summary: Govern any AI-agent action through a plural, auditable decision gate.
  description: >
    Agent Veda is Atmakosh's governance spine. An external orchestrator asks
    permission before it acts; Veda deliberates the action across eight
    worldviews, applies a deny-by-default perimeter and a tiered-autonomy gate,
    and returns a binding verdict plus a hash-chained audit id. Callers MUST NOT
    execute an action unless the response field `execute` is `true`.
    See also the human-readable spec (docs/api/AGENTS_API.md) and Agent Kairo,
    the governed operations agent that composes these endpoints.
  contact:
    name: Atmakosh Research
    email: support@atmakosh.com
  license:
    name: Proprietary — Atmakosh LLC
servers:
  - url: https://atmakosh.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: authorize
    description: Govern a single agent action.
  - name: approvals
    description: Human-in-loop signatures for contested/high-trust actions.
  - name: evidence
    description: Replayable audit evidence.
  - name: loops
    description: Governed pipelines for iterating autonomous agents.
paths:
  /v1/agents/authorize:
    post:
      tags: [authorize]
      operationId: authorizeAgentAction
      summary: Govern one intended agent action.
      description: >
        The council deliberates; the verdict, binding conditions, and full plural
        reasoning are chained into the audit log. Requires role `operator`+.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AgentAuthorizeRequest' }
            examples:
              humanInLoopDeploy:
                value:
                  agent_id: build-agent-7
                  action: deploy service atmasphere to production
                  context: Monday release train; reviewed by two engineers
                  perimeter: { allowed_actions: [deploy, rollback, scale] }
                  autonomy_level: human_in_loop
      responses:
        '200':
          description: A governed decision. Inspect `execute` before acting.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AuthorizeResponse' }
              examples:
                allowPendingApproval:
                  value:
                    audit_id: a_9f2c
                    timestamp: "2026-07-29T12:00:00Z"
                    verdict: ALLOW
                    conditions: [retain_rollback_plan, notify_on_call]
                    kind: agent_authorization
                    agent_id: build-agent-7
                    action: deploy service atmasphere to production
                    autonomy_level: human_in_loop
                    approval_required: true
                    execute: false
                perimeterDeny:
                  value:
                    verdict: DENY
                    gate: perimeter
                    reason: action outside declared operating perimeter
                    conditions: []
                    approval_required: false
                    execute: false
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/Invalid' }
        '429': { $ref: '#/components/responses/Quota' }
  /v1/approvals:
    get:
      tags: [approvals]
      operationId: listPendingApprovals
      summary: Decisions awaiting an admin signature. Requires platform_admin.
      parameters:
        - { name: limit, in: query, schema: { type: integer, default: 1000 } }
      responses:
        '200':
          description: Pending human-in-loop decisions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count: { type: integer }
                  pending:
                    type: array
                    items: { $ref: '#/components/schemas/PendingApproval' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /v1/approvals/{audit_id}/sign:
    post:
      tags: [approvals]
      operationId: signApproval
      summary: Cryptographically sign a decision, releasing it for execution.
      description: Requires platform_admin. The signed approval is itself chained.
      parameters:
        - { name: audit_id, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Signed. `execute` is now true for the underlying decision.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SignResponse' }
        '404': { description: Unknown audit_id }
        '409': { description: Not an approval-requiring decision, or already signed }
  /v1/approvals/{audit_id}:
    get:
      tags: [approvals]
      operationId: getApprovalStatus
      summary: Approval status, signature verified against the signing key.
      parameters:
        - { name: audit_id, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Approval status envelope }
  /v1/agents/{agent_id}/evidence:
    get:
      tags: [evidence]
      operationId: getAgentEvidence
      summary: Chained decision history for one agent (audit / compliance).
      parameters:
        - { name: agent_id, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Replayable evidence records for the agent }
  /v1/loops/register:
    post:
      tags: [loops]
      operationId: registerLoop
      summary: Register a governed loop manifest for an iterating agent.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/LoopManifest' }
      responses:
        '200': { description: Registered (a 4xx "already registered" is benign) }
  /v1/loops/{loop_id}/checkpoint:
    post:
      tags: [loops]
      operationId: checkpointLoop
      summary: Govern one loop step through the five gates.
      parameters:
        - { name: loop_id, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [action]
              properties:
                action: { type: string }
                context: { type: string }
      responses:
        '200':
          description: Verdict + loop governance for the step.
          content:
            application/json:
              schema:
                type: object
                properties:
                  verdict: { $ref: '#/components/schemas/Verdict' }
                  loop_governance: { type: object, additionalProperties: true }
                  audit_id: { type: string }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT carrying role and region claims. Role `operator`+ for authorize; `platform_admin` for approvals.
  schemas:
    Verdict:
      type: string
      enum: [ALLOW, ALLOW_WITH_REVIEW, DENY]
      description: >
        ALLOW = every worldview proceeds; ALLOW_WITH_REVIEW = a worldview demands
        evidence first (never executes — routed to human review); DENY = rejected.
    AutonomyLevel:
      type: string
      enum: [shadow, human_in_loop, autonomous]
      default: autonomous
      description: >
        shadow = observe-only (never executes); human_in_loop = even an ALLOW
        needs a signed approval; autonomous = ALLOW executes.
    AgentAuthorizeRequest:
      type: object
      required: [agent_id, action]
      properties:
        agent_id: { type: string, minLength: 1, maxLength: 200 }
        action:
          type: string
          minLength: 3
          maxLength: 4000
          description: What the agent intends to do.
        context: { type: string, maxLength: 8000, default: "" }
        philosophies:
          type: array
          items: { type: string }
          description: Optional subset of the eight worldviews; empty = all.
        perimeter:
          type: object
          description: When allowed_actions is set, an action outside it is denied at the perimeter gate.
          properties:
            allowed_actions:
              type: array
              items: { type: string }
        autonomy_level: { $ref: '#/components/schemas/AutonomyLevel' }
    AuthorizeResponse:
      type: object
      properties:
        audit_id: { type: string, description: Hash-chained record id. }
        timestamp: { type: string, format: date-time }
        verdict: { $ref: '#/components/schemas/Verdict' }
        conditions:
          type: array
          items: { type: string }
          description: Binding conditions the caller must honour when executing.
        kind: { type: string, example: agent_authorization }
        agent_id: { type: string }
        action: { type: string }
        autonomy_level: { $ref: '#/components/schemas/AutonomyLevel' }
        approval_required:
          type: boolean
          description: If true, a signed approval is required before execution.
        execute:
          type: boolean
          description: The caller MUST NOT run the action unless this is true.
        gate:
          type: [string, "null"]
          description: Set to "perimeter" when denied before the council convened.
        reason: { type: string }
      required: [verdict, conditions, execute, approval_required]
    PendingApproval:
      type: object
      properties:
        audit_id: { type: string }
        timestamp: { type: string, format: date-time }
        agent_id: { type: string }
        action: { type: string }
        verdict: { $ref: '#/components/schemas/Verdict' }
        conditions: { type: array, items: { type: string } }
    SignResponse:
      type: object
      properties:
        approval_audit_id: { type: string }
        execute: { type: boolean, example: true }
        signature: { type: string }
        key_id: { type: string }
    LoopManifest:
      type: object
      required: [loop_id, objective, reward_function, perimeter]
      properties:
        loop_id: { type: string }
        objective: { type: string }
        reward_function: { type: string }
        owner: { type: string }
        escalation_contact: { type: string }
        perimeter:
          type: object
          properties:
            allowed_actions: { type: array, items: { type: string } }
        stopping:
          type: object
          properties:
            max_denials: { type: integer, default: 3 }
        philosophies: { type: array, items: { type: string } }
    Error:
      type: object
      properties:
        detail: { type: string, description: Human-readable reason. }
  responses:
    Unauthorized:
      description: Missing or invalid token.
      content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
    Forbidden:
      description: Authenticated but role/region not permitted.
      content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
    Invalid:
      description: Invalid request body (e.g. unknown autonomy_level).
      content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
    Quota:
      description: Entitlement or quota exceeded.
      content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
