Accept Graphs API
The Graphs API from Accept — 2 operation(s) for graphs.
OpenAPI Specification
openapi: 3.1.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:
AuthorityGraphSeverityRollupValue:
type: string
description: 'Severity-rollup vocabulary used by DiagnosticSummary.highest_severity and SurfaceAuthorityPosture.highest_severity. The three non-"none" values share string identity with AuthorityGraphDiagnosticSeverity.
'
enum:
- none
- info
- warning
- critical
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'
AuthorityGraphDiagnostic:
type: object
description: 'One operator-actionable condition observed during projection. node_refs identifies the entities the diagnostic applies to (most-specific entity first, supporting context refs trailing).
'
required:
- kind
- severity
properties:
kind:
$ref: '#/components/schemas/AuthorityGraphDiagnosticKind'
severity:
$ref: '#/components/schemas/AuthorityGraphDiagnosticSeverity'
node_refs:
type: array
items:
$ref: '#/components/schemas/AuthorityGraphNodeRef'
message:
type: string
ContextGraphExternalRefData:
type: object
description: 'External reference structure mirroring the governance-map external_ref wire shape (httpapi.externalRefResponse). Same field names and JSON tags so consumers can share parsing logic across both endpoints.
'
required:
- source_system
- source_id
properties:
source_system:
type: string
source_id:
type: string
source_url:
type: string
source_version:
type: string
last_synced_at:
type: string
format: date-time
description: RFC3339 UTC timestamp.
ContextGraphAuthoritySummaryData:
type: object
description: 'Typed data for the synthetic `authority_summary` node. Mirrors the governance-map AuthoritySummary DTO field-for-field so the values are directly comparable across both endpoints.
'
required:
- surface_count
- active_profile_count
- active_grant_count
- active_agent_count
properties:
surface_count:
type: integer
active_profile_count:
type: integer
active_grant_count:
type: integer
active_agent_count:
type: integer
AuthorityGraphFailModePolicyStatus:
type: string
description: 'Surface-level fail-mode posture. "override" — surface''s own FailModePolicyID resolved. "inherited" — BS default supplies the effective policy. "missing" — no effective policy at any level. "dangling" — any non-empty policy reference (surface override or BS default) failed to resolve. Dangling wins over inherited and missing.
'
enum:
- override
- inherited
- missing
- dangling
AuthorityGraphValidityStatus:
type: string
description: 'Time-window classification an authority profile or grant carries on its typed data. Emitted nodes always carry "effective"; future-dated and expired entities are filtered out of the node set and produce diagnostics instead.
'
enum:
- effective
- future_dated
- expired
AuthorityGraphConsequenceThreshold:
type: object
description: 'Typed value object representing an authority profile''s consequence threshold. Exactly one variant is populated based on type — monetary (amount + currency) or risk_rating (risk_rating). monetary is the canonical control-plane/API value for amount/currency thresholds; financial is accepted as a compatibility alias in control-plane Profile bundle input and is persisted as the Postgres storage value. Profile reads and graph projections use the canonical monetary form.
'
required:
- type
properties:
type:
type: string
enum:
- monetary
- financial
- risk_rating
description: 'monetary is canonical, financial is a compatibility alias for control-plane Profile bundle input, and risk_rating uses the risk_rating field.
'
amount:
type: number
currency:
type: string
risk_rating:
type: string
AuthorityGraphSurfaceAuthorityPosture:
type: object
description: 'Per-surface authority posture (D31m). One record per emitted active decision surface in the FULL pre-depth-filter projection. Frontends consume this to render per-surface health without walking edges or interpreting diagnostics.
'
required:
- surface
- authority_status
- profile_status
- grant_status
- agent_status
- fail_mode_policy_status
- escalation_status
- complete_paths
- incomplete_paths
- highest_severity
properties:
surface:
$ref: '#/components/schemas/AuthorityGraphNodeRef'
authority_status:
$ref: '#/components/schemas/AuthorityGraphAuthorityStatus'
profile_status:
$ref: '#/components/schemas/AuthorityGraphProfileStatus'
grant_status:
$ref: '#/components/schemas/AuthorityGraphGrantStatus'
agent_status:
$ref: '#/components/schemas/AuthorityGraphAgentStatus'
fail_mode_policy_status:
$ref: '#/components/schemas/AuthorityGraphFailModePolicyStatus'
escalation_status:
$ref: '#/components/schemas/AuthorityGraphEscalationStatus'
complete_paths:
type: integer
incomplete_paths:
type: integer
highest_severity:
$ref: '#/components/schemas/AuthorityGraphSeverityRollupValue'
diagnostic_kinds:
type: array
items:
$ref: '#/components/schemas/AuthorityGraphDiagnosticKind'
description: 'Unique diagnostic kinds whose NodeRefs associate with this surface (direct surface ref, or profile/grant/agent ref anchored to this surface). Sorted alphabetically.
'
AuthorityGraphNodeRef:
type: object
description: 'Reference to a node by its (kind, id) pair. Used by edge endpoints and the projection root.
'
required:
- kind
- id
properties:
kind:
type: string
description: Node kind (one of the AuthorityGraphNode kinds).
enum:
- business_service
- decision_surface
- authority_profile
- authority_grant
- agent
- fail_mode_policy
id:
type: string
AuthorityGraphFailModePolicyData:
type: object
description: 'Typed data for a fail_mode_policy node. Carries identity, lifecycle, and ownership; the full Rules array is omitted (operator-noisy) but the per-class rule count is exposed so operators see coverage at a glance.
'
required:
- id
- version
- name
- status
- managed
properties:
id:
type: string
version:
type: integer
name:
type: string
status:
type: string
effective_date:
type: string
format: date-time
effective_until:
type: string
format: date-time
description: 'Validity-window upper bound. Policy version is no longer active at or after this instant.
'
business_owner:
type: string
technical_owner:
type: string
origin:
type: string
managed:
type: boolean
rule_count_by_class:
$ref: '#/components/schemas/AuthorityGraphRuleCountByClass'
AuthorityConstraint:
type: object
description: 'One typed runtime constraint attached to an AuthorityGrant. The orchestrator evaluates each constraint on every request; the first violation rejects with reason_code CONSTRAINT_VIOLATED and emits an AUTHORITY_CONSTRAINT_VIOLATED audit event.
'
required:
- kind
properties:
kind:
$ref: '#/components/schemas/AuthorityConstraintKind'
min_confidence:
type: number
description: 'confidence_threshold_min variant: minimum allowed request.confidence (in [0,1]).
'
max_consequence:
$ref: '#/components/schemas/AuthorityGraphConsequenceThreshold'
start_time:
type: string
format: date-time
description: 'time_window variant: inclusive lower bound of the permitted window.
'
end_time:
type: string
format: date-time
description: 'time_window variant: exclusive upper bound of the permitted window.
'
AuthorityGraphEffectivePolicySource:
type: string
description: 'Resolved fail-mode-policy origin per decision surface. "override" — the surface had a non-empty FailModePolicyID that resolved to an active version. "business_service_default" — the surface inherits from the BS-level default (surface had no override OR its override was dangling). "none" — no effective fail-mode policy resolves for this surface.
'
enum:
- override
- business_service_default
- none
ContextGraphCoverageData:
type: object
description: 'Typed data for the synthetic `coverage` node. Mirrors the governance-map Coverage DTO (Phase 9 explicit field naming); the three AI-binding counters are mutually exclusive at the surface level and sum to surface_count by construction.
'
required:
- surface_count
- surfaces_with_direct_ai_binding
- surfaces_with_scoped_ai_binding
- surfaces_with_no_ai_binding
properties:
surface_count:
type: integer
surfaces_with_direct_ai_binding:
type: integer
surfaces_with_scoped_ai_binding:
type: integer
surfaces_with_no_ai_binding:
type: integer
AuthorityGraphDiagnosticSeverity:
type: string
description: Operator-facing severity for diagnostics.
enum:
- info
-
# --- 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