Giulia REST API Reference

Document version: Build 155 · v0.2.1 · 2026-03-28

Complete reference for all REST API endpoints exposed by the Giulia daemon on port 4000.

Base URL: http://localhost:4000

Content-Type: All POST endpoints accept application/json. All responses return application/json unless otherwise noted.

Path Convention: Most GET endpoints under /api/index and /api/knowledge require ?path=P where P is the host-side project path (e.g., C:/Development/GitHub/MyApp). POST endpoints take path in the JSON body. The PathMapper translates host paths to container paths automatically.

Authentication: REST endpoints have no authentication. The MCP endpoint (/mcp) requires a Bearer token via the GIULIA_MCP_KEY environment variable. Giulia is a local development tool designed for localhost access only. It is not designed for network exposure -- do not bind to 0.0.0.0 or expose port 4000 to untrusted networks. See SECURITY.md for the full threat model.

MCP Access: All tool endpoints are also available via the Model Context Protocol at /mcp. See the MCP section for setup and usage.

Core (10 endpoints)
Index (9 endpoints)
Knowledge (24 endpoints)
Intelligence (5 endpoints)
Runtime (16 endpoints)
Search (3 endpoints)
Transaction (3 endpoints)
Approval (2 endpoints)
Monitor (7 endpoints)
Discovery (4 endpoints)
MCP (Model Context Protocol)

Core

Root-level endpoints defined in Giulia.Daemon.Endpoint. These handle health checks, command execution, project management, and debugging.

GET /health

Health check. Returns daemon status, Erlang node name, and version.

Parameters: None.

Example:

curl http://localhost:4000/health

Response:

{
  "status": "ok",
  "node": "worker@giulia-worker",
  "version": "0.6.0-build.137"
}

POST /api/command

Main command endpoint. Accepts either a structured command or a free-text chat message for LLM inference.

Parameters (JSON body):

Field	Required	Description
`message`	Yes*	Free-text prompt for LLM inference
`command`	Yes*	Structured command (`init`, `status`, `projects`)
`path`	Yes	Host-side project path

*One of message or command is required.

Example (chat):

curl -X POST http://localhost:4000/api/command \
  -H "Content-Type: application/json" \
  -d '{"message": "List all modules", "path": "C:/Development/GitHub/Giulia"}'

Response:

{
  "status": "ok",
  "response": "Indexed modules:\n- Giulia.Application\n- Giulia.Client\n..."
}

POST /api/command/stream

SSE streaming inference. Returns a chunked text/event-stream response with real-time inference steps.

Parameters (JSON body):

Field	Required	Description
`message`	Yes	Free-text prompt
`path`	Yes	Host-side project path

Example:

curl -N -X POST http://localhost:4000/api/command/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "Explain the supervision tree", "path": "C:/Development/GitHub/Giulia"}'

Response (SSE):

event: start
data: {"request_id": "#Ref<0.1234.5.6>"}

event: step
data: {"type": "think", "content": "..."}

event: complete
data: {"type": "complete", "response": "The supervision tree..."}

POST /api/ping

Lightweight ping. Checks whether a project context is active for the given path.

Parameters (JSON body):

Field	Required	Description
`path`	Yes	Host-side project path

Example:

curl -X POST http://localhost:4000/api/ping \
  -H "Content-Type: application/json" \
  -d '{"path": "C:/Development/GitHub/Giulia"}'

Response:

{
  "status": "ok",
  "path": "/projects/Giulia"
}

GET /api/status

Daemon status. Returns node name, uptime, and active project count.

Parameters: None.

Example:

curl http://localhost:4000/api/status

Response:

{
  "node": "worker@giulia-worker",
  "started_at": "2026-03-16T10:00:00Z",
  "uptime_seconds": 0,
  "active_projects": 2
}

GET /api/projects

List all active project contexts managed by the daemon.

Parameters: None.

Example:

curl http://localhost:4000/api/projects

Response:

{
  "projects": [
    {"path": "/projects/Giulia", "pid": "#PID<0.500.0>"},
    {"path": "/projects/MyApp", "pid": "#PID<0.600.0>"}
  ]
}

POST /api/init

Initialize a project context. Scans for GIULIA.md and starts a ProjectContext GenServer.

Parameters (JSON body):

Field	Required	Description
`path`	Yes	Host-side project path
`opts`	No	Initialization options (map)

Example:

curl -X POST http://localhost:4000/api/init \
  -H "Content-Type: application/json" \
  -d '{"path": "C:/Development/GitHub/MyApp"}'

Response:

{
  "status": "initialized",
  "path": "/projects/MyApp"
}

GET /api/debug/paths

Debug endpoint. Shows current path mappings between host and container paths.

Parameters: None.

Example:

curl http://localhost:4000/api/debug/paths

Response:

{
  "in_container": true,
  "mappings": [
    {"host": "C:/Development/GitHub", "container": "/projects"}
  ]
}

GET /api/agent/last_trace

Returns the last inference trace (OODA loop steps, tool calls, timing).

Parameters: None.

Example:

curl http://localhost:4000/api/agent/last_trace

Response:

{
  "trace": {
    "steps": ["think", "validate", "execute"],
    "tool_calls": [...],
    "duration_ms": 2340
  }
}

GET /api/approvals

List all pending approval requests from the inference consent gate.

Parameters: None.

Example:

curl http://localhost:4000/api/approvals

Response:

{
  "pending": [],
  "count": 0
}

Index

AST index endpoints backed by ETS. Managed by Giulia.Daemon.Routers.Index.

GET /api/index/modules

List all indexed modules in a project.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path

Example:

curl "http://localhost:4000/api/index/modules?path=C:/Development/GitHub/Giulia"

Response:

{
  "modules": [
    {"name": "Giulia.Application", "file": "lib/giulia/application.ex"},
    {"name": "Giulia.Client", "file": "lib/giulia/client.ex"}
  ],
  "count": 138
}

GET /api/index/functions

List functions in a project, optionally filtered by module.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path
`module`	No	Filter by module name (e.g., `Giulia.Tools.Registry`)

Example:

curl "http://localhost:4000/api/index/functions?path=C:/Development/GitHub/Giulia&module=Giulia.Tools.Registry"

Response:

{
  "functions": [
    {"name": "register", "arity": 1, "module": "Giulia.Tools.Registry", "type": "def", "line": 42},
    {"name": "list_tools", "arity": 0, "module": "Giulia.Tools.Registry", "type": "def", "line": 55}
  ],
  "count": 2,
  "module": "Giulia.Tools.Registry"
}

GET /api/index/module_details

Full module metadata including file path, moduledoc, functions, types, specs, callbacks, and struct fields.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path
`module`	Yes	Module name

Example:

curl "http://localhost:4000/api/index/module_details?path=C:/Development/GitHub/Giulia&module=Giulia.Tools.Registry"

Response:

{
  "module": "Giulia.Tools.Registry",
  "details": {
    "file": "lib/giulia/tools/registry.ex",
    "moduledoc": "Auto-discovers tools on boot",
    "functions": [...],
    "types": [...],
    "specs": [...],
    "callbacks": [],
    "struct": null
  }
}

GET /api/index/summary

Project shape overview with aggregate counts.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path

Example:

