openapi: 3.0.3 info: title: AgentHound API description: >- REST API for `agenthound-server`. The server binds to 127.0.0.1:8080 by default and is single-user. Mutating endpoints are gated by an Origin allowlist (OriginGuard): browser requests must originate from an allowlisted origin (default `http://localhost:8080` and `http://127.0.0.1:8080`, configurable via `AGENTHOUND_CORS_ORIGINS`). Requests with no `Origin` header are admitted as non-browser callers (curl, the agenthound CLI, cron pipelines). Read-only endpoints (graph reads, findings, prebuilt queries, rules, health, docs) are intentionally open. Single-user posture means localhost reads are fine; gating them would force the UI to plumb auth headers through every read for no security gain. The `/ingest` endpoint accepts a completed JSON scan artifact. Drag-drop the file into the UI's Scan Manager, or use CLI ingest (`agenthound-server ingest `) to bypass HTTP entirely. version: "0.1.0" license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 servers: - url: /api/v1 description: Default components: schemas: ErrorResponse: type: object required: [error] properties: error: $ref: "#/components/schemas/ErrorDetail" ErrorDetail: type: object required: [code, message] properties: code: type: string example: VALIDATION_ERROR message: type: string example: description of the problem details: description: Additional error context (validation errors, etc.) RegistryContractMismatchDetails: type: object additionalProperties: false required: [root_coverage_key, supported_contract, action] properties: root_coverage_key: { type: string } received_contract: $ref: "#/components/schemas/InstructionRegistryContractV1" supported_contract: $ref: "#/components/schemas/InstructionRegistryContractV1" action: { type: string } IngestAdmissionErrorResponse: type: object additionalProperties: false required: [error] properties: error: type: object additionalProperties: false required: [code, message] properties: code: type: string enum: [UNSUPPORTED_V1_CONTRACT, REGISTRY_CONTRACT_MISMATCH] message: { type: string } details: $ref: "#/components/schemas/RegistryContractMismatchDetails" HealthResponse: type: object properties: status: type: string enum: [ok, degraded] neo4j: type: string enum: [ok, unavailable] postgres: type: string enum: [ok, unavailable] GraphStats: type: object additionalProperties: false required: [node_counts, edge_counts, total_nodes, total_edges, projection] properties: node_counts: type: object additionalProperties: type: integer edge_counts: type: object additionalProperties: type: integer total_nodes: type: integer total_edges: type: integer projection: $ref: "#/components/schemas/ProjectionIdentity" ProjectionIdentity: type: object additionalProperties: false required: [scan_id, revision, coverage_limited, coverage_limitation_count] properties: scan_id: type: string minLength: 1 revision: type: integer format: int64 minimum: 1 coverage_limited: type: boolean coverage_limitation_count: type: integer minimum: 0 Node: type: object properties: id: type: string kinds: type: array items: type: string properties: type: object additionalProperties: true Edge: type: object properties: source: type: string target: type: string kind: type: string source_kind: type: string target_kind: type: string properties: type: object additionalProperties: true PageMetadata: type: object additionalProperties: false required: [offset, limit, total, has_more, complete, revision, projection] properties: offset: { type: integer, minimum: 0 } limit: { type: integer, minimum: 1 } total: { type: integer, format: int64, minimum: 0 } has_more: { type: boolean } complete: { type: boolean } revision: { type: string, minLength: 1 } projection: $ref: "#/components/schemas/ProjectionIdentity" NodeListResponse: type: object additionalProperties: false required: [nodes, page] properties: nodes: type: array items: $ref: "#/components/schemas/Node" page: $ref: "#/components/schemas/PageMetadata" EdgeListResponse: type: object additionalProperties: false required: [edges, page] properties: edges: type: array items: $ref: "#/components/schemas/Edge" page: $ref: "#/components/schemas/PageMetadata" IngestV1: type: object additionalProperties: false required: [meta, graph] properties: meta: $ref: "#/components/schemas/IngestMetaV1" graph: type: object additionalProperties: false required: [nodes, edges] properties: nodes: type: array items: $ref: "#/components/schemas/IngestNodeV1" edges: type: array items: $ref: "#/components/schemas/IngestEdgeV1" IngestMetaV1: type: object additionalProperties: false required: - version - type - identity - collector - collector_version - timestamp - scan_id - collection - ruleset - identity_schemes properties: version: type: integer enum: [1] type: type: string enum: [agenthound-ingest] identity: $ref: "#/components/schemas/CollectionIdentityV1" collector: type: string enum: [mcp, a2a, config, scan] collector_version: type: string minLength: 1 timestamp: type: string format: date-time scan_id: type: string minLength: 1 collection: $ref: "#/components/schemas/IngestCollectionV1" ruleset: $ref: "#/components/schemas/IngestRulesetV1" identity_schemes: type: array minItems: 1 items: $ref: "#/components/schemas/IngestIdentitySchemeV1" extra: type: object additionalProperties: true IdentityEvidenceV1: type: object additionalProperties: false required: [kind, digest] properties: kind: { type: string, pattern: "^[a-z_]+$" } digest: { type: string, pattern: "^hmac-sha256:[0-9a-f]{64}$" } CollectionIdentityV1: type: object additionalProperties: false required: [scheme, version, collection_point_id, network_context_id, quality, network_quality, network_class, evidence, network_evidence] properties: scheme: { type: string, enum: [agenthound_collection_v1] } version: { type: integer, enum: [1] } collection_point_id: { type: string, pattern: "^sha256:[0-9a-f]{64}$" } network_context_id: { type: string, pattern: "^sha256:[0-9a-f]{64}$" } quality: { type: string, enum: [strong, weak] } network_quality: { type: string, enum: [strong, unknown] } network_class: { type: string, enum: [unknown, offline, private, public, mixed] } display: $ref: "#/components/schemas/CollectionDisplayLabels" evidence: type: array minItems: 1 items: { $ref: "#/components/schemas/IdentityEvidenceV1" } network_evidence: type: array minItems: 1 items: { $ref: "#/components/schemas/IdentityEvidenceV1" } CollectionDisplayLabels: type: object additionalProperties: false properties: hostname: { type: string, maxLength: 255 } os: { type: string, maxLength: 255 } architecture: { type: string, maxLength: 255 } IngestCollectionV1: type: object additionalProperties: false required: [state, coverage_keys, outcomes] properties: state: type: string enum: [unknown, not_applicable, complete, partial, failed, truncated] coverage_keys: type: array minItems: 1 uniqueItems: true items: type: string pattern: "^(mcp|a2a|config|scan):[^:]+:sha256:[0-9a-f]{64}$" authoritative_roots: type: array uniqueItems: true items: type: object additionalProperties: false required: [coverage_key, child_coverage_keys] properties: coverage_key: type: string pattern: "^(mcp|a2a|config|scan):(root|instruction-exact-user|instruction-exact-project|instruction-deep):sha256:[0-9a-f]{64}$" child_coverage_keys: type: array uniqueItems: true items: type: string pattern: "^(mcp|a2a|config|scan):[^:]+:sha256:[0-9a-f]{64}$" registry_contract: $ref: "#/components/schemas/InstructionRegistryContractV1" description: Required on recognized config instruction roots and forbidden on all other roots. outcomes: type: array minItems: 1 items: type: object additionalProperties: false required: [collector, coverage_key, target, method, state] properties: collector: type: string enum: [mcp, a2a, config, scan] coverage_key: { type: string } parent_coverage_key: { type: string } target: { type: string, minLength: 1 } method: { type: string, minLength: 1 } state: type: string enum: [unknown, not_applicable, complete, partial, failed, truncated] items: { type: integer, minimum: 0 } error: { type: string } InstructionRegistryContractV1: type: object additionalProperties: false required: [generation, digest] properties: generation: type: integer minimum: 1 digest: type: string pattern: "^sha256:[0-9a-f]{64}$" IngestRulesetV1: type: object additionalProperties: false required: [digest, load_state, authenticity] properties: digest: { type: string, minLength: 1 } entries: type: array items: type: object additionalProperties: false required: [type, id, version, semantic_sha256, source] properties: type: { type: string } id: { type: string } version: { type: integer, minimum: 1 } semantic_sha256: { type: string } source: { type: string } effective_matcher: type: object additionalProperties: true load_state: type: string enum: [unknown, not_applicable, complete, partial, failed, truncated] errors: type: array items: { type: string } authenticity: { type: string, minLength: 1 } IngestIdentitySchemeV1: type: object additionalProperties: false required: [entity_kind, scheme, version] properties: entity_kind: { type: string } transport: { type: string } scheme: { type: string, minLength: 1 } version: { type: integer, minimum: 1 } IngestNodeV1: type: object additionalProperties: false required: [id, kinds, properties, observation_domains] properties: id: { type: string, minLength: 1 } kinds: type: array minItems: 1 items: { type: string } properties: type: object additionalProperties: true observation_domains: type: array minItems: 1 uniqueItems: true items: { type: string } property_semantics: type: string enum: [reference_only] description: Omit for an authoritative property observation. reference_only asserts only id and kinds and requires an empty properties object. IngestEdgeV1: type: object additionalProperties: false required: - source - target - kind - source_kind - target_kind - properties - observation_domains properties: source: { type: string, minLength: 1 } target: { type: string, minLength: 1 } kind: { type: string, minLength: 1 } source_kind: { type: string, minLength: 1 } target_kind: { type: string, minLength: 1 } properties: type: object additionalProperties: true observation_domains: type: array minItems: 1 uniqueItems: true items: { type: string } observation_semantics: type: string enum: [any_owner, all_dependencies] NodeDetail: type: object properties: node: $ref: "#/components/schemas/Node" edges: type: array items: $ref: "#/components/schemas/Edge" SearchResultItem: type: object properties: id: type: string name: type: string kind: type: string NeighborhoodResponse: type: object properties: nodes: type: array items: $ref: "#/components/schemas/Node" edges: type: array items: $ref: "#/components/schemas/Edge" BlastRadiusResponse: type: object properties: nodes: type: array items: $ref: "#/components/schemas/Node" edges: type: array items: $ref: "#/components/schemas/Edge" rings: type: object additionalProperties: type: array items: type: string direction: type: string enum: [out, in, both] max_hops: type: integer PathRequest: type: object additionalProperties: false required: [source, source_kind] properties: source: type: string target: type: string source_kind: type: string target_kind: type: string max_hops: type: integer default: 10 minimum: 1 maximum: 20 limit: type: integer default: 10 minimum: 1 maximum: 100 PathNode: type: object properties: id: type: string name: type: string kinds: type: array items: type: string properties: type: object additionalProperties: true PathEdge: type: object properties: kind: type: string source: type: string target: type: string risk_weight: type: number PathResult: type: object properties: nodes: type: array items: $ref: "#/components/schemas/PathNode" edges: type: array items: $ref: "#/components/schemas/PathEdge" hops: type: integer weight: type: number PathResponse: type: object additionalProperties: false required: [paths, metadata, projection] properties: paths: type: array items: $ref: "#/components/schemas/PathResult" metadata: $ref: "#/components/schemas/TraversalMetadata" projection: $ref: "#/components/schemas/ProjectionIdentity" TraversalMetadata: type: object required: [scope, direction, relationship_kinds, max_hops, algorithm, complete] properties: scope: type: string enum: [topology, security] direction: type: string enum: [out, both] relationship_kinds: type: array items: type: string max_hops: type: integer algorithm: type: string enum: [bounded-min-weight, bounded-enumeration] complete: type: boolean truncated: type: boolean expansion_limit: type: integer expansions: type: integer incomplete_reason: type: string Finding: type: object required: [id, severity, category, title, description, edge_kind, source_id, source_name, source_kind, target_id, target_name, target_kind, confidence, variant, evidence, owasp_map, atlas_map] properties: id: type: string scan_id: type: string captured_at: type: string format: date-time severity: type: string enum: [critical, high, medium, low] category: type: string title: type: string description: type: string edge_kind: type: string source_id: type: string source_name: type: string source_kind: type: string target_id: type: string target_name: type: string target_kind: type: string confidence: type: number variant: type: string enum: - unknown - default - credential_chain_observed_material - credential_chain_reference - credential_node_reference - cross_protocol_host_correlation evidence: $ref: "#/components/schemas/FindingEvidence" owasp_map: type: array items: type: string atlas_map: type: array items: type: string triage: allOf: - $ref: "#/components/schemas/TriageState" nullable: true description: >- Inline triage state for this finding (omitted when no decision has been recorded). Lets the register render the triage control without a per-row round-trip. FindingEvidence: type: object required: [state, channels] properties: state: type: string enum: [unknown, observed_signal, inferred, hypothesis, reference_only, verified] detector: type: string match_type: type: string channels: type: array items: type: string material_status: type: string exposure_status: type: string correlation: type: string proof: $ref: "#/components/schemas/FindingProof" FindingProof: type: object additionalProperties: false required: - action - action_id - verified_at - proof_type - outcome - control_stage - control_status - control_resource_addressed - credential_stage - credential_status - credential_resource_addressed - cleanup_status properties: action: type: string enum: [credential_reach] action_id: type: string minLength: 1 verified_at: type: string format: date-time proof_type: type: string enum: [differential_resource_read] outcome: type: string enum: [credential_required] control_stage: type: string enum: [initialize, resource_read] control_status: type: string enum: [denied] control_resource_addressed: type: boolean credential_stage: type: string enum: [resource_read] credential_status: type: string enum: [allowed] credential_resource_addressed: type: boolean cleanup_status: type: string enum: [not_applicable] TriageState: type: object properties: status: type: string enum: [new, triaging, confirmed, accepted-risk, false-positive] note: type: string updated_at: type: string format: date-time TriageUpdateRequest: type: object additionalProperties: false required: [status] properties: status: type: string enum: [new, triaging, confirmed, accepted-risk, false-positive] note: type: string FindingScope: type: object additionalProperties: false required: [mode, scan_id, revision, published_at, projection_status, snapshot_status, available, stale, coverage_limited, active_coverage_limitations] properties: mode: type: string enum: [published] scan_id: type: string revision: type: integer format: int64 nullable: true published_at: type: string format: date-time nullable: true projection_status: type: string snapshot_status: type: string available: type: boolean stale: type: boolean coverage_limited: type: boolean active_coverage_limitations: type: array items: $ref: "#/components/schemas/PostureCoverageLimitation" FindingsResponse: type: object additionalProperties: false required: [findings, scope] properties: findings: type: array items: $ref: "#/components/schemas/Finding" scope: $ref: "#/components/schemas/FindingScope" FindingDetail: type: object additionalProperties: false required: [finding, attack_path, remediation, impact, snapshot] properties: finding: $ref: "#/components/schemas/Finding" attack_path: allOf: - $ref: "#/components/schemas/AttackPath" nullable: true remediation: type: array items: $ref: "#/components/schemas/RemediationStep" impact: allOf: - $ref: "#/components/schemas/FindingImpact" nullable: true instruction_evidence: $ref: "#/components/schemas/InstructionEvidence" snapshot: type: object additionalProperties: false required: [scope, scan_id, revision, published_at, projection_status, snapshot_status, available, stale, evidence_state] properties: scope: type: string scan_id: type: string revision: type: integer format: int64 nullable: true published_at: type: string format: date-time nullable: true projection_status: type: string snapshot_status: type: string available: type: boolean stale: type: boolean evidence_state: type: string enum: - unavailable - persisted_exact_evidence InstructionEvidence: type: object additionalProperties: false required: [version, verdict, scope, path, type, hash, size_bytes, modified_at, total_signals, truncated, signals] properties: version: type: integer enum: [1] verdict: type: string enum: [signal, poisoning] scope: type: string enum: [exact_project, exact_user, deep] path: type: string type: type: string hash: type: string size_bytes: type: integer format: int64 minimum: 0 modified_at: type: string format: date-time total_signals: type: integer minimum: 1 truncated: type: boolean signals: type: array maxItems: 32 items: $ref: "#/components/schemas/InstructionSignal" InstructionSignal: type: object additionalProperties: false required: [rule_id, label, severity, strength, raw_offset, line, column, match, context_before, context_after] properties: rule_id: type: string label: type: string severity: type: string enum: [low, medium, high, critical] strength: type: string enum: [decisive, primary, supporting] raw_offset: type: integer minimum: 0 line: type: integer minimum: 1 column: type: integer minimum: 1 match: type: string description: Exact raw matched evidence. For an encoded payload larger than the evidence window, this is the bounded source excerpt corresponding to the decisive decoded semantics. context_before: type: string context_after: type: string decoded_excerpt: type: string AttackPath: type: object required: - nodes - edges - shape - continuity - direction - completeness - cost - total_risk_weight properties: nodes: type: array items: $ref: "#/components/schemas/AttackPathNode" edges: type: array items: $ref: "#/components/schemas/AttackPathEdge" shape: type: string enum: [linear, branched, disconnected, cyclic, nodes_only] continuity: $ref: "#/components/schemas/EvidenceContinuity" direction: type: string enum: [forward, reverse, mixed, non_linear, not_applicable] completeness: $ref: "#/components/schemas/EvidenceCompleteness" linearization: $ref: "#/components/schemas/EvidenceLinearization" cost: $ref: "#/components/schemas/AttackCost" total_risk_weight: type: number nullable: true AttackPathNode: type: object required: [id, kinds, properties] properties: id: type: string kinds: type: array items: type: string properties: type: object additionalProperties: true AttackPathEdge: type: object required: [source, target, kind, properties, synthetic] properties: source: type: string target: type: string kind: type: string properties: type: object additionalProperties: true synthetic: type: boolean provenance: $ref: "#/components/schemas/EdgeProvenance" EdgeProvenance: type: object required: [type] properties: type: type: string basis: type: string source_collector: type: string EvidenceContinuity: type: object required: [state, component_count, missing_node_ids] properties: state: type: string enum: [continuous, discontinuous, not_applicable] component_count: type: integer missing_node_ids: type: array items: type: string EvidenceCompleteness: type: object required: [state, reasons] properties: state: type: string enum: [complete, incomplete, not_applicable] reasons: type: array items: type: string EvidenceLinearization: type: object required: [node_ids, edge_indexes] properties: node_ids: type: array items: type: string edge_indexes: type: array items: type: integer AttackCost: type: object required: [state, value, reasons, missing_weight_edge_indexes] properties: state: type: string enum: [complete, incomplete, not_applicable] value: type: number nullable: true reasons: type: array items: type: string missing_weight_edge_indexes: type: array items: type: integer RemediationActor: type: object required: [id, name, kind] properties: id: type: string name: type: string kind: type: string RemediationStep: type: object required: [step, title, description, edge_kind, source, target] properties: step: type: integer title: type: string description: type: string edge_kind: type: string source: $ref: "#/components/schemas/RemediationActor" target: $ref: "#/components/schemas/RemediationActor" channels: type: array items: type: string commands: type: array items: type: string FindingImpact: type: object required: [summary, blast_radius] properties: summary: type: string blast_radius: type: string data_sensitivity: type: string PreBuiltQuery: type: object properties: id: type: string name: type: string description: type: string category: type: string severity: type: string owasp_map: type: array items: type: string atlas_map: type: array items: type: string PreBuiltResult: type: object additionalProperties: false required: [query, rows, projection] properties: query: $ref: "#/components/schemas/PreBuiltQuery" rows: type: array items: type: object additionalProperties: true projection: $ref: "#/components/schemas/ProjectionIdentity" metadata: $ref: "#/components/schemas/TraversalMetadata" Rule: type: object properties: id: type: string name: type: string description: type: string version: type: integer enabled: type: boolean severity: type: string scope: type: object properties: collector: type: string targets: type: array items: type: string owasp: type: array items: type: string tags: type: array items: type: string source: type: string RuleListResponse: type: object additionalProperties: false required: [rules, total] properties: rules: type: array items: $ref: "#/components/schemas/Rule" total: type: integer minimum: 0 NormalizationWarning: type: object additionalProperties: false required: [code, status, message, publication_unsafe] properties: code: type: string minLength: 1 status: type: string enum: [warning, degraded] message: type: string minLength: 1 context: type: string property: type: string publication_unsafe: type: boolean FactCounts: type: object additionalProperties: false required: [nodes, edges] properties: nodes: { type: integer, minimum: 0 } edges: { type: integer, minimum: 0 } InventoryTotals: type: object additionalProperties: false required: [node_counts, edge_counts, total_nodes, total_edges] properties: node_counts: type: object additionalProperties: { type: integer, format: int64, minimum: 0 } edge_counts: type: object additionalProperties: { type: integer, format: int64, minimum: 0 } total_nodes: { type: integer, format: int64, minimum: 0 } total_edges: { type: integer, format: int64, minimum: 0 } FrozenGraphTotals: type: object additionalProperties: false required: [before, after] properties: before: allOf: - $ref: "#/components/schemas/InventoryTotals" nullable: true after: allOf: - $ref: "#/components/schemas/InventoryTotals" nullable: true IngestResult: type: object additionalProperties: false required: [scan_id, outcome, projection_status, submitted, write_rows, findings, graph_totals, normalization_status, collection, identity, duration] properties: scan_id: type: string outcome: type: string enum: [unknown, complete, partial, failed] projection_status: type: string enum: [complete, incomplete] submitted: $ref: "#/components/schemas/FactCounts" write_rows: $ref: "#/components/schemas/FactCounts" findings: type: integer minimum: 0 graph_totals: $ref: "#/components/schemas/FrozenGraphTotals" warnings: type: array items: type: string normalization_status: type: string enum: [complete, warning, degraded] normalization_warnings: type: array items: $ref: "#/components/schemas/NormalizationWarning" collection: $ref: "#/components/schemas/IngestCollectionV1" identity: $ref: "#/components/schemas/IngestIdentityResult" post_processing_stats: type: array items: type: object additionalProperties: false required: [processor_name, edges_created, nodes_updated, duration] properties: processor_name: type: string minLength: 1 edges_created: type: integer minimum: 0 nodes_updated: type: integer minimum: 0 duration: type: integer minimum: 0 error: type: string stages: type: array items: type: object additionalProperties: false required: [name, state, required, duration] properties: name: type: string minLength: 1 state: type: string enum: [unknown, not_applicable, complete, partial, failed, truncated] required: type: boolean duration: type: integer minimum: 0 error: type: string published_revision: type: integer format: int64 minimum: 1 duration: type: integer minimum: 0 description: Duration in nanoseconds IngestIdentityResult: type: object additionalProperties: false required: [collection_point_id, network_context_id, quality, network_quality, network_class, recognition] properties: collection_point_id: { type: string, pattern: "^sha256:[0-9a-f]{64}$" } network_context_id: { type: string, pattern: "^sha256:[0-9a-f]{64}$" } quality: { type: string, enum: [strong, weak] } network_quality: { type: string, enum: [strong, unknown] } network_class: { type: string, enum: [unknown, offline, private, public, mixed] } display: $ref: "#/components/schemas/CollectionDisplayLabels" recognition: { type: string, enum: [new, recognized, unknown] } Scan: type: object required: [id, collector, status, started_at, submitted, write_rows, graph_totals] properties: id: type: string collector: type: string status: type: string enum: [pending, running, completed, completed_with_errors, failed] started_at: type: string format: date-time completed_at: type: string format: date-time artifact_observed_at: type: string format: date-time submitted: $ref: "#/components/schemas/FactCounts" write_rows: $ref: "#/components/schemas/FactCounts" graph_totals: type: object additionalProperties: false required: [before, after] properties: before: allOf: - $ref: "#/components/schemas/ScanGraphTotal" nullable: true after: allOf: - $ref: "#/components/schemas/ScanGraphTotal" nullable: true error: type: string collection_status: type: string graph_status: type: string analysis_status: type: string snapshot_status: type: string projection_status: type: string publication_status: type: string comparison_key: type: string comparable_to_scan_id: type: string published_revision: type: integer format: int64 published_at: type: string format: date-time metadata: type: object additionalProperties: true ScanGraphTotal: type: object additionalProperties: false required: [total_nodes, total_edges] properties: total_nodes: { type: integer, format: int64, minimum: 0 } total_edges: { type: integer, format: int64, minimum: 0 } ScanPageMetadata: type: object additionalProperties: false required: [offset, limit, total, has_more, complete, revision] properties: offset: { type: integer, minimum: 0 } limit: { type: integer, minimum: 1 } total: { type: integer, format: int64, minimum: 0 } has_more: { type: boolean } complete: { type: boolean } revision: { type: string, minLength: 1 } ScanListResponse: type: object additionalProperties: false required: [scans, page] properties: scans: type: array items: $ref: "#/components/schemas/Scan" page: $ref: "#/components/schemas/ScanPageMetadata" ProjectionState: type: object additionalProperties: false required: [status, dirty_coverage, active_coverage_roots, active_coverage_limitations, updated_at] properties: status: type: string enum: [unknown, updating, incomplete, complete] scan_id: type: string error: type: string dirty_coverage: type: array items: type: string active_coverage_roots: type: array items: $ref: "#/components/schemas/PostureCoverageRoot" active_coverage_limitations: type: array items: $ref: "#/components/schemas/PostureCoverageLimitation" updated_at: type: string format: date-time published_scan_id: type: string published_revision: type: integer format: int64 published_at: type: string format: date-time PostureCoverageRoot: type: object additionalProperties: false required: - coverage_key - mode - state - scan_id - observed_at - registry_contract - contract_current properties: coverage_key: type: string pattern: "^config:instruction-(exact-user|exact-project|deep):sha256:[0-9a-f]{64}$" mode: type: string enum: [exact_user, exact_project, deep] state: type: string enum: [complete, truncated, partial, failed] scan_id: type: string minLength: 1 observed_at: type: string format: date-time registry_contract: $ref: "#/components/schemas/InstructionRegistryContractV1" contract_current: type: boolean PostureCoverageLimitation: type: object additionalProperties: false required: - coverage_key - state - scan_id - observed_at properties: coverage_key: type: string minLength: 1 parent_coverage_key: type: string minLength: 1 state: type: string enum: [unknown, partial, failed, truncated] scan_id: type: string minLength: 1 observed_at: type: string format: date-time PostureScope: type: object additionalProperties: false required: - scan_id - revision - coverage_keys - active_coverage_keys - active_coverage_roots - active_coverage_limitations - dirty_coverage - projection_state properties: scan_id: type: string minLength: 1 revision: type: integer format: int64 minimum: 1 coverage_keys: type: array items: type: string active_coverage_keys: type: array items: type: string active_coverage_roots: type: array items: $ref: "#/components/schemas/PostureCoverageRoot" active_coverage_limitations: type: array items: $ref: "#/components/schemas/PostureCoverageLimitation" dirty_coverage: type: array items: type: string comparison_key: type: string projection_state: type: string enum: [complete] PostureExport: type: object additionalProperties: false description: Immutable persisted export of one published posture revision. required: - schema_version - scope - completeness - observations - health - limits - suppression - graph_after - comparison - findings properties: schema_version: type: integer enum: [1] scope: $ref: "#/components/schemas/PostureScope" completeness: type: object additionalProperties: true observations: type: object additionalProperties: true health: type: object required: [state, captured] properties: state: type: string enum: [not_captured, ok, degraded] captured: type: boolean observed_at: type: string format: date-time limits: type: object properties: findings: type: object required: [returned, total, complete] properties: returned: type: integer total: type: integer complete: type: boolean suppression: type: object additionalProperties: true graph_before: type: object additionalProperties: true graph_after: type: object additionalProperties: true comparison: type: object additionalProperties: true collection: $ref: "#/components/schemas/IngestCollectionV1" ruleset: $ref: "#/components/schemas/IngestRulesetV1" identity_schemes: type: array items: $ref: "#/components/schemas/IngestIdentitySchemeV1" findings: type: array items: $ref: "#/components/schemas/Finding" CreateScanRequest: type: object required: [collector] properties: collector: type: string enum: [mcp, a2a, config] metadata: type: object additionalProperties: true QueryRequest: type: object required: [cypher] properties: cypher: type: string params: type: object additionalProperties: true QueryResponse: type: object properties: rows: type: array items: type: object additionalProperties: true responses: ValidationError: description: Invalid request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" NotFound: description: Resource not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" Forbidden: description: Origin not in allowlist content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" ProjectionConflict: description: Stable complete published graph projection unavailable or changed during the read content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" paths: /health: get: summary: Health check description: Returns Neo4j and PostgreSQL connectivity status. operationId: getHealth tags: [Public] responses: "200": description: All services healthy content: application/json: schema: $ref: "#/components/schemas/HealthResponse" "503": description: One or more services unavailable content: application/json: schema: $ref: "#/components/schemas/HealthResponse" /docs: get: summary: OpenAPI specification description: Returns this OpenAPI 3.0.3 specification as YAML. operationId: getDocs tags: [Public] responses: "200": description: OpenAPI spec content: application/yaml: schema: type: string /graph/stats: get: summary: Graph statistics description: Returns node and edge counts grouped by kind. operationId: getGraphStats tags: [Graph] responses: "200": description: Stats retrieved content: application/json: schema: $ref: "#/components/schemas/GraphStats" "409": $ref: "#/components/responses/ProjectionConflict" /graph/search: get: summary: Search graph nodes description: Free-text search over node properties. operationId: searchGraph tags: [Graph] parameters: - name: q in: query required: true schema: type: string - name: limit in: query schema: type: integer default: 20 minimum: 1 maximum: 100 responses: "200": description: Search results content: application/json: schema: type: array items: $ref: "#/components/schemas/SearchResultItem" "409": $ref: "#/components/responses/ProjectionConflict" /graph/nodes: get: summary: List nodes description: List graph nodes with optional kind filter. operationId: listNodes tags: [Graph] parameters: - name: kind in: query schema: type: string description: Filter by node label (e.g. MCPServer, MCPTool) - name: limit in: query schema: type: integer default: 100 minimum: 1 maximum: 10000 - name: offset in: query schema: type: integer default: 0 minimum: 0 - name: revision in: query schema: type: string description: Opaque page.revision value from the first page. responses: "200": description: Nodes list content: application/json: schema: $ref: "#/components/schemas/NodeListResponse" "409": description: Graph revision changed, or the stable complete published projection is unavailable. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /graph/nodes/{id}: get: summary: Get node description: Returns a single node with all connected edges. operationId: getNode tags: [Graph] parameters: - name: id in: path required: true schema: type: string responses: "200": description: Node with edges content: application/json: schema: $ref: "#/components/schemas/NodeDetail" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/ProjectionConflict" /graph/nodes/{id}/neighborhood: get: summary: Node neighborhood description: Returns the immediate (or N-hop) neighborhood of a node. operationId: getNodeNeighborhood tags: [Graph] parameters: - name: id in: path required: true schema: type: string - name: depth in: query schema: type: integer default: 1 minimum: 1 maximum: 3 responses: "200": description: Neighborhood subgraph content: application/json: schema: $ref: "#/components/schemas/NeighborhoodResponse" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/ProjectionConflict" /graph/nodes/{id}/blast-radius: get: summary: Node blast radius description: >- Returns nodes reachable from (or to) the given node up to `max_hops`, grouped by ring distance. operationId: getNodeBlastRadius tags: [Graph] parameters: - name: id in: path required: true schema: type: string - name: direction in: query schema: type: string enum: [out, in, both] default: out - name: max_hops in: query schema: type: integer default: 6 minimum: 1 maximum: 10 responses: "200": description: Blast radius subgraph content: application/json: schema: $ref: "#/components/schemas/BlastRadiusResponse" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/ProjectionConflict" /graph/edges: get: summary: List edges description: List graph edges with optional filters. operationId: listEdges tags: [Graph] parameters: - name: kind in: query schema: type: string description: Filter by edge kind (e.g. TRUSTS_SERVER, CAN_REACH) - name: source in: query schema: type: string description: Filter by source node ID - name: target in: query schema: type: string description: Filter by target node ID - name: limit in: query schema: type: integer default: 100 minimum: 1 maximum: 100000 - name: offset in: query schema: type: integer default: 0 minimum: 0 - name: revision in: query schema: type: string description: Opaque page.revision value from the first page. responses: "200": description: Edges list content: application/json: schema: $ref: "#/components/schemas/EdgeListResponse" "409": description: Graph revision changed, or the stable complete published projection is unavailable. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /ingest: post: summary: Ingest collector output description: >- Upload strict ingest-v1 collector JSON. Before generic validation or lifecycle/audit writes, the server reverifies the automatically paired PostgreSQL and Neo4j markers. Non-V1, malformed, or inconsistent derived identity, unknown structural fields, unscoped facts, property aliases, and incomplete canonical evidence metadata are rejected before graph writes. Every valid artifact is accepted; the server scopes ambiguous identities and lifecycle ownership from the artifact's collection point and network context. Max body 100 MB. operationId: ingest tags: [Ingest] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/IngestV1" responses: "200": description: Ingest successful content: application/json: schema: $ref: "#/components/schemas/IngestResult" "400": description: Invalid payload, unsupported ingest version, or instruction registry contract mismatch. content: application/json: schema: oneOf: - $ref: "#/components/schemas/ErrorResponse" - $ref: "#/components/schemas/IngestAdmissionErrorResponse" "403": $ref: "#/components/responses/Forbidden" "500": description: Ingest failed before or after graph mutation. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "503": description: PostgreSQL/Neo4j immutable storage binding could not be verified. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /analysis/shortest-path: post: summary: Shortest path description: >- Find a hop-shortest bounded path using the directed security relationship policy. operationId: shortestPath tags: [Analysis] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PathRequest" responses: "200": description: Paths found content: application/json: schema: $ref: "#/components/schemas/PathResponse" "400": $ref: "#/components/responses/ValidationError" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/ProjectionConflict" /analysis/all-paths: post: summary: All paths description: >- Enumerate directed security paths, bounded by max_hops, limit, and the server expansion cap. operationId: allPaths tags: [Analysis] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PathRequest" responses: "200": description: Paths found content: application/json: schema: $ref: "#/components/schemas/PathResponse" "400": $ref: "#/components/responses/ValidationError" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/ProjectionConflict" /analysis/weighted-path: post: summary: Weighted (lowest-risk) path description: >- Find the bounded minimum-risk-weight path with one deployment-independent directed security algorithm. Every traversed edge must have an explicit non-negative finite risk_weight. operationId: weightedPath tags: [Analysis] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PathRequest" responses: "200": description: Weighted path found content: application/json: schema: $ref: "#/components/schemas/PathResponse" "400": $ref: "#/components/responses/ValidationError" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/ProjectionConflict" /analysis/topology/shortest-path: post: summary: Topology shortest path description: Find a hop-shortest path over explicit undirected topology traversal. operationId: topologyShortestPath tags: [Analysis] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PathRequest" responses: "200": description: Topology paths found content: application/json: schema: $ref: "#/components/schemas/PathResponse" "400": $ref: "#/components/responses/ValidationError" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/ProjectionConflict" /analysis/topology/all-paths: post: summary: All topology paths description: Enumerate bounded undirected topology paths. operationId: topologyAllPaths tags: [Analysis] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PathRequest" responses: "200": description: Topology paths found content: application/json: schema: $ref: "#/components/schemas/PathResponse" "400": $ref: "#/components/responses/ValidationError" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/ProjectionConflict" /analysis/topology/weighted-path: post: summary: Weighted topology path description: >- Find a bounded minimum-risk-weight path over undirected topology. Every traversed edge must have an explicit non-negative finite risk_weight. operationId: topologyWeightedPath tags: [Analysis] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PathRequest" responses: "200": description: Weighted topology path found content: application/json: schema: $ref: "#/components/schemas/PathResponse" "400": $ref: "#/components/responses/ValidationError" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/ProjectionConflict" /analysis/findings: get: summary: Security findings description: >- Returns exactly the immutable currently published scan snapshot with publication/completeness metadata in the response body. Each row includes inline triage. operationId: getFindings tags: [Analysis] parameters: - name: severity in: query schema: type: string enum: [critical, high, medium, low] - name: include_suppressed in: query description: When true, include accepted-risk / false-positive findings. schema: type: boolean default: false responses: "200": description: Findings list content: application/json: schema: $ref: "#/components/schemas/FindingsResponse" /findings/triage/{fingerprint}: get: summary: Get finding triage state description: >- Returns the cross-scan triage decision for a finding fingerprint. Open read. A fingerprint with no recorded decision returns the implicit `new` state. operationId: getTriage tags: [Analysis] parameters: - name: fingerprint in: path required: true schema: type: string description: 16-character hex finding fingerprint responses: "200": description: Triage state content: application/json: schema: $ref: "#/components/schemas/TriageState" "400": $ref: "#/components/responses/ValidationError" patch: summary: Patch finding triage state description: >- Updates the triage decision for a finding fingerprint. Omitting note preserves the current analyst note; an explicit empty note clears it. Triage state has no foreign key to findings, so it survives scan deletion and re-detection. operationId: setTriage tags: [Analysis] parameters: - name: fingerprint in: path required: true schema: type: string description: 16-character hex finding fingerprint requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TriageUpdateRequest" responses: "200": description: Updated triage state content: application/json: schema: $ref: "#/components/schemas/TriageState" "400": $ref: "#/components/responses/ValidationError" "403": $ref: "#/components/responses/Forbidden" /analysis/findings/{id}: get: summary: Finding detail description: >- Returns the typed evidence subgraph and context for a finding in the immutable currently published snapshot. Mutable Neo4j is never used as a detail fallback. operationId: getFindingDetail tags: [Analysis] parameters: - name: id in: path required: true schema: type: string responses: "200": description: Finding detail content: application/json: schema: $ref: "#/components/schemas/FindingDetail" "404": $ref: "#/components/responses/NotFound" /analysis/prebuilt: get: summary: List pre-built queries description: Returns metadata for all 19 pre-built security queries. operationId: listPreBuilt tags: [Analysis] responses: "200": description: Query list content: application/json: schema: type: array items: $ref: "#/components/schemas/PreBuiltQuery" /analysis/prebuilt/{id}: get: summary: Execute pre-built query description: Run a pre-built query by ID and return results. operationId: runPreBuilt tags: [Analysis] parameters: - name: id in: path required: true schema: type: string responses: "200": description: Query results content: application/json: schema: $ref: "#/components/schemas/PreBuiltResult" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/ProjectionConflict" /posture: get: summary: Projection and publication state description: >- Separates the mutable projection attempt from the latest persisted published posture revision. operationId: getPostureState tags: [Analysis] responses: "200": description: Current projection/publication state content: application/json: schema: $ref: "#/components/schemas/ProjectionState" /posture/export: get: summary: Export the published posture description: >- Returns one immutable export persisted at publication time. The server does not combine current graph, finding, or scan-history reads. operationId: exportPublishedPosture tags: [Analysis] responses: "200": description: Persisted published posture export content: application/json: schema: $ref: "#/components/schemas/PostureExport" "404": $ref: "#/components/responses/NotFound" /scans: get: summary: List scans description: List scan history with pagination. operationId: listScans tags: [Scans] parameters: - name: limit in: query schema: type: integer default: 50 - name: offset in: query schema: type: integer default: 0 minimum: 0 - name: revision in: query schema: type: string description: Opaque page.revision value from the first page. - name: order in: query schema: type: string enum: [started, completed, published] default: started description: Stable start order, latest usable completion, or current/latest publication order. responses: "200": description: Scan list content: application/json: schema: $ref: "#/components/schemas/ScanListResponse" "409": description: Scan history revision changed; restart pagination at offset 0. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" post: summary: Create scan description: Register a new scan. operationId: createScan tags: [Scans] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateScanRequest" responses: "201": description: Scan created content: application/json: schema: $ref: "#/components/schemas/Scan" "400": $ref: "#/components/responses/ValidationError" "403": $ref: "#/components/responses/Forbidden" /scans/{id}: get: summary: Get scan description: Get scan details by ID. operationId: getScan tags: [Scans] parameters: - name: id in: path required: true schema: type: string responses: "200": description: Scan details content: application/json: schema: $ref: "#/components/schemas/Scan" "404": $ref: "#/components/responses/NotFound" delete: summary: Delete scan description: >- Delete only PostgreSQL scan history. Never mutates Neo4j. Pending, running, active coverage-head, and currently published scans are rejected. operationId: deleteScan tags: [Scans] parameters: - name: id in: path required: true schema: type: string responses: "204": description: Scan deleted "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": description: Scan is active, owns a coverage head, or is currently published. /rules: get: summary: List detection rules description: Returns metadata for every loaded detection rule (builtin and custom). operationId: listRules tags: [Rules] parameters: - name: collector in: query schema: type: string enum: [mcp, a2a, config, all] - name: severity in: query schema: type: string enum: [critical, high, medium, low, info] - name: tag in: query schema: type: string responses: "200": description: Rule list content: application/json: schema: $ref: "#/components/schemas/RuleListResponse" /rules/{id}: get: summary: Get rule description: Returns the full definition of a single detection rule. operationId: getRule tags: [Rules] parameters: - name: id in: path required: true schema: type: string responses: "200": description: Rule content: application/json: schema: $ref: "#/components/schemas/Rule" "404": $ref: "#/components/responses/NotFound" /query: post: summary: Raw Cypher query description: >- Execute a raw Cypher query against Neo4j. Browser callers are gated by OriginGuard (Origin allowlist); CLI users bypass HTTP entirely via `agenthound-server query`. operationId: rawQuery tags: [Admin] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/QueryRequest" responses: "200": description: Query results content: application/json: schema: $ref: "#/components/schemas/QueryResponse" "400": $ref: "#/components/responses/ValidationError" "403": $ref: "#/components/responses/Forbidden"