Skip to main content

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.

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.