curl "http://localhost:4000/api/index/summary?path=C:/Development/GitHub/Giulia"

Response:

{
  "summary": "138 modules, 1418 functions, 95 types, 312 specs, 14 structs, 28 callbacks"
}

GET /api/index/status

Indexer status including scan state, cache warmth, and Merkle root.

Parameters: None.

Example:

curl http://localhost:4000/api/index/status

Response:

{
  "state": "idle",
  "project_path": "/projects/Giulia",
  "file_count": 138,
  "last_scan": "2026-03-16T10:05:00Z",
  "cache_status": "warm",
  "merkle_root": "a1b2c3d4e5f6"
}

POST /api/index/scan

Trigger a full re-index of a project. Scans all .ex files, builds AST entries, property graph, and embeddings.

Parameters (JSON body):

Field	Required	Description
`path`	Yes	Host-side project path

Example:

curl -X POST http://localhost:4000/api/index/scan \
  -H "Content-Type: application/json" \
  -d '{"path": "C:/Development/GitHub/Giulia"}'

Response:

{
  "status": "scanning",
  "path": "/projects/Giulia"
}

POST /api/index/verify

Merkle tree integrity verification. Recomputes hashes and compares against stored tree.

Parameters (JSON body):

Field	Required	Description
`path`	Yes	Host-side project path

Example:

curl -X POST http://localhost:4000/api/index/verify \
  -H "Content-Type: application/json" \
  -d '{"path": "C:/Development/GitHub/Giulia"}'

Response:

{
  "status": "ok",
  "verified": true,
  "root": "a1b2c3d4e5f6",
  "leaf_count": 138
}

POST /api/index/compact

Trigger CubDB compaction to reclaim disk space from the persistence layer.

Parameters (JSON body):

Field	Required	Description
`path`	Yes	Host-side project path

Example:

curl -X POST http://localhost:4000/api/index/compact \
  -H "Content-Type: application/json" \
  -d '{"path": "C:/Development/GitHub/Giulia"}'

Response:

{
  "status": "compacting",
  "path": "/projects/Giulia"
}

GET /api/index/complexity

Rank functions by cognitive complexity (Sonar-style, nesting-aware scoring).

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path
`module`	No	Filter by module name
`min`	No	Minimum complexity threshold (default: 0)
`limit`	No	Max results to return (default: 50)

Example:

curl "http://localhost:4000/api/index/complexity?path=C:/Development/GitHub/Giulia&min=5&limit=10"

Response:

{
  "functions": [
    {"name": "build", "arity": 2, "module": "Giulia.Knowledge.Store", "complexity": 24, "line": 150},
    {"name": "run", "arity": 3, "module": "Giulia.Intelligence.Preflight", "complexity": 18, "line": 42}
  ],
  "count": 10,
  "module": null,
  "min_complexity": 5
}

Knowledge

Property Graph topology analysis endpoints. Managed by Giulia.Daemon.Routers.Knowledge. This is the largest category with 23 endpoints.

All GET endpoints require ?path=P in the query string.

GET /api/knowledge/stats

Graph statistics: vertex/edge counts, connected components, top hub modules.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path

Example:

curl "http://localhost:4000/api/knowledge/stats?path=C:/Development/GitHub/Giulia"

Response:

{
  "vertices": 1243,
  "edges": 1544,
  "components": 3,
  "hubs": [
    {"module": "Giulia.Knowledge.Store", "degree": 28},
    {"module": "Giulia.Daemon.Helpers", "degree": 15}
  ]
}

GET /api/knowledge/dependents

Find all modules that depend on a given module (downstream blast radius).

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path
`module`	Yes	Target module name

Example:

curl "http://localhost:4000/api/knowledge/dependents?path=C:/Development/GitHub/Giulia&module=Giulia.Daemon.Helpers"

Response:

{
  "module": "Giulia.Daemon.Helpers",
  "dependents": [
    "Giulia.Daemon.Routers.Index",
    "Giulia.Daemon.Routers.Knowledge",
    "Giulia.Daemon.Routers.Runtime"
  ],
  "count": 9
}

GET /api/knowledge/dependencies

Find all modules that a given module depends on (upstream dependencies).

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path
`module`	Yes	Target module name

Example:

curl "http://localhost:4000/api/knowledge/dependencies?path=C:/Development/GitHub/Giulia&module=Giulia.Daemon.Routers.Index"

Response:

{
  "module": "Giulia.Daemon.Routers.Index",
  "dependencies": [
    "Giulia.Daemon.Helpers",
    "Giulia.Context.Store",
    "Giulia.Context.Indexer",
    "Giulia.Core.PathMapper"
  ],
  "count": 4
}

GET /api/knowledge/centrality

Hub detection score for a module: in-degree, out-degree, and dependent list.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path
`module`	Yes	Target module name

Example:

curl "http://localhost:4000/api/knowledge/centrality?path=C:/Development/GitHub/Giulia&module=Giulia.Knowledge.Store"

Response:

{
  "module": "Giulia.Knowledge.Store",
  "in_degree": 28,
  "out_degree": 5,
  "dependents": ["Giulia.Daemon.Routers.Knowledge", "..."]
}

GET /api/knowledge/impact

Full impact map: upstream and downstream dependencies at a given depth, with function-level edges.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path
`module`	Yes	Target module name
`depth`	No	Traversal depth (default: 2)

Example:

curl "http://localhost:4000/api/knowledge/impact?path=C:/Development/GitHub/Giulia&module=Giulia.Tools.Registry&depth=2"

Response:

{
  "module": "Giulia.Tools.Registry",
  "upstream": [
    {"module": "Giulia.Context.Builder", "depth": 1}
  ],
  "downstream": [
    {"module": "Giulia.Inference.Orchestrator", "depth": 1},
    {"module": "Giulia.Inference.Pool", "depth": 2}
  ],
  "function_edges": [
    {"function": "register/1", "calls": ["Giulia.Tools.ReadFile"]}
  ]
}

GET /api/knowledge/integrity

Behaviour-implementer integrity check. Detects missing or extra callbacks.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path

Example:

curl "http://localhost:4000/api/knowledge/integrity?path=C:/Development/GitHub/Giulia"

Response:

{
  "status": "fractured",
  "fractures": [
    {
      "behaviour": "Giulia.Provider",
      "fractures": [
        {"implementor": "Giulia.Provider.Ollama", "missing": ["stream/3"], "extra": []}
      ]
    }
  ]
}

GET /api/knowledge/dead_code

Detect functions that are defined but never called anywhere in the project.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path

Example:

curl "http://localhost:4000/api/knowledge/dead_code?path=C:/Development/GitHub/Giulia"

Response:

{
  "dead_functions": [
    {"module": "Giulia.Tools.Think", "function": "unused_helper", "arity": 1, "line": 45}
  ],
  "count": 12
}

GET /api/knowledge/cycles

Detect circular dependencies (strongly connected components with more than one member).

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path

Example:

curl "http://localhost:4000/api/knowledge/cycles?path=C:/Development/GitHub/Giulia"

Response:

{
  "cycles": [
    ["Giulia.Context.Store", "Giulia.Knowledge.Store"]
  ],
  "count": 1
}

GET /api/knowledge/god_modules

