API Reference

This page documents the JSON output schemas for unfault review and unfault ask. These are useful when parsing CLI output programmatically or building integrations.

Tip

For background on core concepts, see Facts and Workspaces & Sessions.

Review Output

When you run unfault review --output json, the CLI returns a JSON object with the analysis results.

Response Schema

{
  "session_id": "string",
  "status": "created | analyzing | completed | failed | expired",
  "meta": { ... },
  "contexts": [ ... ],
  "elapsed_ms": 142,
  "error_message": "string | null"
}

Fields

Field	Type	Description
session_id	string	Unique identifier for this analysis session
status	enum	Session status: created, analyzing, completed, failed, expired
meta	object	Metadata about the analysis (see below)
contexts	array	Analysis results grouped by context (see below)
elapsed_ms	integer	Time taken for analysis in milliseconds
error_message	string | null	Error details if analysis failed

Meta Object

{
  "label": "payments-service",
  "languages": ["python"],
  "framework_guesses": ["fastapi"],
  "requested_dimensions": ["stability", "correctness"]
}

Field	Type	Description
label	string	Workspace label (usually directory name)
languages	array	Detected programming languages
framework_guesses	array	Detected frameworks (e.g., fastapi, express)
requested_dimensions	array	Dimensions that were analyzed

Context Object

Each context groups facts together. Currently, the primary fact type is rule_finding (shown as “findings” in the output):

{
  "context_id": "ctx_workspace",
  "label": "Workspace",
  "findings": [ ... ]
}

Finding Object (rule_finding fact type)

A finding is a fact produced by rule analysis. It represents a detected pattern in your code:

{
  "id": "python.http.missing_timeout:api/client.py:42",
  "rule_id": "python.http.missing_timeout",
  "kind": "StabilityRisk",
  "title": "HTTP call has no timeout",
  "description": "This HTTP call via requests.get has no timeout specified...",
  "severity": "High",
  "confidence": 0.9,
  "dimension": "stability",
  "file_path": "api/client.py",
  "line": 42,
  "column": 5,
  "end_line": 42,
  "end_column": 45,
  "fix_preview": "Add timeout parameter: requests.get(url, timeout=30)"
}

Field	Type	Description
id	string	Unique finding identifier (format: rule_id:file_path:line)
rule_id	string	Rule that produced this finding
kind	enum	Finding category (see below)
title	string	Short title
description	string	Detailed explanation
severity	enum	Critical, High, Medium, Low, Info
confidence	float	Confidence score (0.0 to 1.0)
dimension	string	Which dimension this finding relates to
file_path	string	File path where the finding was detected
line	integer	Line number (1-based)
column	integer | null	Column number (1-based)
end_line	integer | null	End line number
end_column	integer | null	End column number
fix_preview	string | null	Human-readable summary of suggested fix

Finding Kinds

Kind	Description
StabilityRisk	Could cause service instability or outages
PerformanceSmell	May impact performance
BehaviorThreat	Unexpected behavior under certain conditions
AntiPattern	Code pattern that typically leads to problems
ResourceLeak	Potential resource leak (connections, memory)
ReliabilityRisk	Could affect service reliability
SecurityVulnerability	Security concern

Severity Levels

Severity	Description
Critical	Immediate action required
High	Should be addressed soon
Medium	Worth addressing
Low	Minor improvement
Info	Informational

Dimensions

Dimension	Description
stability	Service stability and resilience
performance	Execution speed and resource usage
correctness	Logic and behavior correctness
scalability	Ability to handle increased load
observability	Logging, tracing, and monitoring
reliability	Consistent operation over time
security	Security posture
maintainability	Code maintainability

Complete Example

