JSON Protocol

This page summarizes the main HTTP payload shapes currently used by the web UI.

Read this page when you want exact backend payload shapes. If you want to understand why those payloads look this way, read Architecture / Pipeline first.

Common Types

Node

{
  "id": "method:...",
  "kind": "method",
  "label": "foo",
  "fqname": "MyPkg.foo",
  "location": {"file": "src/a.jl", "line": 42, "column": 1},
  "metadata": {"external": true, "external_group": "external_package"}
}

metadata.external_group is optional for external method nodes:

base_stdlib
external_package

Other useful optional metadata fields include:

virtual
synthetic
overload_style

Edge

{
  "id": "edge:...",
  "kind": "call_possible",
  "source": "method:...",
  "target": "method:...",
  "confidence": "possible",
  "evidence": {
    "kinds": ["call_possible"],
    "engine": "da_source",
    "file": "src/a.jl",
    "line": 55
  }
}

evidence contract:

evidence.kinds is required for every edge.
evidence.kinds is an array of edge-kind strings.
evidence.kinds always includes the current top-level kind.
Aggregated edges may include multiple values in evidence.kinds.
evidence.engine = "da_source" refers to the DepAtlasSource engine id.

confidence enum:

exact
inferred
possible
dynamic

confidence should be interpreted as evidence class, not certainty.

Endpoints

POST `/api/v1/tasks`

{
  "analysis_path": "/abs/path/project",
  "refresh_mode": "full"
}

This endpoint creates a new analysis task.

The normal product request flow only needs analysis_path and refresh_mode. JET runs use the dedicated JET-view endpoints below.

POST `/api/v1/snapshots/{snapshot_id}/jet-views`

Create or reuse a cached pure-JET graph view for a selected method node.

{
  "method_node_id": "method:abc123",
  "overload_site": {"file": "src/MyPkg.jl", "line": 42}
}

GET `/api/v1/snapshots/{snapshot_id}/jet-views/{jet_view_id}`

Fetch the status or completed result of a cached JET view.

POST `/api/v1/snapshots/{snapshot_id}/inference/query`

Run a query-time semantic refinement provider against an existing snapshot. The default provider is source_static, which only reads existing snapshot edge evidence.

{
  "target": {
    "kind": "call_edge",
    "edge_id": "edge:abc123"
  },
  "providers": ["source_static"],
  "cost_policy": "snapshot_only"
}

callsite_location targets use source coordinates and can be sent either with coordinates directly on target or inside target.payload:

{
  "target": {
    "kind": "callsite_location",
    "file": "src/MyPkg.jl",
    "line": 42,
    "column": 17
  },
  "providers": ["source_static"],
  "cost_policy": "snapshot_only"
}

Supported target kinds are:

call_edge
callsite_location
method
expression_range

In the first implementation, source_static answers call_edge and callsite_location. A callsite_location query with file and line returns all snapshot call edges on that line; adding column narrows to the matching callsite when the snapshot contains column evidence. If an older snapshot has only line-level evidence, the provider returns line-level matches with a diagnostic instead of guessing.

The jet provider is interactive-cost and must be requested explicitly. Its first implementation supports method targets only and returns a selected-method pure JET graph as a query artifact. callsite_location is intentionally unsupported for jet until compiler evidence can be attributed back to source callsite coordinates.

{
  "target": {
    "kind": "method",
    "method_node_id": "method:entry"
  },
  "providers": ["jet"],
  "cost_policy": "interactive"
}

{
  "request": {
    "snapshot_id": "snp_abc123",
    "target": {"kind": "call_edge", "payload": {"edge_id": "edge:abc123"}},
    "providers": ["source_static"],
    "cost_policy": "snapshot_only"
  },
  "results": [
    {
      "status": "answered",
      "provider": "source_static",
      "provider_version": "1",
      "cost_class": "snapshot",
      "confidence": "possible",
      "inferred_arg_types": [],
      "method_matches": [
        {
          "node_id": "method:target",
          "fqname": "MyPkg.foo",
          "signature": "foo(x::Int)",
          "confidence": "possible",
          "source": "snapshot_edge"
        }
      ],
      "evidence_trace": [
        {
          "provider": "source_static",
          "engine": "da_source",
          "edge_id": "edge:abc123",
          "dispatch_resolution": "unique"
        }
      ],
      "artifacts": {},
      "diagnostics": [],
      "elapsed_seconds": 0.0,
      "cached": false
    }
  ]
}

JET-backed results use the same outer result schema and place provider-specific output under artifacts:

{
  "status": "answered",
  "provider": "jet",
  "provider_version": "2",
  "cost_class": "interactive",
  "method_matches": [],
  "evidence_trace": [],
  "artifacts": {
    "jet_graph": {"nodes": [], "edges": [], "diagnostics": []},
    "metrics": {
      "entrypoint_resolved": true,
      "root_node_id": "method:entry",
      "inferred_edges": 0,
      "dynamic_edges": 0
    }
  },
  "diagnostics": [],
  "elapsed_seconds": 0.0,
  "cached": false
}

GET `/api/v1/tasks/{task_id}`

This endpoint returns task lifecycle status, normalized config, progress, and any eventual snapshot id.

GET `/api/v1/snapshots/{snapshot_id}/summary`

This endpoint returns snapshot counts, supported layers, canonical project_modules, and diagnostics.

POST `/api/v1/snapshots/{snapshot_id}/graph/query`

This endpoint returns filtered nodes, edges, and pagination state for one graph layer.

Response note:

nodes is still the single renderable node list.
node_appearance explains why each returned node appears in this query result.
node_appearance[*].reasons may include:
- edge_endpoint
- scope_match
- search_match

The request body includes:

layer
filters
optional page

Common filter fields include:

edge_kinds
confidence_min
module_prefix
show_overloaded_functions
show_base_stdlib_calls
show_external_package_calls

Query response shape

nodes is still the single renderable node list. node_appearance is query-context metadata that explains why each returned node is present.

{
  "nodes": [{"id": "method:entry", "kind": "method", "label": "entry", "fqname": "Main.entry", "location": {"file": "src/Main.jl", "line": 3, "column": 1}, "metadata": {}}],
  "edges": [{"id": "e_call_entry_mid", "kind": "call_inferred", "source": "method:entry", "target": "method:mid", "confidence": "inferred", "evidence": {"kinds": ["call_inferred"], "callee_group": "project", "overload_style": "none"}}],
  "node_appearance": {
    "method:entry": {"reasons": ["edge_endpoint", "search_match"]},
    "method:mid": {"reasons": ["edge_endpoint"]}
  },
  "page": {"cursor": "1", "limit": 2000, "next_cursor": null, "total_edges": 1}
}

POST `/api/v1/snapshots/{snapshot_id}/reachability/query`

This endpoint returns a bounded reachability subgraph for one seed node.

Response note:

nodes is still the single renderable node list.
node_appearance explains why each returned node appears in this reachability result.
node_appearance[*].reasons may include:
- edge_endpoint
- reachability_seed

The request body includes:

layer
node_id
optional direction
optional depth
optional filters
optional limits

{
  "seed_node_id": "method:entry",
  "layer": "method",
  "direction": "outgoing",
  "depth": 3,
  "nodes": [{"id": "method:entry", "kind": "method", "label": "entry", "fqname": "Main.entry", "location": {}, "metadata": {}}],
  "edges": [],
  "node_appearance": {
    "method:entry": {"reasons": ["reachability_seed"]}
  },
  "reachability": {
    "incoming": {"node_depths": {}, "edge_depths": {}},
    "outgoing": {"node_depths": {}, "edge_depths": {}}
  },
  "truncated": false
}

GET `/api/v1/snapshots/{snapshot_id}/node?id=<node_id>`

This endpoint returns the node plus incoming and outgoing neighborhood information.

GET `/api/v1/source?file=<abs-or-rel>&line=<n>&snapshot_id=<optional>`

This endpoint returns a source snippet centered around one line.

If snapshot_id is provided, the backend resolves relative paths against that snapshot's project root.

GET `/api/v1/fs/list?path=<optional>`

This endpoint returns directory entries for the path browser used by the web UI.

Notes

The web UI currently uses the /api/v1/... namespace throughout.
Graph export JSON is documented separately in Export JSON.

Want the backend reasoning behind these payloads? See Architecture / Pipeline.
Want the Julia-side entrypoints instead of HTTP? See Julia API.

Common Types​

Node​

Edge​

Endpoints​

POST /api/v1/tasks​

POST /api/v1/snapshots/{snapshot_id}/jet-views​

GET /api/v1/snapshots/{snapshot_id}/jet-views/{jet_view_id}​

POST /api/v1/snapshots/{snapshot_id}/inference/query​

GET /api/v1/tasks/{task_id}​

GET /api/v1/snapshots/{snapshot_id}/summary​

POST /api/v1/snapshots/{snapshot_id}/graph/query​

POST /api/v1/snapshots/{snapshot_id}/reachability/query​

GET /api/v1/snapshots/{snapshot_id}/node?id=<node_id>​

GET /api/v1/source?file=<abs-or-rel>&line=<n>&snapshot_id=<optional>​

GET /api/v1/fs/list?path=<optional>​

Notes​

Related Pages​