Detect god modules: high complexity, high centrality, and high function count.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path

Example:

curl "http://localhost:4000/api/knowledge/god_modules?path=C:/Development/GitHub/Giulia"

Response:

{
  "god_modules": [
    {"module": "Giulia.Knowledge.Store", "function_count": 45, "complexity": 320, "degree": 28}
  ],
  "count": 1
}

GET /api/knowledge/orphan_specs

Detect orphan specs: @spec declarations without a matching function definition.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path

Example:

curl "http://localhost:4000/api/knowledge/orphan_specs?path=C:/Development/GitHub/Giulia"

Response:

{
  "orphan_specs": [
    {"module": "Giulia.Provider.Ollama", "spec": "stream/3"}
  ],
  "count": 1
}

GET /api/knowledge/fan_in_out

Analyze fan-in/fan-out per module. Reveals dependency direction imbalance.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path

Example:

curl "http://localhost:4000/api/knowledge/fan_in_out?path=C:/Development/GitHub/Giulia"

Response:

{
  "modules": [
    {"module": "Giulia.Daemon.Helpers", "fan_in": 9, "fan_out": 2, "ratio": 4.5}
  ],
  "count": 138
}

GET /api/knowledge/coupling

Function-level dependency strength between module pairs.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path

Example:

curl "http://localhost:4000/api/knowledge/coupling?path=C:/Development/GitHub/Giulia"

Response:

{
  "pairs": [
    {"from": "Giulia.Daemon.Endpoint", "to": "Giulia.Daemon.Helpers", "strength": 12}
  ],
  "count": 45
}

GET /api/knowledge/api_surface

Public vs private function ratio per module.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path

Example:

curl "http://localhost:4000/api/knowledge/api_surface?path=C:/Development/GitHub/Giulia"

Response:

{
  "modules": [
    {"module": "Giulia.Knowledge.Store", "public": 23, "private": 12, "ratio": 0.66}
  ],
  "count": 138
}

GET /api/knowledge/change_risk

Composite refactoring priority score per module. Combines centrality, complexity, coupling, and coverage.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path

Example:

curl "http://localhost:4000/api/knowledge/change_risk?path=C:/Development/GitHub/Giulia"

Response:

{
  "modules": [
    {"module": "Giulia.Knowledge.Store", "risk_score": 87, "factors": {"centrality": 28, "complexity": 320}}
  ],
  "count": 138
}

GET /api/knowledge/path

Shortest path between two modules in the dependency graph.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path
`from`	Yes	Source module name
`to`	Yes	Target module name

Example:

curl "http://localhost:4000/api/knowledge/path?path=C:/Development/GitHub/Giulia&from=Giulia.Client&to=Giulia.Tools.Registry"

Response:

{
  "from": "Giulia.Client",
  "to": "Giulia.Tools.Registry",
  "path": ["Giulia.Client", "Giulia.Daemon.Endpoint", "Giulia.Tools.Registry"],
  "hops": 2
}

GET /api/knowledge/logic_flow

Function-level Dijkstra path between two MFA (Module.function/arity) vertices.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path
`from`	Yes	Source MFA (e.g., `Giulia.Client.main/1`)
`to`	Yes	Target MFA

Example:

curl "http://localhost:4000/api/knowledge/logic_flow?path=C:/Development/GitHub/Giulia&from=Giulia.Client.main/1&to=Giulia.Tools.Registry.list_tools/0"

Response:

{
  "from": "Giulia.Client.main/1",
  "to": "Giulia.Tools.Registry.list_tools/0",
  "steps": [
    "Giulia.Client.main/1",
    "Giulia.Client.send_request/2",
    "Giulia.Tools.Registry.list_tools/0"
  ],
  "hop_count": 2
}

GET /api/knowledge/style_oracle

Find exemplar functions by concept with a quality gate (requires both @spec and @doc).

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path
`q`	Yes	Concept to search for
`top_k`	No	Number of results to return (default: 3)

Example:

curl "http://localhost:4000/api/knowledge/style_oracle?path=C:/Development/GitHub/Giulia&q=error%20handling&top_k=5"

Response:

{
  "exemplars": [
    {
      "module": "Giulia.Core.PathSandbox",
      "function": "validate/2",
      "score": 0.92,
      "has_spec": true,
      "has_doc": true
    }
  ],
  "count": 3
}

POST /api/knowledge/pre_impact_check

Analyze rename/remove risk with callers, risk score, and phased migration plan.

Parameters (JSON body):

Field	Required	Description
`path`	Yes	Host-side project path
`module`	Yes	Target module name
`action`	Yes	One of: `rename_function`, `remove_function`, `rename_module`
`target`	No	Function target in `name/arity` format (for function actions)
`new_name`	No	New name (for rename actions)

Example:

curl -X POST http://localhost:4000/api/knowledge/pre_impact_check \
  -H "Content-Type: application/json" \
  -d '{"path": "C:/Development/GitHub/Giulia", "module": "Giulia.Tools.Registry", "action": "rename_function", "target": "register/1", "new_name": "register_tool"}'

Response:

{
  "action": "rename_function",
  "target": "register/1",
  "risk_score": "medium",
  "affected_callers": [
    {"module": "Giulia.Tools.ReadFile", "function": "init/0", "line": 12}
  ],
  "migration_plan": [
    "Step 1: Add register_tool/1 as alias",
    "Step 2: Update 3 callers",
    "Step 3: Remove register/1"
  ]
}

GET /api/knowledge/heatmap

Composite module health scores on a 0-100 scale with red/yellow/green zone classification.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path

Example:

curl "http://localhost:4000/api/knowledge/heatmap?path=C:/Development/GitHub/Giulia"

Response:

{
  "modules": [
    {"module": "Giulia.Knowledge.Store", "score": 82, "zone": "red", "factors": {"complexity": 0.9, "centrality": 0.8}},
    {"module": "Giulia.Tools.ReadFile", "score": 15, "zone": "green", "factors": {"complexity": 0.1, "centrality": 0.1}}
  ],
  "count": 138,
  "zones": {"red": 5, "yellow": 18, "green": 115}
}

GET /api/knowledge/unprotected_hubs

Find hub modules with low @spec/@doc coverage. High-traffic modules that lack contracts are risky.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path
`hub_threshold`	No	Minimum in-degree to qualify as hub (default: 3)
`spec_threshold`	No	Minimum spec coverage ratio (default: 0.5)

Example:

curl "http://localhost:4000/api/knowledge/unprotected_hubs?path=C:/Development/GitHub/Giulia&hub_threshold=5"

Response:

{
  "modules": [
    {"module": "Giulia.Daemon.Helpers", "in_degree": 9, "spec_coverage": 0.2, "severity": "red"}
  ],
  "count": 3,
  "severity_counts": {"red": 1, "yellow": 2}
}

GET /api/knowledge/struct_lifecycle

Trace struct data flow across modules: creation points, usage, and transformations.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path
`struct`	No	Filter to a specific struct name

Example:

curl "http://localhost:4000/api/knowledge/struct_lifecycle?path=C:/Development/GitHub/Giulia"

Response:

{
  "structs": [
    {
      "name": "Giulia.Core.PathSandbox",
      "created_in": ["Giulia.Core.PathSandbox"],
      "used_in": ["Giulia.Tools.ReadFile", "Giulia.Tools.WriteFile"],
      "transformed_in": []
    }
  ],
  "count": 14
}