{
  "session_id": "sess_abc123def456",
  "status": "completed",
  "meta": {
    "label": "payments-service",
    "languages": ["python"],
    "framework_guesses": ["fastapi"],
    "requested_dimensions": ["stability", "correctness"]
  },
  "contexts": [
    {
      "context_id": "ctx_workspace",
      "label": "Workspace",
      "findings": [
        {
          "id": "python.http.missing_timeout:src/client.py:42",
          "rule_id": "python.http.missing_timeout",
          "kind": "StabilityRisk",
          "title": "HTTP call has no timeout",
          "description": "This HTTP call via requests.get has no timeout specified. If the remote service is slow or unresponsive, this call will block indefinitely.",
          "severity": "High",
          "confidence": 0.9,
          "dimension": "stability",
          "file_path": "src/client.py",
          "line": 42,
          "column": 5,
          "fix_preview": "Add timeout parameter: requests.get(url, timeout=30)"
        }
      ]
    }
  ],
  "elapsed_ms": 142,
  "error_message": null
}

---

Facts Model

Facts are the underlying data model for all observations Unfault makes about your code. The review output above uses the rule_finding fact type, presented as “findings” for backward compatibility.

Fact Schema

{
  "fact_type": "rule_finding",
  "fact_key": "python.http.missing_timeout:src/client.py:42",
  "severity": "High",
  "dimension": "stability",
  "file_path": "src/client.py",
  "line": 42,
  "column": 5,
  "rule_id": "python.http.missing_timeout",
  "payload": { ... }
}

Field	Type	Description
fact_type	string	Type discriminator (e.g., rule_finding, slo_state)
fact_key	string	Unique key for deduplication within a session
severity	enum	Critical, High, Medium, Low, Info
dimension	string	Which dimension this fact relates to
file_path	string | null	File path if location-specific
line	integer | null	Line number (1-based)
column	integer | null	Column number (1-based)
rule_id	string | null	Rule ID for rule_finding facts
payload	object	Fact-type-specific data

Fact Types

Type	Description	Status
rule_finding	Pattern detected by a rule	Available
slo_state	SLO compliance snapshot	Coming soon

Note

The facts model is extensible. New fact types will be added as Unfault learns to observe more aspects of your codebase.

rule_finding Payload

For fact_type: "rule_finding", the payload contains the full finding details:

{
  "finding_id": "python.http.missing_timeout:src/client.py:42",
  "rule_id": "python.http.missing_timeout",
  "kind": "StabilityRisk",
  "title": "HTTP call has no timeout",
  "description": "This HTTP call via requests.get has no timeout specified...",
  "confidence": 0.9,
  "fix_preview": "Add timeout parameter: requests.get(url, timeout=30)"
}

---

Ask Output

When you run unfault ask "query" --json, the CLI returns context retrieved from past analyses.

Response Schema

{
  "query": "string",
  "sessions": [ ... ],
  "findings": [ ... ],
  "sources": [ ... ],
  "context_summary": "string",
  "graph_context": { ... } | null,
  "flow_context": { ... } | null,
  "slo_context": { ... } | null
}

Fields

Field	Type	Description
query	string	Original query
sessions	array	Retrieved session contexts
findings	array	Retrieved finding contexts
sources	array	All sources used in retrieval
context_summary	string	Brief summary for LLM consumption
graph_context	object | null	Graph-based context for structural queries
flow_context	object | null	Call flow context for path tracing
slo_context	object | null	SLO context for observability queries

Session Context

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_label": "payments-service",
  "created_at": "2025-01-10T12:00:00Z",
  "similarity": 0.85,
  "total_findings": 5,
  "dimension_counts": { "stability": 2, "performance": 3 },
  "severity_counts": { "High": 1, "Medium": 4 }
}

Field	Type	Description
session_id	string	Session identifier
workspace_label	string	Workspace name
created_at	datetime	When the session was created
similarity	float	Similarity score to the query (0.0 to 1.0)
total_findings	integer	Total findings in this session
dimension_counts	object	Findings count by dimension
severity_counts	object	Findings count by severity

Finding Context

{
  "finding_id": "python.http.timeout:api/client.py:42",
  "rule_id": "python.http.timeout",
  "dimension": "stability",
  "severity": "High",
  "file_path": "api/client.py",
  "line": 42,
  "similarity": 0.78
}

