Developer reference
Model Monster API Reference
Build and validate CORE system blueprints through the external REST API or MCP server. Use this reference to find endpoints, sync payload fields, type tags, risk tags, and modeling guidance.
Start here
Fast pathUse this path when you are building a customer proof of concept or wiring an agent to Model Monster for the first time.
Get an API key
Create a key from Settings > API Keys or Developers > API Keys, then send it with each request as a bearer token.
2Follow the workflow
Understand the order for reading context, choosing tags, validating, and syncing graph changes.
3Validate the payload
Check required sync fields and expand only the schema fragments you need.
4Resolve guidance
Map validation and sync responses to clear next actions without reading every rule upfront.
Authentication
Bearer API key
Model Monster API and MCP requests use an API key in the
Authorization
header. Create a key from
Settings > API Keys
or
Developers > API Keys, copy the raw value when it is shown, and store it in your server or agent environment.
Keys inherit the user's access. For customer POCs and agent integrations, prefer scoped keys for the organization, team, or system being tested. Rotate or revoke keys from the same API Keys screen.
curl "https://api.modelmonster.ai/api/v1/reference/modeling-guide" \
-H "Authorization: Bearer ${MM_API_KEY}" \
-H "Accept: application/json"Overview
13 reference entriesThe API lets developers and agents discover organizations, read the current system graph, classify components and resources, validate sync payloads, and apply graph updates. The model is intentionally explicit: nodes use stable instance UUIDs, edges are unidirectional, and risk travels through payload edges.
Components
Software and AI building blocks that process or route information.
Resources
Organizational data, systems, and networks that components interact with. Resources carry inherent risk based on what they contain.
Operations
Control Edges
Payload edges model real execution/data flow. Nonflow components use control-topology edges plus applied_controls on payload edges.
Tag Propagation
Risk tags move along payload edges and can be added, removed, or consumed by nodes. A scoped-read tag may cross one declared component edge through conveys_tags before a component consumes it.
Graph Structure
Reference endpoints
REST and MCP alignedStart with the modeling guide and schema, then use the specialized reference endpoints as needed while authoring or validating a graph sync.
Step-by-step workflow for building system blueprints. Read this first.
Current read-first guidance bundle and non-secret guidance_version recommended for gated writes; required when the guidance gate is in enforce mode.
Canonical field guide for repo-owned private PURLs, repo_path, and collision handling.
CORE framework vocabulary for components, resources, operations, and edges.
Faceted classification taxonomy, lifted type presets, and node classification guide.
Risk tag categories and default add/remove behavior by type tags.
Catalog of agent-visible guidance types, default actions, and reference links.
Field guidance plus canonical sync and schema-2.0 execution-flow JSON Schemas.
Optional structural guidance for component placement, data-flow changes, configuration changes, and their evidence limits.
Schema-2.0 execution-flow evidence plus separate current component-placement advice. Follow page.next_cursor until page.has_more is false; start large systems with view=summary.
Recovery/warming recompute of derived execution-flow state for the current editable draft. Editor reads refresh transparently; call this only on recompute_then_retry guidance.
Dedicated read/write endpoint for authored phase-route family edge exclusions.
Markdown export of the full reference catalog, including guidance.
Modeling workflow
5 steps
You are building a CORE system blueprint — a directed graph of components
and resources that describes how data flows through an AI system and where
risk enters, propagates, and is mitigated.
Work outside-in: boundaries first, then processing, then completeness.
Draw the boundaries
Goal: Identify every resource the system touches.
Read guidance
Resources are where risk lives. Start here because they frame everything else.
Network boundaries (type: network):
Internet — anything beyond organizational control
Intranet — internal network, still crosses team boundaries
Local — same host / same trust domain
When you sync these shared boundary resources, prefer canonical_zone: internet | intranet | local instead of inventing bespoke resource names or metadata.
If a component creates or enforces a trust boundary (e.g., an ingress proxy that is the only path to backend services, a WAF that filters malicious traffic), it belongs in the blueprint. The boundary enforcement IS the risk-relevant behavior.
Data stores (type: data):
Databases, object stores, caches, file systems, vector stores.
Each distinct store is its own resource — "the PostgreSQL database" not "PostgreSQL the software."
External systems (type: system):
Third-party platforms the system interacts with (Google Drive, Slack, Jira, Salesforce). These are resources because you consume their data, not because you install them.
For each resource, assign:
classification — public / internal / confidential / restricted
risk_tags — what risk does data flowing from or through this resource carry?
Risk tags cover two dimensions:
Data sensitivity — pii, phi, credential, confidential, etc.
Trust / exposure — untrusted, unvalidated, adversarial, abuse
Network resources almost always carry trust tags:
Internet → defaults: [untrusted, adversarial, unauthenticated, unvalidated, malicious, abuse]
Intranet → risk_tags: [untrusted] (cross-team, not adversarial)
Local → typically no trust tags (same trust domain)
Trace input provenance
Goal: Understand where data enters the system and what trust it carries.
Read guidance
Every system has at least one input. Ask:
Who or what provides the input?
Human user → likely untrusted, unvalidated, possibly adversarial
Another API → untrusted, unvalidated, possibly adversarial
Another AI → add ai-generated, unverified on top of the above
Internal scheduled job → may be more trusted, still unvalidated
These trust properties are risk_tags on the source resource (the network boundary or external system), not adds_tags on the first component that receives them. Components downstream then mitigate these risks via removes_tags (e.g., an auth gateway removes unauthenticated; a WAF removes adversarial).
The input point is usually a component (an API endpoint, a webhook handler, a file ingestion service). It connects to a network-type resource representing where the input comes from.
This step often reveals components and resources you missed:
"Wait, there's also a webhook from Stripe" → new input component
+ Internet resource.
Map the processing chain
Goal: Identify every component between inputs and outputs.
Read guidance
Walk the data path from each input to each output. For each candidate, follow this sequence:
3a. Classify — is it a component or a resource?
Install it? → component
Connect to it? → component
Use it to connect? → component + resource pair
Data behind it? → resource
(See type-tags reference for the full decision tree.)
3b. Prune — apply both tests before including:
1. Does it transform, filter, or enrich data in transit?
2. Does it gate access, enforce authentication, terminate encryption, or limit exposure?
If BOTH answers are no, leave it out.
Include infrastructure that enforces security boundaries:
WAF / anti-DDoS → removes exposure to raw internet
TLS-terminating proxy → creates a trust boundary
Auth gateway → transforms unauthenticated to authenticated
Rate limiter → mitigates abuse risk
Exclude infrastructure that only passes through:
A reverse proxy that forwards requests unchanged
A CDN that caches static assets without filtering
A container runtime or orchestrator
3c. Search the registry before creating any node.
Use the search tool with the component name (e.g., "PostgreSQL", "Claude", "Cloudflare").
Catalog purl found → include the component's purl in the sync node and omit type_tags unless you need to override them. Matching purls inherit curated type_tags, name, and vendor metadata automatically; default risk behavior follows from the inherited type_tags.
Catalog referent_uuid found → do NOT send it to sync. It is a catalog identity, not a savefile referent, and sync will reject it with not_found_referent. Use the component's purl instead.
No match → create an ad-hoc node and continue to 3d.
3d. Assign identity and type_tags (ad-hoc nodes only).
Tags span five facets — use all that apply:
scope — exactly one: local | internal | external | unknown
type — at least one: model, guardrail, security, storage, orchestrator, integration, processor, router, input, output, observability, transformer
subtype — mechanism: llm, embedding, classifier, filter, detector, validator, auth, waf, database, cache, agent, retriever, parser, chunker, etc.
domain — what it handles: text, code, image, pii, injection, toxicity, credential, schema, etc.
interface — how you connect: api, sdk, ui, stream, webhook, grpc
The system auto-applies default adds_tags/removes_tags based on
type_tags. Getting them right is essential — they drive the risk model. Examples:
[external, model, llm, text, api] → adds [ai-generated, unverified]
[internal, guardrail, filter, pii] → removes [pii]
[internal, guardrail, detector, injection] → removes [adversarial]
[external, security, auth, api] → removes [unauthenticated]
[internal, storage, database, api] → no default risk changes
[external, orchestrator, agent, agentic] → (no default — set manually)
Give ad-hoc components a PURL identity. The PURL lets reviewers trace the component back to its implementation without guessing — include as much detail as you know.
purl_namespace — who owns it: org's reverse DNS (e.g., "ai.modelmonster", "com.acme")
repo_path — where to find it: repo or workspace path (e.g., "monorepo/support-bot", "apps/tenant_router")
purl_name — what it is: service or module within the repo (e.g., "auth-gateway", "slack-alert-sender")
purl_version — which version: semver, commit hash, or date (e.g., "1.0.0", "2f6c9ab", "2026-03-06")
At minimum provide purl_namespace and purl_name. But if you know the repo path, the version, or the commit — include them. The richer the PURL, the easier it is for a reviewer to find the actual code.
Important:
configuration is runtime node state, not referent identity.
configuration must stay shallow: values may be scalars or lists of scalars. Nested objects and nested arrays are not supported.
If you know where a repo-owned private component lives, put that repo/workspace path in repo_path, not only in configuration.repo_path.
Modeling control components:
A component that controls a flow (such as a rate limiter or
budget guardrail) is a component, but its levels — rpm, spend
cap, quota — go in its configuration. There is no throttle/rate-limit/budget facet. The component's type_tags say what it is (e.g. [internal, integration, gateway] or [internal, router, security]); the configuration says how it is tuned.
If two repo-owned private components would otherwise collide, first change the field that is actually different:
different repo/workspace path -> repo_path
different service/module name -> purl_name
different nested code path -> purl_subpath
different owning namespace -> purl_namespace
different release/build -> purl_version
Do not bump purl_version just to avoid a collision unless the component is genuinely a different version/release/build.
Provide individual purl_* fields — do not switch to internal bare names like namespace/version or construct the compact purl string yourself. The system builds it:
pkg:private/{purl_namespace}/{purl_name}@{purl_version}?repo_path={repo_path} pkg:private/ai.modelmonster/auth-gateway@2f6c9ab?repo_path=apps/auth-gateway
Common components to look for:
Models — [model, llm|embedding|classifier|generator]
Orchestrators — [orchestrator, agent|workflow|router]
Retrieval — [processor, retriever|rerank]
Integration — [integration, mcp|gateway|messaging]
Security — [security, auth|waf|firewall]
Infrastructure — [storage, cache|database|kv]
Wire the edges
Goal: Connect components and resources with typed operations.
Read guidance
Every edge between a component and a resource must have operations:
read, write, delete, execute, grant
Distinguish data from configuration:
A read edge means the resource's content enters the component and continues into the component's outputs. This is correct for data the component processes or passes on. It does not apply to configuration or authentication values that the component consumes.
Decide per edge. Other than the use of a credential to authenticate the component (for example, in an authorization header), does content from this resource appear in what the component sends or writes onward?
Yes -> normal read: resource -> component [read]. This includes stores whose records contain credential material (user databases, captured logs). Records are data. Their tags propagate, and that propagation is real risk signal.
No -> the component consumes the values. Model it in two parts:
1. Scope the read to the tags it acquires:
operations: [read], read_risk_tags: [credential]
2. Declare consumption on the component:
consumes_tags: [credential]
The consumed tags stop at the component. The system records a custody fact: this component holds this value. The flow shows as Consumed on the map.
If a middle component fetches the values and hands them to the real consumer (a gateway), declare the handoff on the connecting edge. Each entry names the tag, the secret resource, and the component that first read it:
conveys_tags: [{tag: credential, resource: <secret resource>, acquired_via: <gateway component>}]
The tags cross only that edge. If the target does not consume them, they spill as normal data and the system emits a warning.
If you declare neither consumption nor a handoff, the scoped tags propagate as normal data. This is the default. It is safe, and it produces findings that tell you where a claim is missing.
Older graphs: a graph with no read_risk_tags, consumes_tags, or conveys_tags behaves exactly as before. You do not need to update existing graphs.
Do not simulate consumption. Do not use removes_tags to erase a credential, do not route the read through an unrelated control component, and do not exclude the edge from routes. Declare the consumption, or let the tags propagate.
Example (agent with injected secrets):
Anthropic API Key -> Agent Runtime [read:credential]
Agent Runtime: consumes_tags: [credential]
Result: no credential flow past the runtime; one custody fact.
Example (gateway handoff):
Vault Secret -> MCP Gateway [read:credential]
MCP Gateway -> Chat MCP Server [conveys_tags: [{tag: credential, resource: <vault secret>, acquired_via: <mcp gateway>}]]
Chat MCP Server: consumes_tags: [credential]
Result: credential crosses one declared hop and stops; custody facts at the gateway path's end; nothing enters chat payloads.
Verify the mechanism before drawing a read from a resource with credential or restricted tags. Task definitions, IAM policies, mounts, and service configuration are edge evidence. If the component identity cannot access the resource, do not draw the edge. Draw the actual acquisition path or record the uncertainty for review.
Component-to-component edges (data flows) must NOT have operations.
Not every meaningful edge is a payload edge.
Control-topology edges are for controller-eligible components (with a control or nonflow type tag) that influence or observe a payload path:
edge_mode: observe → monitoring, logging, tracing, SIEM, or similar controls that may mirror risk-carrying data
edge_mode: guard → auth, routing, policy, or similar controls that gate the payload path without carrying it
Payload edges stay unannotated. If a controller-eligible component affects a payload edge, bind it explicitly on the payload edge with:
applied_controls:
- controller_uuid: <controller-eligible component instance_uuid>
mode: observe | guard
Use graph node instance_uuid values for controller_uuid. Do not use referent_uuid there.
Common control-edge mistakes:
edge_mode belongs only on edges that touch a controller-eligible component
applied_controls belong only on payload edges, never on the same edge as edge_mode
controller_uuid must be an active controller-eligible component instance_uuid from get_snapshot or get_node_detail, not a referent_uuid from search
A control binding affects a payload edge only when its controller has a connected control-topology corridor to the payload edge source in the authored direction. A guard corridor runs from the controller to that source. If no such path exists, the binding reports a no_path diagnostic and does not set topology-dependent guarded or observed facts. Configured tag effects may still apply. Fix the corridor or remove the binding.
When the guarded payload edge starts at a resource, fix the corridor by adding a control-topology edge from the controller to that resource: controller -> resource [grant] with edge_mode: guard. Control-mode links to a resource do not change whether the resource counts as an input or an output; only payload links do.
Edges are always unidirectional. Model the full request/response cycle explicitly when both directions matter; do not collapse a round trip into one conceptual or mixed-direction edge.
Edge endpoints always use node instance_uuid values from get_snapshot or get_node_detail. search_detail returns referent_uuid values for component/resource catalog entries, not graph edge endpoints.
For request/response systems:
Model the inward request path and the outward response path as separate directed edges.
If the response passes through output validators, formatters, filters, or adapters, model that outward path explicitly.
If a component both sends a request and receives a response from the same resource, that is two edges, not one.
Rules of thumb:
Database access → resource -> component [read];
component -> resource [write] / [delete]
API call → component -> resource [write] or [execute]
for the request; resource -> component [read]
for the response
Internet boundary → internet -> component [read] for inbound
requests; component -> internet [write] for
outbound responses; internet -> component
[execute] for callbacks or invocation paths
File storage → component -> resource [write];
resource -> component [read]
Permission system → component -> resource [grant]; add a separate
resource -> component [read] edge if policy or entitlement data comes back. When the permission system is a controller (control or nonflow type tag) and the grant only gates access, add edge_mode: guard so the edge is control topology and does not make the resource an output
Example:
Traefik -> External API payload edge, no edge_mode applied_controls:
- controller_uuid: <router-forward-auth instance_uuid>
mode: guard
Traefik -> Router ForwardAuth control-topology edge with edge_mode: guard
Check completeness
Goal: Use risk reasoning to find gaps in the model.
Read guidance
Walk the risk tags through the graph mentally:
For each resource with risk_tags, ask:
Does every path from this resource to an output pass through components that handle these risks?
Example: resource has [pii, confidential] → is there a pii filter before the data reaches an external component?
For each component with adds_tags, ask:
Are there downstream components that address what was added?
Example: LLM adds [ai-generated, unverified] → is there a factuality checker? A content filter?
For each Internet-facing input, trace the trust tags from the Internet resource through the graph. Each should be mitigated:
unauthenticated → security component with [auth] removes it
unvalidated → guardrail with [validator] removes it
adversarial → guardrail with [detector, injection] or security with [waf] removes it
malicious → security with [waf|firewall] removes it
abuse → rate limiter or anti-DDoS removes it
Common gaps:
Missing guardrails — model output goes directly to user without content filtering or validation
Missing authentication — external input accepted without identity verification
Missing data protection — pii flows to external service without filtering
Missing output validation — AI-generated content served without schema or factuality checks
These gaps are not necessarily wrong — they represent architectural decisions. But they should be intentional, not accidental.
Sync schema
8 top-level fieldsModel Monster External API Sync Payload defines the canonical JSON shape for validating and applying graph changes.
Component component.yaml
identity:
instance_uuid:
required: true
description: Client-generated UUID v4 for the graph instance.
kind:
required: true
values:
- component
referent:
referent_uuid:
required: false
description: Existing component referent UUID.
purl:
required: false
description: Package URL used to resolve an existing component or create a new
one.
purl_type:
required: false
description: Canonical PURL type field.
purl_namespace:
required: false
description: Canonical PURL namespace field.
purl_name:
required: false
description: Canonical PURL name field used for component identity.
purl_version:
required: false
description: Canonical PURL version field. Change only for a real new version/release/build.
repo_path:
required: false
description: Optional repo/workspace path for human guidance. For private PURLs
this is rendered as the repository_path qualifier, not core package identity.
purl_qualifiers:
required: false
description: Canonical PURL qualifiers field.
purl_subpath:
required: false
description: Canonical PURL subpath field.
name:
required: false
description: Canonical human-readable referent label.
classification:
type_tags:
required: false
description: Type tags. Canonical tags are recommended; custom tags are allowed
and preserved.
spdx_license_expression:
required: false
description: Shared external license field.
extra_data:
required: false
description: Structured referent metadata.
state:
display_name:
required: false
description: Display name override for this instance.
configuration:
required: false
description: Node-local runtime configuration, not referent identity. Use a shallow
object whose values are scalars or lists of scalars. Nested objects and nested
arrays are not supported.
adds_tags:
required: false
description: Risk tags this component introduces.
removes_tags:
required: false
description: Risk tags this component mitigates.
consumes_tags:
required: false
description: Configuration-channel risk tags this component consumes. Omit on
create to copy the referent default, omit on update to preserve, or send []
to clear.Resource resource.yaml
identity:
instance_uuid:
required: true
description: Client-generated UUID v4 for the graph instance.
kind:
required: true
values:
- resource
referent:
referent_uuid:
required: false
description: Existing resource referent UUID.
purl:
required: false
description: Resource package URL identity, if known.
purl_type:
required: false
description: Canonical PURL type field.
purl_namespace:
required: false
description: Canonical PURL namespace field.
purl_name:
required: false
description: Canonical PURL name field.
purl_version:
required: false
description: Canonical PURL version field. Change only for a real new version/release/build.
repo_path:
required: false
description: Optional repo/workspace path for human guidance. For private PURLs
this is rendered as the repository_path qualifier, not core package identity.
purl_qualifiers:
required: false
description: Canonical PURL qualifiers field.
purl_subpath:
required: false
description: Canonical PURL subpath field.
name:
required: false
description: Canonical human-readable referent label.
classification:
type:
required: false
values:
- data
- system
- network
classification:
required: false
values:
- public
- internal
- confidential
- restricted
canonical_zone:
required: false
values:
- internet
- intranet
- local
- local_computer
description: Prefer this for shared Internet/Intranet/Local boundary resources
instead of creating bespoke names.
risk_tags:
required: false
description: Risk tags carried by this resource. Canonical tags are recommended;
custom tags are allowed and preserved.
type_tags:
required: false
description: Optional type tags for resource characterization (custom tags allowed).
spdx_license_expression:
required: false
description: Shared external license field.
shared:
required: false
description: Explicit org-registry visibility flag for this resource referent.
state:
display_name:
required: false
description: Display name for this resource node.
configuration:
required: false
description: Resource-level runtime configuration, not referent identity. Use
a shallow object whose values are scalars or lists of scalars. Nested objects
and nested arrays are not supported.
extra_data:
required: false
description: Effective structured metadata for this resource node.Edges edges.yaml
common_validation_rules:
edge_mode_requires_nonflow: edge_mode is only valid on edges that touch a controller-eligible
component (control or nonflow type tag).
applied_controls_payload_only: applied_controls belong on payload edges, not control-topology
edges.
controller_uuid_source: controller_uuid must be a node instance_uuid from the active
graph snapshot, never a referent_uuid.
payload_edge:
description: Unannotated edge carrying real execution/data flow. Ordinary payload
edges omit edge_mode.
fields:
from:
required: true
description: Source node instance_uuid.
to:
required: true
description: Target node instance_uuid.
operations:
required: false
description: Required only when the edge connects a component and a resource.
Use read:credential,pii as input shorthand for a scoped read; snapshots return
the canonical read plus read_risk_tags shape.
read_risk_tags:
required: false
description: Non-empty canonical risk-tag scope for a read. Selected tags must
currently be assigned to the resource. Omit for an unrestricted read. Scope
filters only intrinsic resource risk tags; it does not remove carried tags
or classification.
applied_controls:
required: false
description: Controller-eligible components explicitly applied to this payload
edge. Use controller_uuid values from the active graph snapshot.
conveys_tags:
required: false
description: Non-empty canonical {tag, resource, acquired_via} selectors carried
only across this ordinary component-to-component payload edge.
control_topology_edge:
description: Edge describing control or observability topology for a controller-eligible
component. Control-topology edges are not ordinary payload edges.
fields:
from:
required: true
description: Source node instance_uuid.
to:
required: true
description: Target node instance_uuid.
edge_mode:
required: true
values:
- observe
- guard
description: Use observe for monitoring/logging-style mirroring; use guard for
controls that gate a payload path without carrying it.
applied_control:
description: Binding between a payload edge and a controller-eligible component
that affects that flow.
fields:
controller_uuid:
required: true
description: Controller node instance_uuid in the active graph. Fetch it from
get_snapshot or get_node_detail. This is never a referent_uuid.
mode:
required: true
values:
- observe
- guard
description: Use observe for monitoring/logging-style mirroring and guard for
controls that gate the payload path without carrying it.Phase Route Overrides phase_route_overrides.yaml
endpoint:
read: GET /api/v1/org/{org}/t/{team}/system/{system_uid}/phase-route-overrides
write: PATCH /api/v1/org/{org}/t/{team}/system/{system_uid}/phase-route-overrides
request:
family:
required: true
description: Phase-route family selector keyed by family_kind plus sorted member_ids.
current_exclude_edges:
required: true
description: The caller's current family-scoped exclude edge set for conflict
detection.
next_exclude_edges:
required: true
description: The full replacement family-scoped exclude edge set after the edit.
response:
phase_route_overrides:
description: 'Normalized authored sidecar payload. Empty payload is represented
as families: [].'
phase_route_override_hash:
description: Sidecar hash derived from the normalized payload. Null means no authored
overrides.
phase_route_override_diagnostics:
description: Derived family-scoped diagnostics from the latest recompute. Snapshot
responses include only the hash, not the full authored payload.Execution Flow Result Schema Documentation-grade schema for GET .../execution-flows (REST) / get_execution_flows (MCP) and POST .../execution-flows/recompute / recompute_execution_flows. Both transports return the same {ok, data, guidance} envelope; MCP additionally sets isError = !ok. Identifier crosswalk: catalog node_id/node_ids values are graph instance_uuids — pass them to get_node_detail; referent_uuid is catalog identity for search_detail only; policy_target_ids is a legacy name for graph instance UUIDs, not highlight targets; target_id/fragment_id/flow_id/branch_id are opaque and must never be parsed, shortened, or passed to node, search, or sync calls. execution_flow_result_schema.yaml
$schema: https://json-schema.org/draft/2020-12/schema
$id: https://modelmonster.ai/reference/execution_flow_result.schema.json
title: Execution-flow results (read + recompute)
description: "Documentation-grade schema for GET .../execution-flows (REST) / get_execution_flows\
\ (MCP) and POST .../execution-flows/recompute / recompute_execution_flows. Both\
\ transports return the same {ok, data, guidance} envelope; MCP additionally sets\
\ isError = !ok. Identifier crosswalk: catalog node_id/node_ids values are graph\
\ instance_uuids \u2014 pass them to get_node_detail; referent_uuid is catalog identity\
\ for search_detail only; policy_target_ids is a legacy name for graph instance\
\ UUIDs, not highlight targets; target_id/fragment_id/flow_id/branch_id are opaque\
\ and must never be parsed, shortened, or passed to node, search, or sync calls."
$defs:
action_code:
description: Closed machine-readable recovery code carried on every guidance item
from these endpoints. Clients must branch on action_code, never on message text.
type: string
enum:
- none
- correct_parameters
- restart_paging_no_cursor
- retry_with_edit_permission
- create_or_return_to_draft
- recompute_then_retry
- report_do_not_retry
- enumerate_remaining_roots
- call_get_execution_flows
- continue_paging
guidance_item:
type: object
additionalProperties: false
properties:
level:
type: string
enum:
- info
- warning
- error
type:
type: string
message:
type: string
action:
type: string
action_code:
$ref: '#/$defs/action_code'
reference:
type: string
url:
type: string
required:
- level
- type
- message
- action
- action_code
guidance_type_map:
description: 'Every execution-flow guidance type with its level and action_code.
execution_flow_evidence_incomplete is status-conditional: recompute_then_retry
on a draft, report_do_not_retry on read-only versions.'
const:
execution_flows_ready:
level: info
action_code: call_get_execution_flows
execution_flows_page_incomplete:
level: info
action_code: continue_paging
execution_flows_needs_disposition:
level: info
action_code: none
execution_flows_all_clear:
level: info
action_code: none
execution_flows_stale:
level: error
action_code: retry_with_edit_permission | recompute_then_retry
execution_flows_unavailable:
level: error
action_code: create_or_return_to_draft
execution_flows_archive_unavailable:
level: error
action_code: report_do_not_retry
execution_flows_read_only:
level: error
action_code: create_or_return_to_draft
execution_flow_recompute_failed:
level: error
action_code: report_do_not_retry
execution_flow_result_changed:
level: error
action_code: restart_paging_no_cursor
execution_flow_evidence_incomplete:
level: error
action_code: recompute_then_retry | report_do_not_retry
execution_flow_root_too_large:
level: error
action_code: enumerate_remaining_roots
invalid_cursor:
level: error
action_code: correct_parameters
invalid_execution_flow_target:
level: error
action_code: correct_parameters
invalid_payload:
level: error
action_code: correct_parameters
query_parameters:
description: 'GET query parameters (REST: each parameter at most once, list values
comma-separated; MCP: JSON arrays). Unknown parameters are rejected with invalid_payload.
Filters must not change while paging with a cursor.'
type: object
additionalProperties: false
properties:
sections:
type: array
items:
type: string
enum:
- policy_violations
- policy_warnings
- execution_flows
description: Catalog sections to include. Omit for all three.
severities:
type: array
items:
type: string
enum:
- violation
- warning
- unmanaged
- mitigated
- ignored
- no_modeled_exposure
description: Execution-flow severity filter. Risk-first default when omitted
excludes ignored; request ignored explicitly to audit accepted risk.
target_ids:
type: array
items:
type: string
maxItems: 50
description: 'Exact-fetch mode: return only these highlight targets (opaque
IDs previously returned by this endpoint for the same system and version).
Mutually exclusive with sections/severities filtering semantics; unknown
IDs return invalid_execution_flow_target.'
view:
type: string
enum:
- full
- summary
default: full
description: summary returns root_target_stubs only (no evidence graph) with
higher limits; use it first on large systems, then drill down with target_ids.
limit:
type: integer
minimum: 1
description: 'Roots per page. full view: default 20, max 100. summary view:
default 200, max 1000.'
cursor:
type: string
maxLength: 2048
description: Opaque paging cursor from page.next_cursor. Bound to system,
version, filters, and result_hash; reuse with different filters returns
invalid_cursor, and a changed result returns execution_flow_result_changed.
expected_result_hash:
type: string
description: 'Optional first-page pin: if the current result_hash differs,
the read fails with execution_flow_result_changed instead of silently returning
a different result. Use when drilling down after a summary pass.'
severity:
type: string
enum:
- violation
- warning
- unmanaged
- mitigated
- ignored
- no_modeled_exposure
disposition:
type: string
enum:
- consumed
- conveyed_consumed
- spilled_after_conveyance
acquisition_identity:
type: object
additionalProperties: false
properties:
resource:
type: string
description: Graph instance_uuid of the resource where the tag was acquired.
acquired_via:
type: string
description: Graph instance_uuid of the component that read the resource.
required:
- resource
- acquired_via
custody_fact:
type: object
additionalProperties: false
description: Page-local custody fact for a consumed acquisition. Present only
when the selected full-view closure contains consumed evidence.
properties:
holder:
type: string
description: Graph instance_uuid of the component that retains the acquired
value.
acquisition:
$ref: '#/$defs/acquisition_identity'
tags:
type: array
items:
type: string
minItems: 1
uniqueItems: true
required:
- holder
- acquisition
- tags
badge:
type: object
properties:
kind:
type: string
enum:
- origin
- mitigation
- consumed
- output
- risk_exposure
- warning
- violation
description: Closed badge vocabulary. origin = where the risk enters; mitigation
= a control that reduces it; consumed = the component that retains an acquired
value without conveying or spilling it; output = where the branch terminates;
risk_exposure = an attached resource reached by the selected violating branch
(modeled reachability, not an observed incident); warning/violation = policy
findings pinned to a node.
node_id:
type: string
description: "Graph instance_uuid \u2014 pass to get_node_detail for full\
\ node context."
label:
type: string
required:
- kind
- node_id
highlight_target:
type: object
description: One row of the persisted highlight catalog. target_id is opaque;
never parse it.
properties:
target_id:
type: string
kind:
type: string
enum:
- policy_group
- policy_result
- group
- flow_group
- flow
- branch_group
- branch
label:
type: string
severity:
$ref: '#/$defs/severity'
fragment_refs:
type: array
items:
type: string
child_target_refs:
type: array
items:
type: string
metadata:
type: object
properties:
disposition:
$ref: '#/$defs/disposition'
required:
- target_id
- kind
- label
highlight_fragment:
type: object
description: Evidence fragment referenced by targets. fragment_id is opaque; node_ids
are graph instance_uuids (get_node_detail); edge_pairs are [from_instance_uuid,
to_instance_uuid].
properties:
fragment_id:
type: string
kind:
type: string
enum:
- payload_path
- acquisition_path
- control_topology
- badge_set
- node_set
- edge_set
phase:
type: string
enum:
- request
- response
- both
node_ids:
type: array
items:
type: string
edge_pairs:
type: array
items:
type: array
items:
type: string
minItems: 2
maxItems: 2
badges:
type: array
items:
$ref: '#/$defs/badge'
metadata:
type: object
properties:
disposition:
$ref: '#/$defs/disposition'
required:
- fragment_id
- kind
policy_row:
type: object
description: 'Projected policy evaluation row (violation, warning, or compound
finding). policy_target_ids is a legacy field name: its values are graph instance
UUIDs (node IDs), NOT highlight target IDs. component_scoped=true means the
finding applies to a single component; its edge field is then the self-pair
sentinel [node_id, node_id] rather than a real graph edge.'
properties:
target_ref:
type: string
description: Owning highlight target_id (opaque).
policy_target_ids:
type: array
items:
type: string
description: "Graph instance UUIDs the finding applies to \u2014 pass to get_node_detail.\
\ Legacy name; not highlight targets."
edge:
type: array
items:
type: string
minItems: 2
maxItems: 2
description: '[from_instance_uuid, to_instance_uuid]. When both entries are
the same UUID this is the component-scoped sentinel, not a self-edge in
the graph.'
component_scoped:
type: boolean
severity:
type: string
message:
type: string
risk:
type: object
description: Risk snapshot (risk_uid, name, description, mitigation text)
captured at evaluation time.
evidence_node:
type: object
description: 'Snapshot-shaped node in the returned evidence slice. instance_uuid
is THE graph node identity: pass it to get_node_detail and use it in sync edges.
referent_uuid identifies the catalog entry behind the node and belongs only
to search_detail.'
properties:
instance_uuid:
type: string
referent_uuid:
type: string
kind:
type: string
name:
type: string
type_tags:
type: array
items:
type: string
risk_tags:
type: array
items:
type: string
purl:
type: string
required:
- instance_uuid
- kind
- name
page:
type: object
additionalProperties: false
properties:
returned:
type: integer
total:
type: integer
description: Total matching root targets for this filter set.
requested_limit:
type: integer
size_limited:
type: boolean
description: "true when the page closed early because the next root would\
\ exceed the byte/object budget; continue with next_cursor \u2014 this is\
\ normal, not an error."
next_cursor:
type:
- string
- 'null'
has_more:
type: boolean
description: Keep paging until has_more is false; counts are only complete
then.
required:
- returned
- total
- requested_limit
- size_limited
- next_cursor
- has_more
summary_block:
type: object
properties:
matching_root_target_count:
type: integer
policy_result_counts:
type: object
additionalProperties: false
properties:
violations:
type: integer
warnings:
type: integer
compound_findings:
type: integer
required:
- violations
- warnings
- compound_findings
execution_flow_severity_counts:
type: object
description: Counts over execution-flow roots by effective severity (unmanaged/mitigated/ignored/no_modeled_exposure).
Computed over the full filtered result, not just this page.
additionalProperties: false
properties:
unmanaged:
type: integer
mitigated:
type: integer
ignored:
type: integer
no_modeled_exposure:
type: integer
required:
- unmanaged
- mitigated
- ignored
- no_modeled_exposure
suggested_mitigation_count:
oneOf:
- type: integer
minimum: 0
- type: 'null'
required:
- matching_root_target_count
- policy_result_counts
- execution_flow_severity_counts
additionalProperties: false
success_execution_flow_state:
type: object
description: Successful reads expose only the public freshness state for the selected
evidence source.
additionalProperties: false
properties:
status:
type: string
const: fresh
stale:
type: boolean
const: false
evaluation_basis:
type: string
enum:
- current_draft_evaluator
- submitted_persisted_evaluation
- release_archive
updated_at:
type:
- string
- 'null'
required:
- status
- stale
- evaluation_basis
- updated_at
error_execution_flow_state:
type: object
description: Public stale/failure diagnostics. Persisted free-text reason values
are never exposed.
additionalProperties: false
properties:
status:
type: string
stale:
type: boolean
evaluation_basis:
type: string
updated_at:
type:
- string
- 'null'
version_uid:
type: string
failure_stage:
type:
- string
- 'null'
computed_graph_fingerprint:
type:
- string
- 'null'
current_graph_fingerprint:
type:
- string
- 'null'
computed_execution_input_hash:
type:
- string
- 'null'
failed_execution_input_hash:
type:
- string
- 'null'
required:
- status
- stale
root_target_stub:
type: object
description: summary-view root entry. Labels longer than 1024 characters are truncated
and flagged with label_truncated.
properties:
target_id:
type: string
kind:
type: string
label:
type: string
maxLength: 1024
severity:
type:
- string
- 'null'
section_id:
type:
- string
- 'null'
label_truncated:
type: boolean
required:
- target_id
- kind
- label
- severity
- section_id
read_success_data:
type: object
description: data payload of a successful GET. In full view the evidence arrays
are populated and root_target_stubs is empty; in summary view root_target_stubs
is populated and nodes/edges/highlight_catalog/policy_results are empty.
properties:
schema_version:
type: string
const: '2.0'
view:
type: string
enum:
- full
- summary
version_uid:
type: string
version_number:
type: integer
version_status:
type: string
enum:
- draft
- in_review
- active
source:
oneOf:
- type: object
additionalProperties: false
properties:
kind:
type: string
const: live_version
required:
- kind
- type: object
additionalProperties: false
properties:
kind:
type: string
const: release_archive
archive_schema_version:
type: integer
archive_payload_sha256:
type: string
pattern: ^[0-9a-f]{64}$
captured_at:
type: string
required:
- kind
- archive_schema_version
- archive_payload_sha256
- captured_at
graph_hash:
type:
- string
- 'null'
phase_route_override_hash:
type:
- string
- 'null'
result_hash:
type: string
description: Stable hash of the complete filtered result; pass back as expected_result_hash
to pin drill-down reads.
execution_flow_state:
$ref: '#/$defs/success_execution_flow_state'
scope:
type: object
additionalProperties: false
description: 'Always {graph: relevant_evidence, complete_system_graph: false}:
nodes/edges are the evidence slice for this page''s roots, never the whole
system graph.'
properties:
graph:
type: string
const: relevant_evidence
complete_system_graph:
type: boolean
const: false
required:
- graph
- complete_system_graph
summary:
$ref: '#/$defs/summary_block'
root_target_refs:
type: array
items:
type: string
root_target_stubs:
type: array
items:
$ref: '#/$defs/root_target_stub'
purls:
type: object
description: purl -> [instance_uuid] for nodes in this page's evidence slice.
purl_instances:
type: object
description: instance_uuid -> purl for nodes in this page's evidence slice.
nodes:
type: array
items:
$ref: '#/$defs/evidence_node'
edges:
type: array
description: 'Evidence-slice edges in authored direction: {from, to} of instance_uuids.'
custody_facts:
type: array
items:
$ref: '#/$defs/custody_fact'
description: Page-local facts for selected consumed acquisition branches.
Omitted when the full-view page has no consumed evidence and forbidden in
summary view.
suggested_mitigations:
oneOf:
- type: array
items:
$ref: '#/$defs/suggested_mitigation'
- type: 'null'
highlight_catalog:
type: object
properties:
sections:
type: array
targets:
type: array
items:
$ref: '#/$defs/highlight_target'
fragments:
type: array
items:
$ref: '#/$defs/highlight_fragment'
additionalProperties: false
required:
- sections
- targets
- fragments
policy_results:
type: object
additionalProperties: false
properties:
violations:
type: array
items:
$ref: '#/$defs/policy_row'
warnings:
type: array
items:
$ref: '#/$defs/policy_row'
compound_findings:
type: array
items:
$ref: '#/$defs/policy_row'
required:
- violations
- warnings
- compound_findings
page:
$ref: '#/$defs/page'
required:
- schema_version
- view
- version_uid
- version_number
- version_status
- source
- graph_hash
- phase_route_override_hash
- result_hash
- execution_flow_state
- scope
- summary
- root_target_refs
- root_target_stubs
- purls
- purl_instances
- nodes
- edges
- highlight_catalog
- policy_results
- page
additionalProperties: false
allOf:
- if:
properties:
view:
const: full
required:
- view
then:
required:
- suggested_mitigations
else:
properties:
suggested_mitigations: false
custody_facts: false
summary:
required:
- suggested_mitigation_count
recompute_ack_data:
type: object
additionalProperties: false
description: "data payload of a successful POST .../execution-flows/recompute.\
\ status=ready covers both a real recompute and a no-op on an already-fresh\
\ draft; the ack carries no result rows \u2014 follow the execution_flows_ready\
\ guidance and call GET."
properties:
status:
type: string
const: ready
version_uid:
type: string
version_number:
type: integer
graph_hash:
type:
- string
- 'null'
result_hash:
type: string
execution_flow_state:
$ref: '#/$defs/success_execution_flow_state'
required:
- status
- version_uid
- version_number
- result_hash
- execution_flow_state
error_data_variants:
description: error `data` payloads by guidance type.
type: object
properties:
execution_flows_stale:
type: object
additionalProperties: false
properties:
version_uid:
type: string
version_status:
type: string
execution_flow_state:
$ref: '#/$defs/error_execution_flow_state'
required:
- version_uid
- version_status
- execution_flow_state
execution_flows_unavailable:
type: object
additionalProperties: false
properties:
version_uid:
type: string
version_status:
type: string
required:
- version_uid
- version_status
execution_flows_archive_unavailable:
type: object
additionalProperties: false
properties:
version_uid:
type: string
version_number:
type: integer
version_status:
type: string
archive_failure:
type: string
enum:
- missing
- unsupported_schema
- identity_mismatch
- integrity
- captured_state_invalid
archive_failure_detail:
description: First failing archive validation check in normative order.
Omitted when no archive row exists.
type: object
additionalProperties: false
properties:
check:
type: string
enum:
- payload_readable
- payload_sha256
- payload_size
- schema_version_match
- schema_version_supported
- identity_match
- captured_state_shape
row_schema_version: {}
bundle_schema_version: {}
required:
- check
allOf:
- if:
properties:
check:
enum:
- schema_version_match
- schema_version_supported
then:
required:
- row_schema_version
- bundle_schema_version
else:
not:
anyOf:
- required:
- row_schema_version
- required:
- bundle_schema_version
required:
- version_uid
- version_number
- version_status
- archive_failure
execution_flow_evidence_incomplete:
type: object
additionalProperties: false
properties:
version_uid:
type: string
version_status:
type: string
unresolved:
type: object
description: Exact unresolved-reference buckets; every array is sorted
and deduplicated.
properties:
target_refs:
type: array
items:
type: string
fragment_refs:
type: array
items:
type: string
node_ids:
type: array
items:
type: string
edge_pairs:
type: array
items:
type: array
items:
type: string
policy_target_refs:
type: array
items:
type: string
invalid_kinds:
type: array
items:
type: string
invalid_phases:
type: array
items:
type: string
cycle_target_ids:
type: array
items:
type: string
required:
- target_refs
- fragment_refs
- node_ids
- edge_pairs
- policy_target_refs
- invalid_kinds
- invalid_phases
- cycle_target_ids
required:
- version_uid
- version_status
- unresolved
execution_flow_root_too_large:
type: object
description: 'Enriched 413 payload: enough identity and size data to report
the oversized root without ever fetching it.'
additionalProperties: false
properties:
target_id:
type: string
target_kind:
type: string
target_label:
type: string
maxLength: 1024
severity:
type:
- string
- 'null'
section_id:
type:
- string
- 'null'
evidence_object_count:
type: integer
canonical_envelope_bytes:
type: integer
label_truncated:
type: boolean
required:
- target_id
- target_kind
- target_label
- evidence_object_count
- canonical_envelope_bytes
invalid_execution_flow_target:
type: object
additionalProperties: false
properties:
unknown_target_ids:
type: array
items:
type: string
required:
- unknown_target_ids
execution_flows_read_only:
type: object
additionalProperties: false
properties:
version_uid:
type: string
version_status:
type: string
required:
- version_uid
- version_status
execution_flow_recompute_failed:
type: object
additionalProperties: false
properties:
version_uid:
type: string
version_status:
type: string
execution_flow_state:
$ref: '#/$defs/error_execution_flow_state'
required:
- version_uid
- version_status
- execution_flow_state
error_data:
description: Structured data carried by execution-flow error envelopes when the
error has diagnostic fields.
anyOf:
- $ref: '#/$defs/error_data_variants/properties/execution_flows_stale'
- $ref: '#/$defs/error_data_variants/properties/execution_flows_unavailable'
- $ref: '#/$defs/error_data_variants/properties/execution_flows_archive_unavailable'
- $ref: '#/$defs/error_data_variants/properties/execution_flow_evidence_incomplete'
- $ref: '#/$defs/error_data_variants/properties/execution_flow_root_too_large'
- $ref: '#/$defs/error_data_variants/properties/invalid_execution_flow_target'
- $ref: '#/$defs/error_data_variants/properties/execution_flows_read_only'
- $ref: '#/$defs/error_data_variants/properties/execution_flow_recompute_failed'
error_envelope_contract:
oneOf:
- properties:
error:
const: execution_flows_stale
data:
$ref: '#/$defs/error_data_variants/properties/execution_flows_stale'
required:
- error
- data
- properties:
error:
const: execution_flows_unavailable
data:
$ref: '#/$defs/error_data_variants/properties/execution_flows_unavailable'
required:
- error
- properties:
error:
const: execution_flows_archive_unavailable
data:
$ref: '#/$defs/error_data_variants/properties/execution_flows_archive_unavailable'
required:
- error
- data
- properties:
error:
const: execution_flow_evidence_incomplete
data:
$ref: '#/$defs/error_data_variants/properties/execution_flow_evidence_incomplete'
required:
- error
- data
- properties:
error:
const: execution_flow_root_too_large
data:
$ref: '#/$defs/error_data_variants/properties/execution_flow_root_too_large'
required:
- error
- data
- properties:
error:
const: invalid_execution_flow_target
data:
$ref: '#/$defs/error_data_variants/properties/invalid_execution_flow_target'
required:
- error
- data
- properties:
error:
const: execution_flows_read_only
data:
$ref: '#/$defs/error_data_variants/properties/execution_flows_read_only'
required:
- error
- data
- properties:
error:
const: execution_flow_recompute_failed
data:
$ref: '#/$defs/error_data_variants/properties/execution_flow_recompute_failed'
required:
- error
- data
- properties:
error:
enum:
- execution_flow_result_changed
- invalid_cursor
- invalid_payload
data: false
required:
- error
mitigation_component:
type: object
additionalProperties: false
properties:
name:
type: string
purl:
type: string
status:
type: string
minLength: 1
not:
const: prohibited
type_tags:
type: array
items:
type: string
adds_tags:
type: array
items:
type: string
removes_tags:
type: array
items:
type: string
availability:
type: string
enum:
- current_system
- organization_inventory
- registry
required:
- name
- purl
- status
- type_tags
- adds_tags
- removes_tags
- availability
mitigation_edge:
type: object
additionalProperties: false
properties:
from:
type: string
to:
type: string
required:
- from
- to
mitigation_path_effect:
type: object
additionalProperties: false
properties:
target_ref:
type: string
edge:
$ref: '#/$defs/mitigation_edge'
tags_addressed:
type: array
items:
type: string
tags_remaining:
type: array
items:
type: string
net_adds_tags:
type: array
items:
type: string
net_removes_tags:
type: array
items:
type: string
required:
- target_ref
- edge
- tags_addressed
- tags_remaining
- net_adds_tags
- net_removes_tags
mitigation_node_upsert:
type: object
additionalProperties: false
properties:
instance_uuid:
type: string
kind:
type: string
const: component
name:
type: string
purl:
type: string
type_tags:
type: array
items:
type: string
adds_tags:
type: array
items:
type: string
removes_tags:
type: array
items:
type: string
required:
- instance_uuid
- kind
- name
- purl
- type_tags
- adds_tags
- removes_tags
mitigation_applied_control:
type: object
additionalProperties: false
properties:
controller_uuid:
type: string
mode:
type: string
enum:
- observe
- guard
required:
- controller_uuid
- mode
mitigation_sync_edge:
type: object
additionalProperties: false
properties:
from:
type: string
to:
type: string
operations:
type: array
items:
type: string
edge_mode:
type: string
enum:
- observe
- guard
applied_controls:
type: array
items:
$ref: '#/$defs/mitigation_applied_control'
required:
- from
- to
mitigation_remove_edge:
type: object
additionalProperties: false
properties:
from:
type: string
to:
type: string
operations:
type: array
items:
type: string
required:
- from
- to
mitigation_apply_payload:
type: object
additionalProperties: false
properties:
guidance_version:
type: string
base_graph_hash:
type: string
nodes:
type: array
items:
$ref: '#/$defs/mitigation_node_upsert'
remove_edges:
type: array
items:
$ref: '#/$defs/mitigation_remove_edge'
edges:
type: array
items:
$ref: '#/$defs/mitigation_sync_edge'
required:
- guidance_version
- base_graph_hash
- nodes
- remove_edges
- edges
mitigation_placement:
type: object
additionalProperties: false
properties:
strategy:
type: string
enum:
- attached_controls
- inline_chain
apply_payload:
$ref: '#/$defs/mitigation_apply_payload'
required:
- strategy
- apply_payload
suggested_mitigation:
type: object
additionalProperties: false
description: One current-registry component-placement plan derived from canonical
evidence. It is advice, not persisted evidence.
properties:
components:
type: array
minItems: 1
items:
$ref: '#/$defs/mitigation_component'
path_effects:
type: array
minItems: 1
items:
$ref: '#/$defs/mitigation_path_effect'
placement:
$ref: '#/$defs/mitigation_placement'
required:
- components
- path_effects
- placement
type: object
additionalProperties: false
properties:
ok:
type: boolean
data:
anyOf:
- $ref: '#/$defs/read_success_data'
- $ref: '#/$defs/recompute_ack_data'
- $ref: '#/$defs/error_data'
error:
type: string
description: Present when ok=false; equals the guidance type of the primary guidance
item.
guidance:
type: array
items:
$ref: '#/$defs/guidance_item'
required:
- ok
- guidance
allOf:
- if:
properties:
ok:
const: true
required:
- ok
then:
required:
- data
properties:
data:
oneOf:
- $ref: '#/$defs/read_success_data'
- $ref: '#/$defs/recompute_ack_data'
not:
required:
- error
else:
required:
- error
$ref: '#/$defs/error_envelope_contract'Full sync payload schema Open this when you need the complete validation contract, including definitions and nested shapes. 19 definitions
$schema: https://json-schema.org/draft/2020-12/schema
$id: https://modelmonster.ai/schemas/external-api/sync-payload.schema.json
title: Model Monster External API Sync Payload
description: Declarative sync payload accepted by the external API sync endpoint.
This schema documents the structural contract and the persisted sync data surface.
Runtime semantic validation still applies for duplicate UUIDs, graph conflicts,
and domain-specific normalization rules.
type: object
additionalProperties: false
properties:
base_graph_hash:
description: Optional optimistic-concurrency baseline from a fresh snapshot or
prior sync response. Omit for ordinary additive syncs; send it when you need
concurrency checks for follow-up removals or topology edits.
type:
- string
- 'null'
idempotency_key:
description: Optional client-generated key used to replay the same sync request
safely.
type:
- string
- 'null'
maxLength: 128
validate_format:
description: When true, validate and plan the sync without mutating the graph.
type: boolean
include_conflict_snapshot:
description: Optional conflict mode. Use 'compact' to include a compact snapshot
in conflict responses. Empty string and null are treated the same as omitting
the field.
type:
- string
- 'null'
enum:
- null
- ''
- compact
nodes:
description: Node upserts keyed by node instance_uuid. Edge from/to values must
use these same instance_uuid values.
type: array
maxItems: 300
items:
$ref: '#/$defs/syncNode'
edges:
description: Edge upserts between graph nodes addressed by node instance_uuid
values. Resource-linked edges may include operations.
type: array
maxItems: 1200
items:
$ref: '#/$defs/syncEdge'
remove_nodes:
description: Node instance UUIDs to remove from the graph.
type: array
maxItems: 300
items:
$ref: '#/$defs/uuidV4'
remove_edges:
description: Edges to remove from the graph. Match by from/to and optional operations.
type: array
maxItems: 1200
items:
$ref: '#/$defs/removeEdge'
$defs:
uuidV4:
description: RFC 4122 UUID version 4 string.
type: string
pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
jsonObject:
description: Structured JSON object stored with the node state.
type: object
configurationScalar:
description: Scalar configuration value.
type:
- string
- number
- boolean
- 'null'
configurationScalarList:
description: Configuration list containing only scalar values.
type: array
items:
$ref: '#/$defs/configurationScalar'
configurationValue:
description: 'Configuration value: scalar or list of scalars.'
oneOf:
- $ref: '#/$defs/configurationScalar'
- $ref: '#/$defs/configurationScalarList'
configurationObject:
description: Shallow runtime configuration object. Values may be scalars or lists
of scalars; nested objects and nested arrays are not supported.
type: object
additionalProperties:
$ref: '#/$defs/configurationValue'
tagToken:
type: string
maxLength: 64
tagList:
type: array
maxItems: 32
items:
$ref: '#/$defs/tagToken'
riskTagList:
type: array
maxItems: 32
items:
$ref: '#/$defs/tagToken'
conveyanceEntry:
type: object
additionalProperties: false
required:
- tag
- resource
- acquired_via
properties:
tag:
$ref: '#/$defs/tagToken'
resource:
$ref: '#/$defs/uuidV4'
acquired_via:
$ref: '#/$defs/uuidV4'
conveysTagsList:
type: array
minItems: 1
maxItems: 32
items:
$ref: '#/$defs/conveyanceEntry'
operationsList:
type: array
maxItems: 16
items:
anyOf:
- description: Canonical operation token.
type: string
maxLength: 32
- description: 'Scoped-read input shorthand. The service decodes this to operations:
[read] plus read_risk_tags before persistence.'
type: string
pattern: ^\s*[Rr][Ee][Aa][Dd]\s*:[^,]+(?:,[^,]+)*\s*$
maxLength: 2084
operationSelectorList:
type: array
maxItems: 16
items:
type: string
maxLength: 32
controlEdgeMode:
type: string
enum:
- observe
- guard
appliedControl:
type: object
additionalProperties: false
required:
- controller_uuid
- mode
properties:
controller_uuid:
description: Controller node instance UUID from the active graph snapshot.
Must reference a controller-eligible component (control or nonflow type
tag) in the current graph. Do not use a referent_uuid here.
$ref: '#/$defs/uuidV4'
mode:
description: 'How this controller-eligible component applies to the payload
edge: observe mirrors payload state for monitoring/logging-style controls,
while guard gates the payload path without carrying it.'
$ref: '#/$defs/controlEdgeMode'
appliedControlsList:
type: array
maxItems: 16
items:
$ref: '#/$defs/appliedControl'
syncNode:
type: object
additionalProperties: false
required:
- instance_uuid
properties:
instance_uuid:
$ref: '#/$defs/uuidV4'
kind:
description: Node kind. Required for new nodes; existing nodes may omit kind
for metadata-only updates.
type: string
enum:
- component
- resource
referent_uuid:
description: Optional existing component or resource referent UUID for referent
lookup or reuse. Do not use referent_uuid in edge from/to fields.
type: string
purl:
description: Optional package URL used to resolve or create a referent.
type: string
maxLength: 2048
purl_type:
description: Canonical PURL type field for component/resource identity.
type: string
maxLength: 64
purl_namespace:
description: Canonical PURL namespace field for component/resource identity.
type: string
maxLength: 255
purl_name:
description: Canonical PURL name field for component/resource identity.
type: string
maxLength: 256
purl_version:
description: Canonical PURL version field for component/resource identity.
Change this only for a real new version/release/build, not just to avoid
an identity collision.
type: string
maxLength: 256
repo_path:
description: Optional repo/workspace path that helps humans find the implementation.
For private PURLs this is rendered as the repository_path qualifier, not
core package identity.
type: string
maxLength: 1024
purl_qualifiers:
description: Canonical PURL qualifiers field for component/resource identity.
type: string
maxLength: 1024
purl_subpath:
description: Canonical PURL subpath field for component/resource identity.
type: string
maxLength: 512
name:
description: Canonical human-readable referent label.
type: string
maxLength: 256
display_name:
description: Optional instance-local label override stored on graph instance
state.
type: string
maxLength: 256
notes:
description: Freeform notes stored on the graph instance state.
type: string
maxLength: 8192
type_tags:
description: Type tags used for classification and policy evaluation.
$ref: '#/$defs/tagList'
risk_tags:
description: Risk tags carried by the node state.
$ref: '#/$defs/riskTagList'
adds_tags:
description: Risk tags this node introduces.
$ref: '#/$defs/riskTagList'
removes_tags:
description: Risk tags this node mitigates or removes.
$ref: '#/$defs/riskTagList'
consumes_tags:
description: Configuration-channel tags this component consumes.
$ref: '#/$defs/riskTagList'
extra_data:
description: Structured metadata. Component-side referent field; resource-side
effective instance value.
$ref: '#/$defs/jsonObject'
configuration:
description: Structured runtime configuration stored with the node state.
This is instance state, not referent identity. Use a shallow object whose
values are scalars or lists of scalars.
$ref: '#/$defs/configurationObject'
type:
description: Resource type when modeling resources.
type: string
enum:
- data
- system
- network
classification:
description: Resource data classification when modeling resources.
type: string
enum:
- public
- internal
- confidential
- restricted
canonical_zone:
description: Canonical shared zone resource to resolve or create. Use this
instead of inventing bespoke Internet/Intranet/Local resource names.
type: string
enum:
- internet
- intranet
- local
- local_computer
shared:
description: Resource org-registry visibility flag.
type: boolean
spdx_license_expression:
description: Shared external license field routed by kind.
type: string
maxLength: 4096
syncEdge:
type: object
additionalProperties: false
required:
- from
- to
properties:
from:
description: Source node instance UUID.
$ref: '#/$defs/uuidV4'
to:
description: Target node instance UUID.
$ref: '#/$defs/uuidV4'
operations:
description: 'Optional resource-link operations on the edge. A scoped read
may be supplied as read:credential,pii shorthand; responses and persisted
graphs return operations: [read] plus read_risk_tags.'
$ref: '#/$defs/operationsList'
read_risk_tags:
description: Optional non-empty canonical risk-tag scope for a read operation.
Only these intrinsic tags are introduced from the resource; carried tags
and resource classification still propagate. Omit for an unrestricted read.
type: array
minItems: 1
maxItems: 32
items:
type: string
minLength: 1
maxLength: 64
edge_mode:
description: Optional control-topology edge mode for links that touch a controller-eligible
component (control or nonflow type tag). Use observe for monitoring/logging-style
mirroring and guard for controls that gate a payload path. Omit on ordinary
payload edges.
$ref: '#/$defs/controlEdgeMode'
applied_controls:
description: Optional list of controller-eligible components applied to this
payload edge. Use this only on payload edges. Each controller_uuid must
be a graph node instance_uuid from the active graph snapshot, not a referent_uuid.
$ref: '#/$defs/appliedControlsList'
conveys_tags:
description: Configuration arrivals carried across this ordinary component-to-component
payload edge.
$ref: '#/$defs/conveysTagsList'
removeEdge:
type: object
additionalProperties: false
required:
- from
- to
properties:
from:
description: Source node instance UUID.
$ref: '#/$defs/uuidV4'
to:
description: Target node instance UUID.
$ref: '#/$defs/uuidV4'
operations:
description: Optional operations selector for removing resource-link edges.
$ref: '#/$defs/operationSelectorList'Type and risk taxonomy
6 type facetsType tags describe what a node is and how it behaves. Risk tags describe data sensitivity, trust, and exposure properties that enter or move through the graph.
Type facets
scope 4 values
type 12 values
subtype 65 values
domain 57 values
interface 16 values
relation 2 values
Risk categories
data_classification 20 values
security_state 6 values
ai_specific 2 values
content_safety 17 values
privacy 2 values
Private PURLs
Stable private identityConstruct stable private referent identities for repo-owned components and resources.
Fielded Sync Node
Preferred sync payload shape for a repo-owned private component.
View example payload
kind: component
purl_type: private
purl_namespace: modelmonster.ai
purl_name: auth-gateway
purl_version: 2f6c9ab
repo_path: apps/auth-gateway
pkg:private/modelmonster.ai/auth-gateway@2f6c9ab?repository=apps&repository_path=apps%2Fauth-gateway
Nested Private Module
Same repo_path, different nested code path inside the package root.
View example payload
kind: component
purl_type: private
purl_namespace: acme.com
purl_name: scoring-engine
repo_path: monorepo/scoring-engine
purl_subpath: workers/batch
pkg:private/acme.com/scoring-engine?repository=monorepo&repository_path=monorepo%2Fscoring-engine#workers/batch
Bulk Search Query
Use compact strings for bulk_search because the tool input is purls[].
View example payload
description: Use compact strings for bulk_search because the tool input is purls[].
purl: pkg:private/acme.com/scoring-engine@2026-04-13?repository=monorepo&repository_path=monorepo%2Fscoring-engine
pkg:private/acme.com/scoring-engine@2026-04-13?repository=monorepo&repository_path=monorepo%2Fscoring-engine
Guidance catalog
88 situationsThis catalog lists the default guidance copy for agent-visible situations.
Live responses may override message or action with path-specific context while keeping the same guidance type and level.
info active_version_forked Active Version Forked The previous version was active, so this edit created draft {to_version_uid}.
The previous version was active, so this edit created draft {to_version_uid}.
Continue editing the new draft; the active version remains unchanged.
error active_version_read_only Active Version Read Only Archived system versions are read-only.
Archived system versions are read-only.
Retry the write without version_number to fork a draft from the active version.
error ambiguous_control_effects Ambiguous Control Effects applied_controls on one payload edge cannot both add and remove the same tag.
applied_controls on one payload edge cannot both add and remove the same tag.
Adjust controller adds_tags/removes_tags or split the controls so the same payload edge does not both add and remove the same tag.
/api/v1/reference/core-concepts
info concurrent_merge Concurrent Merge Sync merged with {changed_count} concurrent non-conflicting changes.
Sync merged with {changed_count} concurrent non-conflicting changes.
Your updates were saved. Fetch a fresh snapshot if you need the complete merged graph.
error conflicting_operations Conflicting Operations A node cannot be added or updated and removed in the same sync request.
A node cannot be added or updated and removed in the same sync request.
Remove overlapping UUIDs from either nodes or remove_nodes.
/api/v1/reference/schema
error controller_not_nonflow Controller Not Nonflow applied_controls controller_uuid must reference a controller-eligible component.
applied_controls controller_uuid must reference a controller-eligible component.
Pick a component with a control or nonflow type tag before binding it to payload edges.
/api/v1/reference/modeling-guide
warning conveyance_cycle_spill Conveyance Cycle Spill Conveyed {tag} from {resource} via {acquired_via} revisited {node} during {phase} and spilled after {hops} hop(s).
Conveyed {tag} from {resource} via {acquired_via} revisited {node} during {phase} and spilled after {hops} hop(s).
Break the conveyance cycle or accept the bounded payload spill at this component.
/api/v1/reference/core-concepts
warning conveyance_spills_at_target Conveyance Spills At Target Conveyed {tag} from {resource} via {acquired_via} reaches {target}, which neither consumes nor conveys that acquisition.
Conveyed {tag} from {resource} via {acquired_via} reaches {target}, which neither consumes nor conveys that acquisition.
Declare consumes_tags on the target, add the next qualified conveyance hop, or accept payload spill.
/api/v1/reference/core-concepts
warning conveyance_target_unreachable Conveyance Target Unreachable Conveyed {tag} from {resource} via {acquired_via} could not continue beyond spill site {spill_site} during {phase}, so its declared target was unreac…
Conveyed {tag} from {resource} via {acquired_via} could not continue beyond spill site {spill_site} during {phase}, so its declared target was unreachable.
Check the payload route to the target, or remove the conveyance selector if that route is not implemented.
/api/v1/reference/core-concepts
warning custom_tag_preserved Custom Tag Preserved Custom tag '{tag}' in {field} on {node_name} was preserved.
Custom tag '{tag}' in {field} on {node_name} was preserved.
Custom tags are allowed. Optionally align to canonical tags in {reference}.
{reference}
info default_removes_tags_applied Default Removes Tags Applied Default behavior was applied to {instance_uuid}: removes tags [{removes_tags}].
Default behavior was applied to {instance_uuid}: removes tags [{removes_tags}].
Verify that the component implementation removes these tags; explicitly set removes_tags if it does not.
/api/v1/reference/risk-tags
info defaults_applied Defaults Applied Auto-applied default risk tags to {node_name}: {adds_tags}.
Auto-applied default risk tags to {node_name}: {adds_tags}.
No action needed unless you want to override defaults in a follow-up sync.
/api/v1/reference/risk-tags
warning dormant_consumption Dormant Consumption Component {component} declares consumption of {tag}, but no live scoped-read or conveyed acquisition reaches it.
Component {component} declares consumption of {tag}, but no live scoped-read or conveyed acquisition reaches it.
Add a matching scoped read or conveyance, or clear the dormant consumes_tags entry.
/api/v1/reference/core-concepts
warning dormant_conveyance_at_source Dormant Conveyance At Source Conveyance on {source} -> {target} no longer matches a live {tag} acquisition from {resource} via {acquired_via}.
Conveyance on {source} -> {target} no longer matches a live {tag} acquisition from {resource} via {acquired_via}.
Restore the scoped-read acquisition, or remove the dormant conveys_tags selector.
/api/v1/reference/core-concepts
warning dormant_read_scope Dormant Read Scope Scoped read on {resource_uuid} -> {component_uuid} retains tags no longer assigned to the resource: {tags}.
Scoped read on {resource_uuid} -> {component_uuid} retains tags no longer assigned to the resource: {tags}.
Restore those risk tags on the resource if the scope should become active again, or remove the dormant tags from read_risk_tags. The saved scope remains narrow and is not widened automatically.
/api/v1/reference/core-concepts
warning duplicate_instance Duplicate Instance PURL {purl} is attached to {count} graph instances across {referent_count} distinct referents.
PURL {purl} is attached to {count} graph instances across {referent_count} distinct referents.
Reuse one referent_uuid for intentional multi-instance deployments, or remove the accidental duplicate referent.
error duplicate_instance_uuid Duplicate Instance Uuid A sync payload cannot reuse the same instance_uuid for multiple nodes.
A sync payload cannot reuse the same instance_uuid for multiple nodes.
Give each node in the sync payload a unique instance_uuid.
/api/v1/reference/schema
error duplicate_referent_identity Duplicate Referent Identity The payload attempts to create a duplicate referent identity.
The payload attempts to create a duplicate referent identity.
Reuse the existing referent_uuid instead of creating another referent with the same identity fields.
/api/v1/reference/schema
error duplicate_zone_resource Duplicate Zone Resource canonical_zone resources must be unique within a system graph.
canonical_zone resources must be unique within a system graph.
Reuse the existing canonical boundary resource instead of creating another one for the same zone.
/api/v1/reference/modeling-guide
error execution_flow_evidence_incomplete Execution Flow Evidence Incomplete Persisted execution-flow evidence contains references that do not resolve.
Persisted execution-flow evidence contains references that do not resolve.
Recompute this draft, then retry.
error execution_flow_recompute_failed Execution Flow Recompute Failed The canonical report run did not produce current execution-flow results for this draft.
The canonical report run did not produce current execution-flow results for this draft.
Do not retry automatically; report the system, version, and failure stage for diagnosis.
error execution_flow_result_changed Execution Flow Result Changed The execution-flow result changed since this query sequence began.
The execution-flow result changed since this query sequence began.
Discard accumulated pages and restart from the first page.
error execution_flow_root_too_large Execution Flow Root Too Large One root target's complete evidence closure exceeds the response budget and cannot be returned whole.
One root target's complete evidence closure exceeds the response budget and cannot be returned whole.
Report this target's identity and measured size; enumerate the remaining roots with view=summary and fetch them exactly with target_ids. The oversized root stays unassessed.
info execution_flows_all_clear Execution Flows All Clear No unmanaged risk in this result. Re-check after graph changes.
No unmanaged risk in this result. Re-check after graph changes.
Re-run this read after graph, policy, or risk-model changes.
error execution_flows_archive_unavailable Execution Flows Archive Unavailable The release archive for this active version is missing or cannot be trusted.
The release archive for this active version is missing or cannot be trusted.
Do not call recompute; recomputation cannot repair a release archive. Report the system, version, and archive_failure value to an operator.
info execution_flows_needs_disposition Execution Flows Needs Disposition Review the findings; mitigate manually or accept via the ignore workflow.
Review the findings; mitigate manually or accept via the ignore workflow.
Open the system map to inspect the findings and choose a disposition.
/api/v1/reference/remediations
info execution_flows_page_incomplete Execution Flows Page Incomplete Continue with page.next_cursor before drawing conclusions.
Continue with page.next_cursor before drawing conclusions.
Call get_execution_flows again with the returned cursor and unchanged filters.
error execution_flows_read_only Execution Flows Read Only Derived execution-flow state can only be recomputed on an editable draft.
Derived execution-flow state can only be recomputed on an editable draft.
Create or return to an editable draft before recomputing.
info execution_flows_ready Execution Flows Ready Execution-flow results are current.
Execution-flow results are current.
Call get_execution_flows without a cursor.
error execution_flows_stale Execution Flows Stale Execution-flow results are not current for this system version.
Execution-flow results are not current for this system version.
Retry the first page with credentials that can edit this system, or have an editor call recompute_execution_flows; do not retry in a loop after a refresh failure.
/api/v1/reference/schema
error execution_flows_unavailable Execution Flows Unavailable No valid persisted execution-flow result exists for this version.
No valid persisted execution-flow result exists for this version.
Create or return to an editable draft; recompute and query that draft. Do not call recompute for this version.
error forbidden Forbidden You do not have permission to access this resource.
You do not have permission to access this resource.
Use credentials with access to this org, team, or system.
error graph_conflict Graph Conflict Sync overlaps with concurrent edits to the same nodes or edges.
Sync overlaps with concurrent edits to the same nodes or edges.
Fetch a fresh snapshot, rebase your changes, and retry sync.
error guidance_required Guidance Required This write requires the current modeling guidance version.
This write requires the current modeling guidance version.
Call prepare_modeling_context or GET /api/v1/reference/modeling-context, read the required references, then retry with the current guidance_version.
/api/v1/reference/modeling-context
error historical_integrity_unavailable Historical Integrity Unavailable Historical export integrity data is unavailable for the requested version.
Historical export integrity data is unavailable for the requested version.
Export the current or latest version, or version-scope referent history first.
error idempotency_conflict Idempotency Conflict This idempotency_key was already used with a different sync payload.
This idempotency_key was already used with a different sync payload.
Use a new idempotency_key or resend the exact same payload.
/api/v1/reference/schema
error idempotency_in_progress Idempotency In Progress Another request with this idempotency_key is still in progress.
Another request with this idempotency_key is still in progress.
Retry this exact request in a few seconds.
/api/v1/reference/schema
error invalid_applied_controls_location Invalid Applied Controls Location applied_controls are only valid on payload edges.
applied_controls are only valid on payload edges.
Keep edge_mode only on the control-topology edge that touches the nonflow component. Apply applied_controls on the unannotated payload edge that the controller affects.
/api/v1/reference/modeling-guide
error invalid_consumes_tags Invalid Consumes Tags The consumes_tags value is invalid.
The consumes_tags value is invalid.
Use [] to clear consumption, or a list of canonical risk-tag tokens, including registered custom risk tags.
/api/v1/reference/schema
error invalid_control_edge_mode Invalid Control Edge Mode Control-edge mode is invalid.
Control-edge mode is invalid.
Use observe for monitoring-style controls and guard for gating controls that do not carry the payload.
/api/v1/reference/modeling-guide
error invalid_conveys_tags Invalid Conveys Tags The conveys_tags value is invalid.
The conveys_tags value is invalid.
Use a non-empty list of exact {tag, resource, acquired_via} objects on ordinary payload component-to-component edges.
/api/v1/reference/schema
error invalid_cursor Invalid Cursor The supplied cursor is not valid for this system, version, and filter set.
The supplied cursor is not valid for this system, version, and filter set.
Reissue the first-page query and page with the returned next_cursor, keeping the same filters.
error invalid_edge Invalid Edge Each edge entry must be an object.
Each edge entry must be an object.
Provide edge fields as a JSON object.
/api/v1/reference/schema
error invalid_edge_mode_location Invalid Edge Mode Location edge_mode is only valid on edges that touch a controller-eligible component.
edge_mode is only valid on edges that touch a controller-eligible component.
Remove edge_mode from ordinary payload edges, or attach the edge to a controller-eligible component (control or nonflow type tag). Use the modeling guide to separate payload edges from control-topology edges.
/api/v1/reference/modeling-guide
error invalid_edges Invalid Edges Field edges must be a list.
Field edges must be a list.
Set edges to an array of edge objects.
/api/v1/reference/schema
error invalid_execution_flow_target Invalid Execution Flow Target One or more requested highlight target IDs do not exist in the persisted catalog.
One or more requested highlight target IDs do not exist in the persisted catalog.
Use target IDs returned by an earlier execution-flow response for this exact system and version.
error invalid_kind Invalid Kind Node kind must be either component or resource.
Node kind must be either component or resource.
Set kind to component or resource and retry.
/api/v1/reference/schema
error invalid_node Invalid Node Each nodes entry must be an object.
Each nodes entry must be an object.
Provide node fields as a JSON object.
/api/v1/reference/schema
error invalid_nodes Invalid Nodes Field nodes must be a list.
Field nodes must be a list.
Set nodes to an array of node objects.
/api/v1/reference/schema
error invalid_operations Invalid Operations Edge operations are invalid for this edge shape.
Edge operations are invalid for this edge shape.
Use resource operations from read, write, delete, execute, grant. For a scoped read, use operations [read] plus a non-empty read_risk_tags list, or input-only read:credential,pii shorthand. Remove operations and read_risk_tags from component-to-component flows.
/api/v1/reference/core-concepts
error invalid_payload Invalid Payload Request payload is invalid.
Request payload is invalid.
Fix the payload structure and retry.
error invalid_profile Invalid Profile Export profile is not supported.
Export profile is not supported.
Use one of the published export profiles and retry.
error invalid_remove_edges Invalid Remove Edges Field remove_edges must be a list.
Field remove_edges must be a list.
Set remove_edges to an array of edge objects.
/api/v1/reference/schema
error invalid_remove_nodes Invalid Remove Nodes Field remove_nodes must be a list.
Field remove_nodes must be a list.
Set remove_nodes to an array of instance_uuid values.
/api/v1/reference/schema
error invalid_uuid Invalid Uuid UUID value is not a valid UUID v4.
UUID value is not a valid UUID v4.
Generate a standard v4 UUID (xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx).
error invalid_version_number Invalid Version Number version_number must be a valid integer when provided.
version_number must be a valid integer when provided.
Pass a valid integer version_number or omit it.
error missing_base_graph_hash Missing Base Graph Hash base_graph_hash is required for destructive sync operations.
base_graph_hash is required for destructive sync operations.
Fetch a fresh snapshot and retry with its graph_hash as base_graph_hash.
/api/v1/reference/schema
error missing_operations Missing Operations Resource link edges require operations.
Resource link edges require operations.
Add operations (read, write, delete, execute, or grant) to resource edges. Edges are unidirectional: model request and response as separate edges when both directions matter.
tip missing_scope_tag Missing Scope Tag Component {node_name} has no scope tag.
Component {node_name} has no scope tag.
Add one of local, internal, external, or unknown to type_tags.
/api/v1/reference/type-tags
info normalized_operations Normalized Operations Normalized operations in {count} edge payload(s) to canonical operation tokens.
Normalized operations in {count} edge payload(s) to canonical operation tokens.
Use lowercase operations from: read, write, delete, execute, grant. For scoped reads, persisted form is operations: [read] plus read_risk_tags.
/api/v1/reference/core-concepts
info normalized_risk_tags Normalized Risk Tags Normalized risk-tag field values in {count} payload location(s) to canonical token form.
Normalized risk-tag field values in {count} payload location(s) to canonical token form.
Use lowercase hyphenated risk tags and avoid duplicates across risk_tags/adds_tags/removes_tags.
/api/v1/reference/risk-tags
info normalized_type_tags Normalized Type Tags Normalized type_tags in {count} node payload(s) to canonical token form.
Normalized type_tags in {count} node payload(s) to canonical token form.
Use lowercase hyphenated type tags and avoid duplicates to prevent repeated normalization.
/api/v1/reference/type-tags
error not_found Not Found The requested endpoint or resource was not found.
The requested endpoint or resource was not found.
Check the URL and requested identifiers, then retry.
error not_found_context Not Found Context Organization or team is not available in the active session context.
Organization or team is not available in the active session context.
Use GET /api/v1/orgs and GET /api/v1/org/{org}/teams to choose a valid context.
error not_found_node Not Found Node Node with the requested instance_uuid was not found in this system.
Node with the requested instance_uuid was not found in this system.
Fetch GET .../snapshot for current nodes or create the node in sync.
error not_found_org Not Found Org Organization was not found.
Organization was not found.
Check GET /api/v1/orgs for accessible organizations.
error not_found_referent Not Found Referent Referent UUID was not found.
Referent UUID was not found.
A referent_uuid from search is a catalog identity, not a savefile referent. Re-send the node with the catalog item's purl and omit referent_uuid.
error not_found_system Not Found System System was not found.
System was not found.
Check GET /api/v1/org/{org}/t/{team}/systems for available systems.
error not_found_team Not Found Team Team was not found in the selected organization.
Team was not found in the selected organization.
Check GET /api/v1/org/{org}/teams for accessible teams.
error not_found_version Not Found Version The requested system version was not found.
The requested system version was not found.
Check the system's available versions and retry.
tip orphan_node Orphan Node Node {node_name} has no edges.
Node {node_name} has no edges.
Connect this node with flow or resource edges.
error payload_limits_exceeded Payload Limits Exceeded Request payload exceeds one or more published limits.
Request payload exceeds one or more published limits.
Reduce payload size, field lengths, or item counts to match the published sync schema.
/api/v1/reference/schema
error phase_route_override_conflict Phase Route Override Conflict Phase-route overrides changed concurrently for the same family.
Phase-route overrides changed concurrently for the same family.
Fetch the current phase-route overrides for this family, rebase your changes, and retry.
error referent_definition_conflict Referent Definition Conflict Duplicate instances sharing one referent identity must agree on referent-level fields.
Duplicate instances sharing one referent identity must agree on referent-level fields.
Keep referent-level fields identical across duplicate instances, or use a different referent identity when the referent is actually different.
/api/v1/reference/schema
info referent_enriched_from_catalog Referent Enriched From Catalog Applied curated catalog fields to {count} newly created component(s).
Applied curated catalog fields to {count} newly created component(s).
To override, supply type_tags/name explicitly on the node.
error referent_mismatch Referent Mismatch The supplied referent fields do not match the referenced catalog entry.
The supplied referent fields do not match the referenced catalog entry.
Use the canonical referent fields returned by search or search_detail.
/api/v1/reference/schema
warning removes_tags_default_mismatch Removes Tags Default Mismatch Component {instance_uuid} preserved removes_tags as supplied, but it omits default removals [{missing_tags}] for the final type_tags.
Component {instance_uuid} preserved removes_tags as supplied, but it omits default removals [{missing_tags}] for the final type_tags.
Verify that this deviation is intentional; update removes_tags if the component removes these tags.
/api/v1/reference/risk-tags
error runtime_export_unavailable Runtime Export Unavailable The requested version cannot be exported because the runtime graph cannot be built cleanly.
The requested version cannot be exported because the runtime graph cannot be built cleanly.
Repair the version so the runtime graph builds cleanly, then retry the export.
tip search_no_results Search No Results No component matched any word of "{query}".
No component matched any word of "{query}".
Retry with the shortest product name as it would appear in a catalog (for example "Slack" rather than "Slack workspace messaging") before creating an ad-hoc node.
error secrets_detected Secrets Detected The payload appears to contain secrets or credentials.
The payload appears to contain secrets or credentials.
Remove credentials, API keys, and tokens from the payload and retry.
error stale_base_graph_hash Stale Base Graph Hash base_graph_hash is stale relative to the current graph state.
base_graph_hash is stale relative to the current graph state.
Fetch a fresh snapshot and retry with the latest graph_hash. For ordinary additive syncs, omit base_graph_hash.
/api/v1/reference/schema
info type_tag_projection_help Type Tag Projection Help This result includes advisory type_tag facet projections for inspection.
This result includes advisory type_tag facet projections for inspection.
Use the projections to interpret the current graph. When mutating the graph, send canonical type_tags only.
/api/v1/reference/type-tags
info type_tag_projections Type Tag Projections Projected type_tag facets are included for {component_count} component node(s).
Projected type_tag facets are included for {component_count} component node(s).
Read details.by_instance_uuid for the advisory projection. Do not send facet projections back in sync payloads.
/api/v1/reference/type-tags
error unauthorized Unauthorized Authentication required.
Authentication required.
Authenticate with a valid user session or API key.
error unknown_base_graph_hash Unknown Base Graph Hash base_graph_hash is no longer available for this system.
base_graph_hash is no longer available for this system.
Fetch a fresh snapshot and retry with its graph_hash as base_graph_hash.
/api/v1/reference/schema
error unknown_controller_uuid Unknown Controller Uuid applied_controls must reference an active controller-eligible node.
applied_controls must reference an active controller-eligible node.
Fetch get_snapshot to discover active node instance_uuid values. Use a controller_uuid from the current graph, not a referent_uuid from search/search_detail.
/api/v1/reference/schema
error uuid_identity_mismatch Uuid Identity Mismatch A UUID already bound to one referent identity cannot be reused for a different identity.
A UUID already bound to one referent identity cannot be reused for a different identity.
Reuse the existing referent_uuid already bound to that identity, or create a new UUID for the different referent.
/api/v1/reference/schema
error wrong_node_identifier_kind Wrong Node Identifier Kind Edge endpoints must use node instance_uuid values, not referent_uuid values.
Edge endpoints must use node instance_uuid values, not referent_uuid values.
Use instance_uuid values from get_snapshot or get_node_detail for edge endpoints. Use referent_uuid only for search_detail and referent reuse in node payloads.
/api/v1/reference/schema