GET /api/knowledge/duplicates

Find semantically similar functions using embedding cosine similarity. Requires active EmbeddingServing.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path
`threshold`	No	Similarity threshold 0.0-1.0 (default: 0.85)
`max`	No	Maximum clusters to return (default: 20)

Example:

curl "http://localhost:4000/api/knowledge/duplicates?path=C:/Development/GitHub/Giulia&threshold=0.9"

Response:

{
  "clusters": [
    {
      "similarity": 0.95,
      "functions": [
        {"module": "Giulia.Daemon.Routers.Knowledge", "function": "parse_int_param/2"},
        {"module": "Giulia.Daemon.Routers.Runtime", "function": "parse_int_param/2"}
      ]
    }
  ],
  "count": 3
}

GET /api/knowledge/audit

Unified audit combining all four Principal Consultant analyses: unprotected hubs, struct lifecycle, semantic duplicates, and behaviour integrity.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path

Example:

curl "http://localhost:4000/api/knowledge/audit?path=C:/Development/GitHub/Giulia"

Response:

{
  "audit_version": "build_90",
  "unprotected_hubs": {"modules": [...], "count": 3},
  "struct_lifecycle": {"structs": [...], "count": 14},
  "semantic_duplicates": {"clusters": [...], "count": 3},
  "behaviour_integrity": {"status": "consistent", "fractures": []}
}

GET /api/knowledge/conventions

Detect coding convention violations via AST analysis. 12 rules across 2 tiers: Tier 1 (metadata — instant, ETS-only) checks missing moduledoc, spec, and enforce_keys. Tier 2 (AST walk — Sourceror parse) detects anti-patterns: try-rescue flow control, silent rescue, runtime atom creation, process dictionary usage, unsupervised tasks, unless-else, single-value pipes, append-in-reduce, if-not.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host project path
`module`	No	Filter violations to a single module
`suppress`	No	Suppress specific rules for specific modules. Format: `rule:Mod1,Mod2;rule2:Mod3,Mod4`. Semicolons separate rules, colons separate rule from modules, commas separate modules. Example: `suppress=process_dictionary:MyApp.Auth.Context,MyApp.Auth.Token`

Example:

# All violations
curl "http://localhost:4000/api/knowledge/conventions?path=C:/Development/GitHub/Giulia"

# Filter to one module
curl "http://localhost:4000/api/knowledge/conventions?path=C:/Development/GitHub/Giulia&module=Giulia.Daemon.Helpers"

# Suppress process_dictionary for auth modules (intentional usage)
curl "http://localhost:4000/api/knowledge/conventions?path=D:/Development/GitHub/AlexClaw&suppress=process_dictionary:AlexClaw.Executor,AlexClaw.SafeExecutor,AlexClaw.SkillAPI,AlexClaw.AuthContext,AlexClaw.CapabilityToken"

Response:

{
  "total_violations": 3,
  "by_severity": {"error": 1, "warning": 0, "info": 2},
  "by_category": {
    "atoms": [
      {
        "rule": "runtime_atom_creation",
        "message": "String.to_atom/1 creates atoms from runtime strings",
        "category": "atoms",
        "severity": "error",
        "file": "/projects/Giulia/lib/giulia/daemon/helpers.ex",
        "line": 47,
        "module": "Giulia.Daemon.Helpers",
        "convention_ref": "Atoms > Never create atoms from runtime strings"
      }
    ]
  },
  "by_file": { ... },
  "suppressions_applied": {"process_dictionary": ["AlexClaw.AuthContext", "AlexClaw.CapabilityToken"]},
  "rules_checked": [
    {"rule": "missing_moduledoc", "category": "documentation", "severity": "warning", "tier": 1},
    {"rule": "missing_spec", "category": "documentation", "severity": "warning", "tier": 1},
    {"rule": "missing_enforce_keys", "category": "structs", "severity": "info", "tier": 1},
    {"rule": "try_rescue_flow_control", "category": "error_handling", "severity": "error", "tier": 2},
    {"rule": "silent_rescue", "category": "error_handling", "severity": "error", "tier": 2},
    {"rule": "runtime_atom_creation", "category": "atoms", "severity": "error", "tier": 2},
    {"rule": "process_dictionary", "category": "otp", "severity": "warning", "tier": 2},
    {"rule": "unsupervised_task", "category": "otp", "severity": "warning", "tier": 2},
    {"rule": "unless_else", "category": "control_flow", "severity": "warning", "tier": 2},
    {"rule": "single_value_pipe", "category": "pipes", "severity": "info", "tier": 2},
    {"rule": "append_in_reduce", "category": "lists", "severity": "warning", "tier": 2},
    {"rule": "if_not", "category": "control_flow", "severity": "info", "tier": 2}
  ]
}

When module filter is provided, the response also includes "module_filter": "Module.Name". When suppress is provided, the response includes "suppressions_applied" showing which rules/modules were suppressed.

GET /api/knowledge/topology

Full module dependency graph in Cytoscape.js-ready format. Returns nodes with heatmap scores, centrality (fan-in/fan-out), complexity breakdown, and edges with dependency labels. Designed for direct consumption by the Graph Explorer visualization.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host project path

Example:

curl "http://localhost:4000/api/knowledge/topology?path=D:/Development/GitHub/Giulia"

Response:

{
  "nodes": [
    {
      "id": "Giulia.Knowledge.Store",
      "fan_in": 12,
      "fan_out": 5,
      "score": 85,
      "zone": "red",
      "complexity": 42,
      "breakdown": {"specs": 15, "functions": 20, "dependencies": 5, "complexity": 10, "test_status": 5}
    }
  ],
  "edges": [
    {"source": "Giulia.Daemon.Routers.Knowledge", "target": "Giulia.Knowledge.Store", "label": "alias"}
  ],
  "meta": {"node_count": 143, "edge_count": 617}
}

Intelligence

Higher-order analysis: briefings, preflight checks, architect briefs, and plan validation. Managed by Giulia.Daemon.Routers.Intelligence.

Note: These endpoints are forwarded from multiple path prefixes (/api/intelligence, /api/briefing, /api/brief, /api/plan) due to historical path conventions.

GET /api/intelligence/briefing

Surgical briefing for a prompt. Combines semantic search with graph pre-processing to identify relevant modules and context.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path
`prompt`	Yes	The prompt to build context for (alias: `q`)

Example:

curl "http://localhost:4000/api/intelligence/briefing?path=C:/Development/GitHub/Giulia&prompt=add%20a%20new%20tool"

Response:

{
  "status": "ok",
  "briefing": {
    "relevant_modules": ["Giulia.Tools.Registry", "Giulia.Tools.ReadFile"],
    "context": "..."
  }
}

POST /api/briefing/preflight

Preflight contract checklist. Returns 6 contract sections per relevant module plus suggested_tools ranked by semantic similarity to the prompt.

Parameters (JSON body):

Field	Required	Description
`prompt`	Yes	The task description
`path`	Yes	Host-side project path
`top_k`	No	Number of modules to analyze (default: 5)
`depth`	No	Graph traversal depth (default: 2)