Field	Type	Description
finding_id	string	Finding identifier
rule_id	string	Rule ID
dimension	string	Dimension
severity	string	Severity level
file_path	string	File path
line	integer	Line number
similarity	float	Similarity score to the query

Graph Context

Returned for structural queries like “What breaks if I change this file?”:

{
  "query_type": "impact",
  "target_file": "src/core/auth.py",
  "affected_files": [
    { "path": "src/api/routes.py", "depth": 1 },
    { "path": "src/api/middleware.py", "depth": 2 }
  ],
  "dependencies": [],
  "library_users": []
}

Field	Type	Description
query_type	string	Type: impact, dependency, or general
target_file	string	File being analyzed
affected_files	array	Files affected by changes to target
dependencies	array	External dependencies of target
library_users	array	Files using a specific library

Flow Context

Returned for call path queries like “How does authentication work?”:

{
  "query": "authentication",
  "root_nodes": [
    {
      "node_id": "func_validate_token",
      "name": "validate_token",
      "path": "src/auth.py",
      "node_type": "function",
      "depth": 0
    }
  ],
  "paths": [
    [
      { "node_id": "route_login", "name": "POST /login", "node_type": "api_route", "depth": 0 },
      { "node_id": "func_authenticate", "name": "authenticate", "node_type": "function", "depth": 1 },
      { "node_id": "func_validate_token", "name": "validate_token", "node_type": "function", "depth": 2 }
    ]
  ]
}

SLO Context

Returned for observability queries:

{
  "slos": [
    {
      "name": "API Availability",
      "provider": "gcp",
      "target_percent": 99.9,
      "current_percent": 99.95,
      "error_budget_remaining": 0.05
    }
  ],
  "monitored_routes": [
    { "name": "GET /api/users", "file": "src/routes.py" }
  ],
  "unmonitored_routes": [
    { "name": "POST /internal/sync", "file": "src/internal.py" }
  ],
  "summary": "3 SLOs linked to 15 routes, 2 routes unmonitored"
}

Complete Example

{
  "query": "What are my main stability concerns?",
  "sessions": [
    {
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "workspace_label": "payments-service",
      "created_at": "2025-01-10T12:00:00Z",
      "similarity": 0.85,
      "total_findings": 5,
      "dimension_counts": { "stability": 3, "correctness": 2 },
      "severity_counts": { "High": 2, "Medium": 3 }
    }
  ],
  "findings": [
    {
      "finding_id": "python.http.missing_timeout:src/client.py:42",
      "rule_id": "python.http.missing_timeout",
      "dimension": "stability",
      "severity": "High",
      "file_path": "src/client.py",
      "line": 42,
      "similarity": 0.92
    },
    {
      "finding_id": "python.resilience.missing_circuit_breaker:src/client.py:55",
      "rule_id": "python.resilience.missing_circuit_breaker",
      "dimension": "stability",
      "severity": "High",
      "file_path": "src/client.py",
      "line": 55,
      "similarity": 0.88
    }
  ],
  "sources": [
    {
      "source_type": "session",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "similarity": 0.85,
      "metadata": { "total_findings": 5 }
    },
    {
      "source_type": "finding",
      "id": "python.http.missing_timeout:src/client.py:42",
      "similarity": 0.92,
      "metadata": {}
    }
  ],
  "context_summary": "Retrieved 1 session for payments-service with 5 findings. Main stability concerns: HTTP calls without timeouts, missing circuit breakers.",
  "graph_context": null,
  "flow_context": null,
  "slo_context": null
}

---

Exit Codes

Both commands use exit codes to indicate results:

Code	Meaning
0	Success, no findings
1	General error
2	Configuration error
3	Authentication failed
4	Network error
5	Findings detected
6	Invalid input
7	Service unavailable
8	Session error
10	Subscription required

Tip

Exit code 5 indicates findings were detected - this is not an error. Use it in CI to gate deployments.