grafomem-com Agent Orchestrator API

openapi: 3.2.0
info:
  title: GRAFOMEM Cloud Agent Orchestrator API
  description: GMP-conformant governed agent memory platform. Provides vector-backed memory stores, multi-agent orchestration, decision trail audit logging, erasure proof certificates, governance policy evaluation, regulatory reports, webhook alerts, SSO/OIDC, and real-time SSE streaming.
  version: 1.9.0
tags:
- name: Agent Orchestrator
paths:
  /v1/orchestrator/stats:
    get:
      tags:
      - Agent Orchestrator
      summary: Get Stats
      description: Dashboard statistics for the orchestrator.
      operationId: get_stats_v1_orchestrator_stats_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrchestratorStatsResponse'
  /v1/orchestrator/roles:
    get:
      tags:
      - Agent Orchestrator
      summary: List Roles
      description: List available agent roles.
      operationId: list_roles_v1_orchestrator_roles_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/orchestrator/agents:
    post:
      tags:
      - Agent Orchestrator
      summary: Create Agent
      description: Create a new agent definition.
      operationId: create_agent_v1_orchestrator_agents_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Agent Orchestrator
      summary: List Agents
      description: List all agents for the tenant.
      operationId: list_agents_v1_orchestrator_agents_get
      parameters:
      - name: enabled_only
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Enabled Only
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/orchestrator/agents/{agent_id}/propose:
    post:
      tags:
      - Agent Orchestrator
      summary: Propose Action
      description: 'PR-0 — record a CGR-attributed governed decision for a proposed tool action

        (no LLM run). The decision carries the agent''s agent_key + invoice_ref so the agent

        becomes CGR-scorable. Edge-gate/HITL enforcement arrives in later PRs.'
      operationId: propose_action_v1_orchestrator_agents__agent_id__propose_post
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProposeActionRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/orchestrator/agents/{agent_id}:
    get:
      tags:
      - Agent Orchestrator
      summary: Get Agent
      description: Get a single agent by ID.
      operationId: get_agent_v1_orchestrator_agents__agent_id__get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Agent Orchestrator
      summary: Update Agent
      description: Update an agent definition.
      operationId: update_agent_v1_orchestrator_agents__agent_id__put
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Agent Orchestrator
      summary: Delete Agent
      description: Delete an agent definition.
      operationId: delete_agent_v1_orchestrator_agents__agent_id__delete
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/orchestrator/workflows:
    post:
      tags:
      - Agent Orchestrator
      summary: Create Workflow
      description: Create a new workflow.
      operationId: create_workflow_v1_orchestrator_workflows_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkflowRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Agent Orchestrator
      summary: List Workflows
      description: List workflows for the tenant.
      operationId: list_workflows_v1_orchestrator_workflows_get
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/orchestrator/workflows/{workflow_id}:
    get:
      tags:
      - Agent Orchestrator
      summary: Get Workflow
      description: Get a workflow with all its steps.
      operationId: get_workflow_v1_orchestrator_workflows__workflow_id__get
      parameters:
      - name: workflow_id
        in: path
        required: true
        schema:
          type: string
          title: Workflow Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/orchestrator/workflows/{workflow_id}/run:
    post:
      tags:
      - Agent Orchestrator
      summary: Run Workflow
      description: Start a workflow execution with the given input.
      operationId: run_workflow_v1_orchestrator_workflows__workflow_id__run_post
      parameters:
      - name: workflow_id
        in: path
        required: true
        schema:
          type: string
          title: Workflow Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunWorkflowRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/orchestrator/workflows/{workflow_id}/stream:
    get:
      tags:
      - Agent Orchestrator
      summary: Stream Workflow
      description: 'Stream a workflow execution via Server-Sent Events.


        Returns a text/event-stream response with real-time events as

        each agent step progresses through:

        governance → memory → LLM → tools → complete.


        Event types:

        workflow.started, step.started, step.governance_pass,

        step.governance_deny, step.memory_retrieve, step.llm_start,

        step.llm_complete, step.tool_call, step.complete,

        workflow.complete, workflow.error'
      operationId: stream_workflow_v1_orchestrator_workflows__workflow_id__stream_get
      parameters:
      - name: workflow_id
        in: path
        required: true
        schema:
          type: string
          title: Workflow Id
      - name: input_text
        in: query
        required: true
        schema:
          type: string
          description: The initial input for the workflow
          title: Input Text
        description: The initial input for the workflow
      - name: timeout_seconds
        in: query
        required: false
        schema:
          type: number
          description: Timeout in seconds for the workflow
          default: 300.0
          title: Timeout Seconds
        description: Timeout in seconds for the workflow
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/orchestrator/workflows/{workflow_id}/resume:
    post:
      tags:
      - Agent Orchestrator
      summary: Resume Workflow
      description: Resume a workflow waiting for HITL approval.
      operationId: resume_workflow_v1_orchestrator_workflows__workflow_id__resume_post
      parameters:
      - name: workflow_id
        in: path
        required: true
        schema:
          type: string
          title: Workflow Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumeWorkflowRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/orchestrator/workflows/{workflow_id}/resume/stream:
    get:
      tags:
      - Agent Orchestrator
      summary: Resume Workflow Stream
      description: Resume a workflow waiting for HITL approval and stream the results.
      operationId: resume_workflow_stream_v1_orchestrator_workflows__workflow_id__resume_stream_get
      parameters:
      - name: workflow_id
        in: path
        required: true
        schema:
          type: string
          title: Workflow Id
      - name: approved
        in: query
        required: true
        schema:
          type: boolean
          title: Approved
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/orchestrator/workflows/{workflow_id}/terminate:
    post:
      tags:
      - Agent Orchestrator
      summary: Terminate Workflow
      description: Force-terminate a running workflow.
      operationId: terminate_workflow_v1_orchestrator_workflows__workflow_id__terminate_post
      parameters:
      - name: workflow_id
        in: path
        required: true
        schema:
          type: string
          title: Workflow Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/orchestrator/step:
    post:
      tags:
      - Agent Orchestrator
      summary: Execute Step
      description: 'Execute a single ad-hoc step (not part of a workflow).


        Creates a temporary workflow and executes one governed step.

        Useful for testing agents and one-shot queries.'
      operationId: execute_step_v1_orchestrator_step_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteStepRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/orchestrator/steps/{step_id}:
    get:
      tags:
      - Agent Orchestrator
      summary: Get Step
      description: Get a single step by ID.
      operationId: get_step_v1_orchestrator_steps__step_id__get
      parameters:
      - name: step_id
        in: path
        required: true
        schema:
          type: string
          title: Step Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/orchestrator/workflows/{workflow_id}/receipts:
    get:
      tags:
      - Agent Orchestrator
      summary: Get Workflow Receipts
      description: Get all execution receipts for a workflow.
      operationId: get_workflow_receipts_v1_orchestrator_workflows__workflow_id__receipts_get
      parameters:
      - name: workflow_id
        in: path
        required: true
        schema:
          type: string
          title: Workflow Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/orchestrator/workflows/{workflow_id}/verify-chain:
    get:
      tags:
      - Agent Orchestrator
      summary: Verify Receipt Chain
      description: Verify the hash chain integrity of a workflow's receipts.
      operationId: verify_receipt_chain_v1_orchestrator_workflows__workflow_id__verify_chain_get
      parameters:
      - name: workflow_id
        in: path
        required: true
        schema:
          type: string
          title: Workflow Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChainVerificationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/orchestrator/receipts/{receipt_id}:
    get:
      tags:
      - Agent Orchestrator
      summary: Get Receipt
      description: Get a single execution receipt.
      operationId: get_receipt_v1_orchestrator_receipts__receipt_id__get
      parameters:
      - name: receipt_id
        in: path
        required: true
        schema:
          type: string
          title: Receipt Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/orchestrator/replay/{decision_id}:
    post:
      tags:
      - Agent Orchestrator
      summary: Replay Decision
      description: 'Re-execute a decision with frozen inputs and verify output.


        WARNING: This calls the LLM provider and incurs costs.'
      operationId: replay_decision_v1_orchestrator_replay__decision_id__post
      parameters:
      - name: decision_id
        in: path
        required: true
        schema:
          type: string
          title: Decision Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ResumeWorkflowRequest:
      properties:
        approved:
          type: boolean
          title: Approved
      type: object
      required:
      - approved
      title: ResumeWorkflowRequest
      description: Request body for POST /v1/orchestrator/workflows/{id}/resume.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RunWorkflowRequest:
      properties:
        input_text:
          type: string
          title: Input Text
        timeout_seconds:
          anyOf:
          - type: number
          - type: 'null'
          title: Timeout Seconds
      type: object
      required:
      - input_text
      title: RunWorkflowRequest
      description: Request body for POST /v1/orchestrator/workflows/{id}/run.
    ChainVerificationResponse:
      properties:
        status:
          type: string
          title: Status
        steps_verified:
          type: integer
          title: Steps Verified
          default: 0
        tampered_at_step:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tampered At Step
      type: object
      required:
      - status
      title: ChainVerificationResponse
    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
    CreateAgentRequest:
      properties:
        name:
          type: string
          title: Name
        role:
          type: string
          title: Role
          default: custom
        description:
          type: string
          title: Description
          default: ''
        model_id:
          type: string
          title: Model Id
        fallback_models:
          items:
            type: string
          type: array
          title: Fallback Models
        system_prompt:
          type: string
          title: System Prompt
        memory_stores:
          items:
            type: string
          type: array
          title: Memory Stores
        tools:
          items:
            type: string
          type: array
          title: Tools
        max_steps:
          type: integer
          title: Max Steps
          default: 20
        max_tokens_per_step:
          type: integer
          title: Max Tokens Per Step
          default: 4096
        temperature:
          type: number
          title: Temperature
          default: 0.7
        enabled:
          type: boolean
          title: Enabled
          default: true
        agent_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Key
        agent_handle:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Handle
      type: object
      required:
      - name
      - model_id
      - system_prompt
      title: CreateAgentRequest
      description: Request body for POST /v1/orchestrator/agents.
    CreateWorkflowRequest:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
          default: ''
        agent_ids:
          items:
            type: string
          type: array
          title: Agent Ids
        mode:
          type: string
          title: Mode
          default: sequential
        supervisor_agent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Supervisor Agent Id
        max_total_steps:
          type: integer
          title: Max Total Steps
          default: 100
      type: object
      required:
      - name
      - agent_ids
      title: CreateWorkflowRequest
      description: Request body for POST /v1/orchestrator/workflows.
    ExecuteStepRequest:
      properties:
        agent_id:
          type: string
          title: Agent Id
        input_text:
          type: string
          title: Input Text
        timeout_seconds:
          anyOf:
          - type: number
          - type: 'null'
          title: Timeout Seconds
      type: object
      required:
      - agent_id
      - input_text
      title: ExecuteStepRequest
      description: Request body for POST /v1/orchestrator/step.
    UpdateAgentRequest:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        model_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Id
        fallback_models:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Fallback Models
        system_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: System Prompt
        memory_stores:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Memory Stores
        tools:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tools
        max_steps:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Steps
        max_tokens_per_step:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Tokens Per Step
        temperature:
          anyOf:
          - type: number
          - type: 'null'
          title: Temperature
        enabled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Enabled
      type: object
      title: UpdateAgentRequest
      description: Request body for PUT /v1/orchestrator/agents/{id}.
    OrchestratorStatsResponse:
      properties:
        agents_total:
          type: integer
          title: Agents Total
          default: 0
        workflows_total:
          type: integer
          title: Workflows Total
          default: 0
        steps_total:
          type: integer
          title: Steps Total
          default: 0
        tokens_total:
          type: integer
          title: Tokens Total
          default: 0
      type: object
      title: OrchestratorStatsResponse
    ProposeActionRequest:
      properties:
        tool:
          type: string
          title: Tool
        args:
          additionalProperties: true
          type: object
          title: Args
        invoice_ref:
          type: string
          title: Invoice Ref
        reason:
          type: string
          title: Reason
          default: ''
        agent_tier:
          anyOf:
          - type: number
          - type: 'null'
          title: Agent Tier
      type: object
      required:
      - tool
      - invoice_ref
      title: ProposeActionRequest
      description: Request body for POST /v1/orchestrator/agents/{agent_id}/propose (Phase 2, PR-0).