Example:

curl -X POST http://localhost:4000/api/briefing/preflight \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Add caching to the knowledge store", "path": "C:/Development/GitHub/Giulia", "top_k": 3}'

Response:

{
  "modules": [
    {
      "module": "Giulia.Knowledge.Store",
      "contracts": {
        "public_api": ["stats/1", "dependents/2"],
        "specs": ["stats/1 :: map()"],
        "behaviours": [],
        "callbacks": [],
        "struct": null,
        "dependents": ["Giulia.Daemon.Routers.Knowledge"]
      }
    }
  ],
  "suggested_tools": [
    {"endpoint": "GET /api/knowledge/stats", "intent": "Get Property Graph statistics", "score": 0.87}
  ],
  "module_count": 3
}

GET /api/brief/architect

Single-call session briefing. Returns project topology, health heatmap, constitution summary, and runtime info. Recommended as the first call in any session.

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path

Example:

curl "http://localhost:4000/api/brief/architect?path=C:/Development/GitHub/Giulia"

Response:

{
  "project": "Giulia",
  "shape": {
    "modules": 138,
    "functions": 1418,
    "edges": 1544,
    "components": 3
  },
  "heatmap_summary": {
    "red": 5,
    "yellow": 18,
    "green": 115
  },
  "top_hubs": [
    {"module": "Giulia.Knowledge.Store", "degree": 28}
  ],
  "constitution": {
    "taboos": ["Never use umbrella projects"],
    "preferred_patterns": ["Use context modules for business logic"]
  },
  "runtime": {
    "node": "worker@giulia-worker",
    "memory_mb": 256,
    "process_count": 312
  }
}

POST /api/plan/validate

Validate a proposed plan against the Property Graph. Checks for dependency violations, blast radius, and risk.

Parameters (JSON body):

Field	Required	Description
`path`	Yes	Host-side project path
`plan`	Yes	Plan description (string or structured list of steps)

Example:

curl -X POST http://localhost:4000/api/plan/validate \
  -H "Content-Type: application/json" \
  -d '{"path": "C:/Development/GitHub/Giulia", "plan": "Rename Giulia.Daemon.Helpers to Giulia.Daemon.Utils"}'

Response:

{
  "valid": false,
  "risk": "high",
  "issues": [
    "Giulia.Daemon.Helpers has 9 dependents — renaming will break all sub-routers"
  ],
  "blast_radius": 9,
  "suggestion": "Consider adding an alias instead of a full rename"
}

GET /api/intelligence/report_rules

Get canonical report generation rules (section order, scoring formulas, formatting, and Elixir idiom rules).

Parameters: None.

Example:

curl http://localhost:4000/api/intelligence/report_rules

Response:

{
  "status": "ok",
  "rules": "# Report Generation Rules\n..."
}

Runtime

BEAM runtime introspection endpoints. Managed by Giulia.Daemon.Routers.Runtime. Supports both self-introspection and remote node inspection via the optional ?node parameter.

GET /api/runtime/pulse

BEAM health snapshot: memory breakdown, process count, scheduler utilization, ETS table count.

Parameters (query string):

Param	Required	Description
`node`	No	Remote node name (default: self-introspection)

Example:

curl http://localhost:4000/api/runtime/pulse

Response:

{
  "memory": {
    "total_mb": 256,
    "processes_mb": 45,
    "ets_mb": 38,
    "binary_mb": 12,
    "atom_mb": 1
  },
  "processes": 312,
  "schedulers": 8,
  "scheduler_utilization": 0.15,
  "ets_tables": 42,
  "run_queue": 0,
  "uptime_seconds": 3600
}

GET /api/runtime/top_processes

Top 10 processes sorted by a given metric.

Parameters (query string):

Param	Required	Description
`metric`	No	One of: `reductions`, `memory`, `message_queue` (default: `reductions`)
`node`	No	Remote node name

Example:

curl "http://localhost:4000/api/runtime/top_processes?metric=memory"

Response:

{
  "processes": [
    {"pid": "#PID<0.500.0>", "registered_name": "Giulia.Knowledge.Store", "memory": 8388608},
    {"pid": "#PID<0.501.0>", "registered_name": "Giulia.Context.Store", "memory": 4194304}
  ],
  "count": 10,
  "metric": "memory"
}

GET /api/runtime/hot_spots

Top runtime modules fused with Property Graph data. Combines process reduction counts with static analysis metrics.

Parameters (query string):

Param	Required	Description
`path`	No	Host-side project path (enables graph fusion)
`node`	No	Remote node name

Example:

curl "http://localhost:4000/api/runtime/hot_spots?path=C:/Development/GitHub/Giulia"

Response:

{
  "hot_spots": [
    {
      "module": "Giulia.Knowledge.Store",
      "reductions": 15000000,
      "in_degree": 28,
      "complexity": 320,
      "zone": "red"
    }
  ],
  "count": 10
}

GET /api/runtime/trace

Short-lived per-module function call trace. Traces all calls to the specified module for the given duration.

Parameters (query string):

Param	Required	Description
`module`	Yes	Module name to trace
`duration`	No	Trace duration in milliseconds (default: 5000)
`node`	No	Remote node name

Example:

curl "http://localhost:4000/api/runtime/trace?module=Giulia.Knowledge.Store&duration=3000"

Response:

{
  "module": "Giulia.Knowledge.Store",
  "duration_ms": 3000,
  "calls": [
    {"function": "stats/1", "count": 5},
    {"function": "dependents/2", "count": 2}
  ],
  "total_calls": 7
}

GET /api/runtime/history

Last N runtime snapshots from the Collector.

Parameters (query string):

Param	Required	Description
`last`	No	Number of snapshots (default: 20)
`node`	No	Remote node name

Example:

curl "http://localhost:4000/api/runtime/history?last=5"

Response:

{
  "snapshots": [
    {"timestamp": "2026-03-16T10:05:00Z", "memory_mb": 256, "processes": 312, "run_queue": 0}
  ],
  "count": 5
}

GET /api/runtime/trend

Time-series for a single runtime metric.

Parameters (query string):

Param	Required	Description
`metric`	No	One of: `memory`, `processes`, `run_queue`, `ets_memory` (default: `memory`)
`node`	No	Remote node name

Example:

curl "http://localhost:4000/api/runtime/trend?metric=memory"

Response:

{
  "metric": "memory",
  "points": [
    {"timestamp": "2026-03-16T10:00:00Z", "value": 240},
    {"timestamp": "2026-03-16T10:05:00Z", "value": 256}
  ],
  "count": 12
}

GET /api/runtime/alerts

Active runtime warnings with duration (e.g., high memory, run queue buildup).

Parameters (query string):

Param	Required	Description
`node`	No	Remote node name

Example:

curl http://localhost:4000/api/runtime/alerts

Response:

{
  "alerts": [
    {"type": "high_memory", "threshold_mb": 512, "current_mb": 580, "duration_seconds": 120}
  ],
  "count": 1
}

POST /api/runtime/connect

Connect to a remote BEAM node for distributed introspection. Both nodes must share the same Erlang cookie.

Parameters (JSON body):

