Accept Graphs API

openapi: 3.2.0
info:
  title: MIDAS Agents Graphs API
  version: 1.1.0-rc.1
  description: 'Authority governance engine for autonomous decisions. Every evaluation produces exactly one outcome and one tamper-evident audit envelope.

    '
servers:
- url: http://localhost:8080
  description: Local development
security:
- BearerAuth: []
tags:
- name: Graphs
paths:
  /v1/graphs/context:
    get:
      operationId: getContextGraph
      summary: Project a depth-bounded Context Graph rooted at an entity
      description: 'Returns a generic node/edge projection of business and operational context rooted at the entity identified by (view, id). Supported views: `service` (rooted at a BusinessService), `ai_system` (rooted at an AI system), `decision_surface` (rooted at a surface).

        Node kinds: business_service, related_business_service, capability, process, decision_surface, ai_system, ai_system_binding, authority_summary, coverage.

        Edge kinds (all directed): relates_to, has_capability, has_process, has_surface, bound_to (ai_system_binding to most-specific scope), system_of (ai_system_binding to ai_system), summarises, reports_coverage.

        The `depth` parameter is interpreted as undirected BFS hops from the root. Default is 3; values above 5 are silently clamped to 5. Per-entity authority detail (authority_profile, authority_grant, agent, fail_mode_policy) is intentionally absent from the Context Graph and will be first-class on the future /v1/graphs/authority endpoint.

        '
      parameters:
      - name: view
        in: query
        required: true
        schema:
          type: string
          enum:
          - service
          - ai_system
          - decision_surface
        description: 'Perspective. `service` is rooted at a business service. `ai_system` is rooted at an AI system and walks bindings to their scope targets. `decision_surface` is rooted at a surface and emits parent process / business service plus AI systems bound directly to the surface.

          '
      - name: id
        in: query
        required: true
        schema:
          type: string
        description: 'Root entity id. For view=service this is the business_service id.

          '
      - name: depth
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 5
          default: 3
        description: 'Maximum BFS hops from the root, treating edges as undirected. Values above 5 are silently clamped to 5; negative or non-numeric values return 400.

          '
      responses:
        '200':
          description: Context Graph projection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextGraphProjection'
        '400':
          description: Invalid view, id, or depth
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role (requires platform.viewer or above)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Root entity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Wrong HTTP method (only GET allowed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Context graph projection service not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Graphs
  /v1/graphs/authority:
    get:
      operationId: getAuthorityGraph
      summary: Project a depth-bounded Authority Graph rooted at a business service
      description: 'Returns a generic node/edge projection of the authority spine rooted at a business service. Answers the operator question: "for this business service, which decision surfaces are governed by which authority profiles, which grants, which agents, and which fail-mode policies?"

        Node kinds (7): business_service, decision_surface, authority_profile, authority_grant, agent, fail_mode_policy, escalation_target.

        Edge kinds (7, all directed): business_service_has_surface (bs → surface), surface_uses_profile (surface → profile), profile_has_grant (profile → grant), grant_authorises_agent (grant → agent), surface_has_fail_mode_policy (surface → policy, label="override"), business_service_has_fail_mode_policy (bs → policy, label="default"), profile_escalates_to (profile → escalation_target).

        Process nodes are intentionally not projected — the BS → Surface relationship is collapsed into a single edge. The Surface node''s typed data carries process_id for traceability.

        Fail-mode policies are resolved at request time via the FailModePolicies repository''s active-version lookup; missing active versions are skipped defensively without emitting a warning.

        The `depth` parameter is interpreted as undirected BFS hops from the root. Default is 4 (one higher than the Context Graph''s 3) so the default view reaches agent nodes at the end of the BS → Surface → Profile → Grant → Agent chain. Values above 5 are silently clamped to 5.

        MVP supports view=service only. Per-entity views (agent, surface) are reserved for later tranches.

        '
      parameters:
      - name: view
        in: query
        required: true
        schema:
          type: string
          enum:
          - service
        description: 'Perspective. Only `service` is supported at MVP — root at a business service and walk the authority spine.

          '
      - name: id
        in: query
        required: true
        schema:
          type: string
        description: 'Root entity id. For view=service this is the business_service id.

          '
      - name: depth
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 5
          default: 4
        description: 'Maximum BFS hops from the root, treating edges as undirected. Default 4 reaches agent nodes. Values above 5 are silently clamped to 5; negative or non-numeric values return 400.

          '
      responses:
        '200':
          description: Authority Graph projection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorityGraphProjection'
              examples:
                healthy_authority_graph:
                  summary: Healthy authority graph with no diagnostics
                  description: 'Single business service with one surface, one profile, one grant, one active agent, and a resolved escalation target. No diagnostics → all rollup counters are zero; surface posture reports authority_status=complete and highest_severity=none.

                    '
                  value:
                    root:
                      kind: business_service
                      id: bs-1
                    view: service
                    depth: 4
                    nodes:
                    - kind: business_service
                      id: bs-1
                      label: BS One
                    - kind: decision_surface
                      id: surf-1
                      label: Surface One
                    - kind: authority_profile
                      id: prof-1
                      label: Profile One
                    - kind: authority_grant
                      id: grant-1
                      label: grant-1
                    - kind: agent
                      id: agent-1
                      label: Agent One
                    - kind: escalation_target
                      id: et-1
                      label: Governance Approver
                    edges:
                    - kind: business_service_has_surface
                      src:
                        kind: business_service
                        id: bs-1
                      dst:
                        kind: decision_surface
                        id: surf-1
                    - kind: surface_uses_profile
                      src:
                        kind: decision_surface
                        id: surf-1
                      dst:
                        kind: authority_profile
                        id: prof-1
                    - kind: profile_has_grant
                      src:
                        kind: authority_profile
                        id: prof-1
                      dst:
                        kind: authority_grant
                        id: grant-1
                    - kind: grant_authorises_agent
                      src:
                        kind: authority_grant
                        id: grant-1
                      dst:
                        kind: agent
                        id: agent-1
                    - kind: profile_escalates_to
                      src:
                        kind: authority_profile
                        id: prof-1
                      dst:
                        kind: escalation_target
                        id: et-1
                    summary:
                      surface_count: 1
                      active_profile_count: 1
                      active_grant_count: 1
                      active_agent_count: 1
                      fail_mode_policy_count: 0
                      complete_authority_paths: 1
                      incomplete_authority_paths: 0
                      surfaces_with_policy_override: 0
                      surfaces_inheriting_bs_policy: 0
                      grants_with_stop_capability: 0
                      grants_with_constraints: 0
                      escalation_target_count: 1
                      profiles_with_escalation_target: 1
                    diagnostics: []
                    diagnostic_summary:
                      info: 0
                      warning: 0
                      critical: 0
                      highest_severity: none
                    surface_posture:
                    - surface:
                        kind: decision_surface
                        id: surf-1
                      authority_status: complete
                      profile_status: covered
                      grant_status: covered
                      agent_status: covered
                      fail_mode_policy_status: missing
                      escalation_status: targeted
                      complete_paths: 1
                      incomplete_paths: 0
                      highest_severity: none
                mixed_diagnostics_authority_graph:
                  summary: Authority graph with both warning and critical diagnostics
                  description: 'A surface with an inactive agent (critical) and a grant carrying no capabilities (warning). The rollup highest_severity is critical and the affected surface posture reports authority_status=degraded.

                    '
                  value:
                    root:
                      kind: business_service
                      id: bs-1
                    view: service
                    depth: 4
                    nodes:
                    - kind: business_service
                      id: bs-1
                      label: BS One
                    - kind: decision_surface
                      id: surf-1
                      label: Surface One
                    - kind: authority_profile
                      id: prof-1
                      label: Profile One
                    - kind: authority_grant
                      id: grant-1
                      label: grant-1
                    - kind: agent
                      id: agent-1
                      label: Suspended Agent
                    edges:
                    - kind: business_service_has_surface
                      src:
                        kind: business_service
                        id: bs-1
                      dst:
                        kind: decision_surface
                        id: surf-1
                    - kind: surface_uses_profile
                      src:
                        kind: decision_surface
                        id: surf-1
                      dst:
                        kind: authority_profile
                        id: prof-1
                    - kind: profile_has_grant
                      src:
                        kind: authority_profile
                        id: prof-1
                      dst:
                        kind: authority_grant
                        id: grant-1
                    - kind: grant_authorises_agent
                      src:
                        kind: authority_grant
                        id: grant-1
                      dst:
                        kind: agent
                        id: agent-1
                    summary:
                      surface_count: 1
                      active_profile_count: 1
                      active_grant_count: 1
                      active_agent_count: 1
                      fail_mode_policy_count: 0
                      complete_authority_paths: 1
                      incomplete_authority_paths: 0
                      surfaces_with_policy_override: 0
                      surfaces_inheriting_bs_policy: 0
                      grants_with_stop_capability: 0
                      grants_with_constraints: 0
                      escalation_target_count: 0
                      profiles_with_escalation_target: 0
                    diagnostics:
                    - kind: grant_references_inactive_agent
                      severity: critical
                      node_refs:
                      - kind: authority_grant
                        id: grant-1
                      - kind: agent
                        id: agent-1
                      message: grant "grant-1" references agent "agent-1" whose operational_state is "suspended"; runtime authority will be blocked
                    - kind: grant_has_no_capabilities
                      severity: warning
                      node_refs:
                      - kind: authority_grant
                        id: grant-1
                      message: authority grant "grant-1" carries no capabilities — orchestrator capability checks against it always reject
                    - kind: profile_has_no_escalation_target
                      severity: info
                      node_refs:
                      - kind: authority_profile
                        id: prof-1
                      message: authority profile "prof-1" has no explicit escalation target; escalation will preserve the current outcome without target routing
                    diagnostic_summary:
                      info: 1
                      warning: 1
                      critical: 1
                      highest_severity: critical
                      by_kind:
                        grant_references_inactive_agent: 1
                        grant_has_no_capabilities: 1
                        profile_has_no_escalation_target: 1
                    surface_posture:
                    - surface:
                        kind: decision_surface
                        id: surf-1
                      authority_status: degraded
                      profile_status: covered
                      grant_status: covered
                      agent_status: blocked
                      fail_mode_policy_status: missing
                      escalation_status: not_targeted
                      complete_paths: 1
                      incomplete_paths: 0
                      highest_severity: critical
                      diagnostic_kinds:
                      - grant_has_no_capabilities
                      - grant_references_inactive_agent
                      - profile_has_no_escalation_target
                dangling_escalation_target_authority_graph:
                  summary: Authority graph with a dangling escalation target reference
                  description: 'A profile references an EscalationTarget id that does not resolve to an active version. No escalation_target node is emitted (no active target exists); the surface posture reports escalation_status=dangling and the rollup carries one warning.

                    '
                  value:
                    root:
                      kind: business_service
                      id: bs-1
                    view: service
                    depth: 4
                    nodes:
                    - kind: business_service
                      id: bs-1
                      label: BS One
                    - kind: decision_surface
                      id: surf-1
                      label: Surface One
                    - kind: authority_profile
                      id: prof-1
                      label: Profile One
                    - kind: authority_grant
                      id: grant-1
                      label: grant-1
                    - kind: agent
                      id: agent-1
                      label: Agent One
                    edges:
                    - kind: business_service_has_surface
                      src:
                        kind: business_service
                        id: bs-1
                      dst:
                        kind: decision_surface
                        id: surf-1
                    - kind: surface_uses_profile
                      src:
                        kind: decision_surface
                        id: surf-1
                      dst:
                        kind: authority_profile
                        id: prof-1
                    - kind: profile_has_grant
                      src:
                        kind: authority_profile
                        id: prof-1
                      dst:
                        kind: authority_grant
                        id: grant-1
                    - kind: grant_authorises_agent
                      src:
                        kind: authority_grant
                        id: grant-1
                      dst:
                        kind: agent
                        id: agent-1
                    summary:
                      surface_count: 1
                      active_profile_count: 1
                      active_grant_count: 1
                      active_agent_count: 1
                      fail_mode_policy_count: 0
                      complete_authority_paths: 1
                      incomplete_authority_paths: 0
                      surfaces_with_policy_override: 0
                      surfaces_inheriting_bs_policy: 0
                      grants_with_stop_capability: 0
                      grants_with_constraints: 0
                      escalation_target_count: 0
                      profiles_with_escalation_target: 0
                      profiles_with_dangling_escalation_target:
                      - kind: authority_profile
                        id: prof-1
                    diagnostics:
                    - kind: escalation_target_reference_dangling
                      severity: warning
                      node_refs:
                      - kind: authority_profile
                        id: prof-1
                      - kind: escalation_target
                        id: et-missing
                      message: authority profile "prof-1" references escalation target "et-missing", but no active version is available
                    diagnostic_summary:
                      info: 0
                      warning: 1
                      critical: 0
                      highest_severity: warning
                      by_kind:
                        escalation_target_reference_dangling: 1
                    surface_posture:
                    - surface:
                        kind: decision_surface
                        id: surf-1
                      authority_status: degraded
                      profile_status: covered
                      grant_status: covered
                      agent_status: covered
                      fail_mode_policy_status: missing
                      escalation_status: dangling
                      complete_paths: 1
                      incomplete_paths: 0
                      highest_severity: warning
                      diagnostic_kinds:
                      - escalation_target_reference_dangling
        '400':
          description: Invalid view, id, or depth
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role (requires platform.viewer or above)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Root business service not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Wrong HTTP method (only GET allowed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Authority graph projection service not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Graphs
components:
  schemas:
    AuthorityConstraintKind:
      type: string
      description: 'Discriminator for the AuthorityConstraint value object. Each kind populates exactly the fields relevant to its variant:


        - confidence_threshold_min:  uses min_confidence

        - consequence_threshold_max: uses max_consequence

        - human_only / ai_only:      no payload fields

        - time_window:               uses start_time + end_time

        '
      enum:
      - confidence_threshold_min
      - consequence_threshold_max
      - human_only
      - ai_only
      - time_window
    ContextGraphProjection:
      type: object
      description: 'Top-level response shape for GET /v1/graphs/context. Nodes are sorted by (kind, id) ascending; edges are sorted by (kind, src.kind, src.id, dst.kind, dst.id) ascending. Both arrays are always present (never null); an empty depth=0 projection still carries the root in `nodes`.

        '
      required:
      - root
      - view
      - depth
      - nodes
      - edges
      properties:
        root:
          $ref: '#/components/schemas/ContextGraphNodeRef'
        view:
          type: string
          enum:
          - service
          - ai_system
          - decision_surface
          description: 'Perspective the projection was computed in. `service` projects from a business-service root via the governance-map read service. `ai_system` projects from an AI-system root by walking bindings to their scope targets. `decision_surface` projects from a surface root and emits its parent process / business service plus AI systems bound directly to the surface. Future views (agent, risk) are reserved.

            '
        depth:
          type: integer
          minimum: 0
          maximum: 5
          description: 'Effective depth (BFS hops from root, undirected) used to compute the projection. Equals the requested depth when in range, or the silent clamp value (5) when the request exceeded the maximum.

            '
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/ContextGraphNode'
        edges:
          type: array
          items:
            $ref: '#/components/schemas/ContextGraphEdge'
    ContextGraphCapabilityData:
      type: object
      description: Typed data for a node of kind `capability`.
      required:
      - id
      - name
      - status
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        status:
          type: string
        owner:
          type: string
        parent_capability_id:
          type: string
        external_ref:
          $ref: '#/components/schemas/ContextGraphExternalRefData'
    AuthorityGraphAuthorityGrantData:
      type: object
      description: 'Typed data for an authority_grant node. Grant references the profile by logical id (not by version). Noisy lifecycle fields (suspend/revoke metadata, GrantReason) are intentionally excluded from the graph wire shape.


        D31i adds `capabilities` and `constraints`. Capabilities is the SET of canonical Capability values the grant authorises (omitempty when empty — the projection also emits a grant_has_no_capabilities warning diagnostic). Constraints is the typed list of grant constraints (omitempty when empty).

        '
      required:
      - id
      - profile_id
      - agent_id
      - status
      properties:
        id:
          type: string
        profile_id:
          type: string
        agent_id:
          type: string
        status:
          type: string
        effective_date:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        validity_status:
          $ref: '#/components/schemas/AuthorityGraphValidityStatus'
        granted_by:
          type: string
        capabilities:
          type: array
          items:
            $ref: '#/components/schemas/AuthorityCapability'
          description: 'The SET of authority Capability values this grant authorises. Empty / omitted when the grant carries no capabilities.

            '
        constraints:
          type: array
          items:
            $ref: '#/components/schemas/AuthorityConstraint'
          description: 'Typed runtime constraints that narrow the grant on every request. Empty / omitted when the grant has no constraints.

            '
    AuthorityGraphProfileStatus:
      type: string
      description: 'Surface-level profile coverage. "covered" when at least one effective profile attaches to the surface; "missing" otherwise.

        '
      enum:
      - covered
      - missing
    ContextGraphAISystemData:
      type: object
      description: 'Typed data for a node of kind `ai_system`. `active_version`, `active_version_label`, and `active_version_status` are populated when the AI system has an active version on the governance map, omitted otherwise.

        '
      required:
      - id
      - name
      - status
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        status:
          type: string
        vendor:
          type: string
        system_type:
          type: string
        active_version:
          type: integer
          description: The integer version number of the active AISystemVersion. Omitted when no active version exists.
        active_version_label:
          type: string
          description: Optional release label associated with the active version.
        active_version_status:
          type: string
          description: Status of the active AISystemVersion (e.g. draft, active, retired). Mirrors the governance-map ai_systems[].active_version.status field.
        external_ref:
          $ref: '#/components/schemas/ContextGraphExternalRefData'
    AuthorityGraphSummary:
      type: object
      description: 'Backend-computed posture rollup for a service-view Authority Graph projection. Count fields are always present; per-entity gap lists use omitempty. Summary describes the FULL pre-depth-filter projection — operators at depth=0 still see the authority posture.

        '
      required:
      - surface_count
      - active_profile_count
      - active_grant_count
      - active_agent_count
      - fail_mode_policy_count
      - complete_authority_paths
      - incomplete_authority_paths
      - surfaces_with_policy_override
      - surfaces_inheriting_bs_policy
      - grants_with_stop_capability
      - grants_with_constraints
      - escalation_target_count
      - profiles_with_escalation_target
      properties:
        surface_count:
          type: integer
        active_profile_count:
          type: integer
        active_grant_count:
          type: integer
        active_agent_count:
          type: integer
        fail_mode_policy_count:
          type: integer
        complete_authority_paths:
          type: integer
          description: 'Surfaces with at least one effective profile → effective grant → resolved agent chain. Counted per surface, not per chain.

            '
        incomplete_authority_paths:
          type: integer
          description: 'Emitted surfaces with no complete authority path.

            '
        surfaces_without_profiles:
          type: array
          items:
            $ref: '#/components/schemas/AuthorityGraphNodeRef'
        profiles_without_grants:
          type: array
          items:
            $ref: '#/components/schemas/AuthorityGraphNodeRef'
        grants_without_agents:
          type: array
          items:
            $ref: '#/components/schemas/AuthorityGraphNodeRef'
        surfaces_without_effective_fail_mode_policy:
          type: array
          items:
            $ref: '#/components/schemas/AuthorityGraphNodeRef'
        surfaces_with_policy_override:
          type: integer
        surfaces_inheriting_bs_policy:
          type: integer
        policies_missing_active_version:
          type: array
          items:
            $ref: '#/components/schemas/AuthorityGraphNodeRef'
          description: 'Deduped fail-mode-policy NodeRefs that were referenced (at BS or surface level) but had no active version. The entries are NodeRefs even though no fail_mode_policy node is emitted for them.

            '
        grants_with_stop_capability:
          type: integer
          description: 'Count of emitted authority_grant nodes whose capabilities slice contains "stop".

            '
        grants_with_constraints:
          type: integer
          description: 'Count of emitted authority_grant nodes that carry at least one Constraint.

            '
        grants_without_capabilities:
          type: array
          items:
            $ref: '#/components/schemas/AuthorityGraphNodeRef'
          description: 'Emitted grants that carry zero Capabilities. Paired with the grant_has_no_capabilities warning diagnostic.

            '
        escalation_target_count:
          type: integer
          description: 'Count of deduped escalation_target nodes emitted in the full pre-depth-filter projection (D31l).

            '
        profiles_with_escalation_target:
          type: integer
          description: 'Count of effective profiles whose EscalationTargetID resolved to an active escalation target.

            '
        profiles_without_escalation_target:
          type: array
          items:
            $ref: '#/components/schemas/AuthorityGraphNodeRef'
          description: 'Effective profiles with an empty EscalationTargetID. Paired with the profile_has_no_escalation_target info diagnostic.

            '
        profiles_with_dangling_escalation_target:
          type: array
          items:
            $ref: '#/components/schemas/AuthorityGraphNodeRef'
          description: 'Effective profiles whose configured EscalationTargetID did not resolve to an active target. Paired with the escalation_target_reference_dangling warning diagnostic.

            '
    AuthorityGraphEscalationStatus:
      type: string
      description: 'Surface-level escalation routing posture. "targeted" — at least one effective profile under the surface references an active EscalationTarget. "not_targeted" — no profile has an explicit target. "dangling" — at least one profile references a target id that does not resolve. Dangling wins over targeted.

        '
      enum:
      - targeted
      - not_targeted
      - dangling
    ContextGraphRelatedBusinessServiceData:
      type: object
      description: 'Typed data for a node 

# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/accept/refs/heads/main/openapi/accept-graphs-api-openapi.yml