Field	Required	Description
`node`	Yes	Remote node name (e.g., `myapp@192.168.1.50`)
`cookie`	No	Erlang cookie (default: uses daemon's cookie)

Example:

curl -X POST http://localhost:4000/api/runtime/connect \
  -H "Content-Type: application/json" \
  -d '{"node": "myapp@192.168.1.50", "cookie": "giulia_dev"}'

Response:

{
  "status": "connected",
  "node": "myapp@192.168.1.50"
}

GET /api/runtime/monitor/status

Monitor lifecycle status: current phase, profile count, burst detection state.

Parameters: None.

Example:

curl http://localhost:4000/api/runtime/monitor/status

Response:

{
  "phase": "idle",
  "profiles_count": 5,
  "burst_state": "waiting",
  "last_burst_at": "2026-03-16T10:00:00Z"
}

GET /api/runtime/profiles

List saved performance profiles from burst analysis.

Parameters (query string):

Param	Required	Description
`limit`	No	Maximum profiles to return (default: 20)

Example:

curl "http://localhost:4000/api/runtime/profiles?limit=5"

Response:

{
  "profiles": [
    {
      "id": "2026-03-16T10:00:00Z",
      "timestamp": "2026-03-16T10:00:00Z",
      "duration_ms": 15000,
      "snapshot_count": 30,
      "hot_modules_count": 5,
      "bottleneck_count": 2
    }
  ],
  "count": 5
}

GET /api/runtime/profile/latest

Most recent performance profile with full detail.

Parameters: None.

Example:

curl http://localhost:4000/api/runtime/profile/latest

Response:

{
  "id": "2026-03-16T10:00:00Z",
  "duration_ms": 15000,
  "hot_modules": [
    {"module": "Giulia.Knowledge.Store", "peak_reductions": 15000000}
  ],
  "bottleneck_analysis": [
    {"module": "Giulia.AST.Processor", "reason": "high_cpu_sustained"}
  ],
  "peak_metrics": {"memory_mb": 300, "run_queue": 4}
}

GET /api/runtime/profile/:id

Retrieve a specific performance profile by its timestamp ID.

Parameters (path):

Param	Required	Description
`id`	Yes	Profile timestamp ID

Example:

curl http://localhost:4000/api/runtime/profile/2026-03-16T10:00:00Z

Response: Same structure as /api/runtime/profile/latest.

POST /api/runtime/ingest

Receive a runtime snapshot pushed by the Monitor container. Used in the dual-container (worker + monitor) architecture.

Parameters (JSON body):

Field	Required	Description
`node`	Yes	Source node name
`session_id`	Yes	Observation session identifier
`timestamp`	Yes	Snapshot timestamp
`metrics`	Yes	Runtime metrics object

Example:

curl -X POST http://localhost:4000/api/runtime/ingest \
  -H "Content-Type: application/json" \
  -d '{"node": "myapp@host", "session_id": "abc123", "timestamp": "2026-03-16T10:00:00Z", "metrics": {"memory_mb": 256, "processes": 312}}'

Response:

{
  "status": "ok",
  "session_id": "abc123",
  "snapshot_count": 15
}

POST /api/runtime/ingest/finalize

Finalize an observation session. Produces a fused profile combining runtime snapshots with static analysis.

Parameters (JSON body):

Field	Required	Description
`session_id`	Yes	Observation session identifier
`node`	Yes	Source node name

Example:

curl -X POST http://localhost:4000/api/runtime/ingest/finalize \
  -H "Content-Type: application/json" \
  -d '{"session_id": "abc123", "node": "myapp@host"}'

Response:

{
  "status": "finalized",
  "session_id": "abc123",
  "snapshots_processed": 30,
  "duration_ms": 15000,
  "hot_modules": [...],
  "correlation": [...]
}

GET /api/runtime/observations

List all available fused observation sessions.

Parameters: None.

Example:

curl http://localhost:4000/api/runtime/observations

Response:

{
  "observations": [
    {
      "session_id": "abc123",
      "node": "myapp@host",
      "started_at": "2026-03-16T10:00:00Z",
      "stopped_at": "2026-03-16T10:15:00Z",
      "status": "finalized",
      "snapshots_processed": 30,
      "duration_ms": 900000
    }
  ],
  "count": 1
}

GET /api/runtime/observation/:session_id

Full fused observation profile with static + runtime correlation data.

Parameters (path):

Param	Required	Description
`session_id`	Yes	Observation session identifier

Example:

curl http://localhost:4000/api/runtime/observation/abc123

Response:

{
  "session_id": "abc123",
  "node": "myapp@host",
  "status": "finalized",
  "duration_ms": 900000,
  "fused_profile": {
    "hot_modules": [...],
    "bottleneck_analysis": [...],
    "peak_metrics": {...}
  }
}

Search

Code search endpoints: text pattern matching and embedding-based semantic search. Managed by Giulia.Daemon.Routers.Search.

GET /api/search

Direct text pattern search across project source files. No LLM involved.

Parameters (query string):

Param	Required	Description
`pattern`	Yes	Search pattern (alias: `q`)
`path`	No	Host-side project path (default: cwd)

Example:

curl "http://localhost:4000/api/search?pattern=defmodule.*Router&path=C:/Development/GitHub/Giulia"

Response:

{
  "status": "ok",
  "results": [
    {"file": "lib/giulia/daemon/routers/index.ex", "line": 1, "content": "defmodule Giulia.Daemon.Routers.Index do"}
  ]
}

GET /api/search/semantic

Semantic search by concept using embedding cosine similarity. Requires active EmbeddingServing.

Parameters (query string):

Param	Required	Description
`concept`	Yes	Concept to search for (alias: `q`)
`path`	Yes	Host-side project path
`top_k`	No	Number of results (default: 5)

Example:

curl "http://localhost:4000/api/search/semantic?concept=file%20reading&path=C:/Development/GitHub/Giulia&top_k=3"

Response:

{
  "concept": "file reading",
  "modules": [
    {"module": "Giulia.Tools.ReadFile", "score": 0.94, "moduledoc": "Sandboxed file reading"}
  ],
  "functions": [
    {"module": "Giulia.Tools.ReadFile", "function": "execute", "arity": 2, "score": 0.91, "file": "lib/giulia/tools/read_file.ex", "line": 25}
  ],
  "count": 3
}

GET /api/search/semantic/status

Check semantic search index status (whether embeddings are loaded for a project).

Parameters (query string):

Param	Required	Description
`path`	Yes	Host-side project path

Example:

curl "http://localhost:4000/api/search/semantic/status?path=C:/Development/GitHub/Giulia"

Response:

{
  "available": true,
  "module_embeddings": 138,
  "function_embeddings": 626,
  "serving_loaded": true
}

Transaction

Transactional exoskeleton endpoints for safe write operations. Managed by Giulia.Daemon.Routers.Transaction.

POST /api/transaction/enable

Toggle transaction mode for a project. When enabled, file writes are staged for approval before committing.

Parameters (JSON body):

Field	Required	Description
`path`	Yes	Host-side project path

Example:

curl -X POST http://localhost:4000/api/transaction/enable \
  -H "Content-Type: application/json" \
  -d '{"path": "C:/Development/GitHub/Giulia"}'

Response:

{
  "status": "enabled",
  "transaction_mode": true
}

GET /api/transaction/staged

View transaction preference and staged files. Staged files exist only during active inference sessions.

Parameters (query string):

Param	Required	Description
`path`	No	Host-side project path

Example:

curl "http://localhost:4000/api/transaction/staged?path=C:/Development/GitHub/Giulia"

Response:

{
  "transaction_mode": true,
  "staged_files": [],
  "count": 0,
  "note": "Staged files exist only during active inference sessions"
}

POST /api/transaction/rollback

Reset transaction mode (disable). Reverts to direct write behavior.

Parameters (JSON body):

Field	Required	Description
`path`	Yes	Host-side project path

Example:

curl -X POST http://localhost:4000/api/transaction/rollback \
  -H "Content-Type: application/json" \
  -d '{"path": "C:/Development/GitHub/Giulia"}'

Response:

{
  "status": "reset",
  "transaction_mode": false
}

Approval

Consent gate for tool execution during inference. Managed by Giulia.Daemon.Routers.Approval.

POST /api/approval/:approval_id

Respond to an approval request (approve or deny).

Parameters:

Location	Param	Required	Description
Path	`approval_id`	Yes	Approval request identifier
Body	`approved`	Yes	Boolean: `true` to approve, `false` to deny

Example:

curl -X POST http://localhost:4000/api/approval/abc123 \
  -H "Content-Type: application/json" \
  -d '{"approved": true}'

Response:

{
  "status": "ok",
  "approval_id": "abc123",
  "approved": true
}

GET /api/approval/:approval_id

Get details of a pending approval request.

Parameters (path):

Param	Required	Description
`approval_id`	Yes	Approval request identifier

Example:

curl http://localhost:4000/api/approval/abc123

Response:

{
  "approval_id": "abc123",
  "tool": "write_file",
  "args": {"path": "lib/giulia/new_module.ex", "content": "..."},
  "created_at": "2026-03-16T10:00:00Z"
}

Monitor

Logic Monitor dashboard and telemetry streaming. Managed by Giulia.Daemon.Routers.Monitor.

GET /api/monitor

Serve the Logic Monitor HTML dashboard. Opens in a browser for real-time inference telemetry visualization.

Parameters: None.

Example:

curl http://localhost:4000/api/monitor
# Or open in browser: http://localhost:4000/api/monitor

Response: HTML page (not JSON).

GET /api/monitor/graph

Serve the Graph Explorer HTML page. Interactive dependency graph visualization powered by Cytoscape.js. Fetches data from /api/knowledge/topology and provides four view modes: Dependency, Heatmap, Blast Radius, and Hub Map.

Parameters: None.

Example:

# Open in browser
http://localhost:4000/api/monitor/graph

Response: HTML page (not JSON).

GET /api/monitor/stream

SSE endpoint for real-time telemetry events. Subscribe to receive OODA loop events, LLM calls, tool executions, and API requests as they happen.

Parameters: None.

Example:

curl -N http://localhost:4000/api/monitor/stream

Response (SSE):

event: connected
data: {"status":"ok"}

event: event
data: {"event":"ooda.step","measurements":{"duration_ms":150},"metadata":{"step":"think"},"timestamp":"2026-03-16T10:00:00Z"}

GET /api/monitor/history

Recent telemetry events from the rolling buffer (last N events, default 50).

Parameters (query string):

Param	Required	Description
`n`	No	Number of events to return (default: 50)

Example:

curl "http://localhost:4000/api/monitor/history?n=10"

Response:

{
  "events": [
    {
      "event": "ooda.step",
      "measurements": {"duration_ms": 150},
      "metadata": {"step": "think"},
      "timestamp": "2026-03-16T10:00:00Z"
    }
  ],
  "count": 10
}

POST /api/monitor/observe/start

Start an async observation session targeting a remote BEAM node. The Monitor container will periodically push runtime snapshots to the Worker.

Parameters (JSON body):

Field	Required	Description
`node`	Yes	Target node name (e.g., `myapp@192.168.1.50`)
`cookie`	No	Erlang cookie for authentication
`worker_url`	No	Worker URL for snapshot push (default: auto-detected)
`interval_ms`	No	Snapshot interval in milliseconds
`trace_modules`	No	List of module names to trace during observation

Example:

curl -X POST http://localhost:4000/api/monitor/observe/start \
  -H "Content-Type: application/json" \
  -d '{"node": "myapp@192.168.1.50", "cookie": "giulia_dev", "interval_ms": 5000}'

Response:

{
  "status": "observing",
  "session_id": "obs_abc123",
  "node": "myapp@192.168.1.50",
  "interval_ms": 5000,
  "trace_modules": []
}

POST /api/monitor/observe/stop

Stop the active observation and trigger Worker-side finalization.

Parameters (JSON body):

Field	Required	Description
`node`	No	Node name (for multi-target disambiguation)

Example:

curl -X POST http://localhost:4000/api/monitor/observe/stop \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "status": "stopped",
  "snapshots_pushed": 30,
  "duration_ms": 150000,
  "finalize_result": {"status": "finalized", "session_id": "obs_abc123"}
}

GET /api/monitor/observe/status

Check whether an observation is currently running.

Parameters: None.

Example:

curl http://localhost:4000/api/monitor/observe/status

Response:

{
  "status": "observing",
  "node": "myapp@192.168.1.50",
  "session_id": "obs_abc123",
  "elapsed_ms": 45000,
  "snapshots_pushed": 9
}

Discovery

Self-describing API discovery. Aggregates __skills__/0 from all 9 domain sub-routers at runtime. Managed by Giulia.Daemon.Routers.Discovery.

GET /api/discovery/skills

List all available API skills (endpoints) with optional category filter.

Parameters (query string):

Param	Required	Description
`category`	No	Filter by category name

Example:

curl "http://localhost:4000/api/discovery/skills?category=knowledge"

Response:

{
  "skills": [
    {
      "intent": "Get Property Graph statistics (vertices, edges, components, hubs)",
      "endpoint": "GET /api/knowledge/stats",
      "params": {"path": "required"},
      "returns": "JSON graph stats with top hub modules",
      "category": "knowledge"
    }
  ],
  "count": 23
}

GET /api/discovery/categories

List all skill categories with endpoint counts.

Parameters: None.

Example:

curl http://localhost:4000/api/discovery/categories

Response:

{
  "categories": [
    {"category": "approval", "count": 2},
    {"category": "discovery", "count": 3},
    {"category": "index", "count": 9},
    {"category": "intelligence", "count": 5},
    {"category": "knowledge", "count": 23},
    {"category": "monitor", "count": 6},
    {"category": "runtime", "count": 16},
    {"category": "search", "count": 3},
    {"category": "transaction", "count": 3}
  ],
  "total": 9
}

GET /api/discovery/search

Search skills by keyword. Case-insensitive substring match on the intent field.

Parameters (query string):

Param	Required	Description
`q`	Yes	Search keyword

Example:

curl "http://localhost:4000/api/discovery/search?q=dead%20code"

Response:

{
  "skills": [
    {
      "intent": "Detect dead code (functions defined but never called)",
      "endpoint": "GET /api/knowledge/dead_code",
      "params": {"path": "required"},
      "returns": "JSON list of unused functions",
      "category": "knowledge"
    }
  ],
  "count": 1,
  "query": "dead code"
}

GET /api/discovery/report_rules

Get the REPORT_RULES.md location and content. Used by clients (e.g., Claude Code) to retrieve the canonical report generation rules without hardcoding paths.

Parameters (query string):

Param	Required	Description
`path`	No	Host project path (checks for local copy)

Example:

curl "http://localhost:4000/api/discovery/report_rules"

Response:

{
  "host_path": "~/.claude/REPORT_RULES.md",
  "local_path": null,
  "content": "# Report Generation Rules\n...",
  "hint": "host_path uses ~ (client resolves). Content included as fallback."
}

Error Responses

All endpoints return errors in a consistent format:

{
  "error": "Description of what went wrong"
}

Common HTTP status codes:

Code	Meaning
200	Success
400	Bad request (missing required parameters)
404	Resource not found (module not in graph, profile missing)
422	Unprocessable entity (valid request but processing failed)
500	Internal server error
503	Service unavailable (EmbeddingServing not loaded)

MCP

Giulia exposes a native Model Context Protocol (MCP) server at /mcp. MCP allows AI assistants (Claude Code, Cursor, etc.) to discover and invoke Giulia's analysis tools as structured tool calls, without constructing HTTP requests manually.

Setup

1. Set the MCP key in docker-compose.yml (or your environment):

GIULIA_MCP_KEY: "your-secret-key-here"

The MCP server only starts if GIULIA_MCP_KEY is set. Without it, /mcp returns 401.

2. Configure the client by creating .mcp.json in your project root:

{
  "mcpServers": {
    "giulia": {
      "type": "http",
      "url": "http://localhost:4000/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-key-here"
      }
    }
  }
}

How It Works

All 74 @skill-annotated REST endpoints are automatically exposed as MCP tools. The mapping is generated at boot by Giulia.MCP.ToolSchema from the same @skill annotations that power the Discovery API.

Tool naming convention — endpoint path maps to tool name:

REST Endpoint	MCP Tool Name
`GET /api/knowledge/stats`	`knowledge_stats`
`GET /api/index/modules`	`index_modules`
`POST /api/runtime/connect`	`runtime_connect`
`GET /api/brief/architect`	`brief_architect`
`POST /api/knowledge/pre_impact_check`	`knowledge_pre_impact_check`

Rule: strip METHOD /api/, replace / with _. Path params like :id become by_id.

Parameter mapping — REST query params and body fields become flat tool arguments:

REST	MCP Tool Call
`GET /api/knowledge/impact?path=P&module=M&depth=2`	`knowledge_impact(path="P", module="M", depth="2")`
`POST /api/index/scan` with body `{"path":"P"}`	`index_scan(path="P")`

All arguments are strings. The server parses integers and floats internally.

Calling MCP Tools from LLMs

When an LLM (Claude Code, etc.) connects via MCP, it sees each tool with its description and parameter schema. The LLM calls tools by name with a flat argument map:

{
  "name": "knowledge_stats",
  "arguments": {
    "path": "D:/Development/GitHub/MyProject"
  }
}

Required vs optional parameters: The tool schema declares which parameters are required. The path parameter is required for most tools (exceptions: discovery_categories, runtime_pulse, runtime_monitor_status). Optional parameters can be omitted.

The path parameter must be the host-side project path (e.g., D:/Development/GitHub/MyProject), not the container path. The MCP server uses PathMapper for translation, just like the REST API.

MCP Resources

Five resource templates are available via the giulia:// URI scheme:

URI Pattern	Description
`giulia://projects/{path}`	Project summary and index stats (use `list` for all projects)
`giulia://modules/{path}`	List indexed modules for a project
`giulia://graph/{path}`	Knowledge Graph statistics
`giulia://skills/{category}`	Available API skills (use `list` for all)
`giulia://status`	Daemon status (node, version, role, active projects)

Excluded Endpoints

HTML pages (/api/monitor, /api/monitor/graph) and SSE streams (/api/monitor/stream) are excluded from MCP — they are not compatible with the tool call/response model.

Quick Reference

Category	Count	Prefix
Core	10	`/health`, `/api/*`
Index	9	`/api/index/*`
Knowledge	23	`/api/knowledge/*`
Intelligence	5	`/api/intelligence/`, `/api/briefing/`, `/api/brief/`, `/api/plan/`
Runtime	16	`/api/runtime/*`
Search	3	`/api/search/*`
Transaction	3	`/api/transaction/*`
Approval	2	`/api/approval/*`
Monitor	6	`/api/monitor/*`
Discovery	3	`/api/discovery/*`
MCP	74	`/mcp` (tools) + `giulia://` (resources)
Total	80 REST + 74 MCP tools

Note: The 80 REST total includes 10 core endpoints defined in the Endpoint module. The 9 sub-routers contribute 70 self-describing skills via the @skill decorator pattern, queryable at runtime through the Discovery API. The 74 MCP tools are auto-generated from these same skills (minus HTML/SSE endpoints).

FilesExpand file tree

API.md

Latest commit

History

API.md

File metadata and controls

Giulia REST API Reference

Table of Contents

Core

GET /health

POST /api/command

POST /api/command/stream

POST /api/ping

GET /api/status

GET /api/projects

POST /api/init

GET /api/debug/paths

GET /api/agent/last_trace

GET /api/approvals

Index

GET /api/index/modules

GET /api/index/functions

GET /api/index/module_details

GET /api/index/summary

GET /api/index/status

POST /api/index/scan

POST /api/index/verify

POST /api/index/compact

GET /api/index/complexity

Knowledge

GET /api/knowledge/stats

GET /api/knowledge/dependents

GET /api/knowledge/dependencies

GET /api/knowledge/centrality

GET /api/knowledge/impact

GET /api/knowledge/integrity

GET /api/knowledge/dead_code

GET /api/knowledge/cycles

GET /api/knowledge/god_modules

GET /api/knowledge/orphan_specs

GET /api/knowledge/fan_in_out

GET /api/knowledge/coupling

GET /api/knowledge/api_surface

GET /api/knowledge/change_risk

GET /api/knowledge/path

GET /api/knowledge/logic_flow

GET /api/knowledge/style_oracle

POST /api/knowledge/pre_impact_check

GET /api/knowledge/heatmap

GET /api/knowledge/unprotected_hubs

GET /api/knowledge/struct_lifecycle

GET /api/knowledge/duplicates

GET /api/knowledge/audit

GET /api/knowledge/conventions

GET /api/knowledge/topology

Intelligence

GET /api/intelligence/briefing

POST /api/briefing/preflight

GET /api/brief/architect

POST /api/plan/validate

GET /api/intelligence/report_rules

Runtime

GET /api/runtime/pulse

GET /api/runtime/top_processes

GET /api/runtime/hot_spots

GET /api/runtime/trace

GET /api/runtime/history

GET /api/runtime/trend

GET /api/runtime/alerts

POST /api/runtime/connect

GET /api/runtime/monitor/status

GET /api/runtime/profiles

GET /api/runtime/profile/latest

GET /api/runtime/profile/:id

POST /api/runtime/ingest

POST /api/runtime/ingest/finalize

GET /api/runtime/observations

GET /api/runtime/observation/:session_id

Search

GET /api/search