The graph, as a
tool call.
Your AI coding agent can't see what depends on what from inside a single repo's clone. Riftmap exposes the cross-repo dependency graph as a small HTTP API — three endpoints your agent calls during planning, with a freshness contract on every response.
Watch an agent ask "who would I break?"
A Claude Code session inside VS Code. The agent is given the prompt below, calls the Riftmap
API on its own, surfaces 51 consumers across the org, and classifies them by whether they pin
a release tag or float on main. It also flags one honest caveat about the
granularity of the edge — exactly the kind of self-correction you want from an agent making
a breaking-change decision.
I want to delete the `helm:deploy` job — we're moving Helm deploys into the umbrella chart instead. Who would I break? Check if any consumers are pinned to a release tag so I know who has a grace period vs. who breaks on next pipeline run. Use the Riftmap API - https://docs.riftmap.dev/api-reference/introduction The API key and workspace ID is set as a global environment variables as $RIFTMAP_API_KEY and $RIFTMAP_WORKSPACE_ID
Lookup → context → impact.
The recommended call pattern for an agent in a working tree at any repo in your org. The first two cover almost every planning question. The third unlocks transitive blast radius when you need it.
- 01GET
/repositories/lookupResolve a clone URL to a Riftmap repo ID.
Handles SSH/HTTPS and
.gitvariants. Returns 404 on miss, 409 on ambiguous match. The first call an agent makes — it knows the repo it is editing, not its node in the graph. - 02GET
/repositories/{id}/contextOne round-trip: repo + dependencies + dependents + artifacts.
Composes four endpoints into a single call. Lists are capped at 100 with
_totalcounts so the agent knows when to paginate. The "what does this repo touch?" question at the start of a task. - 03GET
/repositories/{id}/impactTransitive downstream blast radius.
BFS through the dependency graph up to
max_depth. Use when the agent needs the full cascade — e.g. before shipping a breaking change to a shared module that other modules consume.
The full surface — including pagination, artifacts, and the org-level graph endpoint — is documented in the agent integration guide .
A working flow in three languages.
Lookup, hydrate context, freshness-check. The same shape your agent's tool implementation ends up taking, whether it lives in a Python pipeline, a Node service, or a one-shot shell script.
# 1. Resolve the working tree's clone URL to a Riftmap repo
REPO_ID=$(curl -s \
"https://api.riftmap.dev/api/v1/repositories/lookup?url=https://github.com/myorg/payments-api" \
-H "X-API-Key: $RIFTMAP_API_KEY" | jq -r '.id')
# 2. Hydrate context in one round-trip
curl -s "https://api.riftmap.dev/api/v1/repositories/$REPO_ID/context" \
-H "X-API-Key: $RIFTMAP_API_KEY"import os, httpx
BASE = "https://api.riftmap.dev/api/v1"
HEADERS = {"X-API-Key": os.environ["RIFTMAP_API_KEY"]}
async with httpx.AsyncClient(headers=HEADERS, timeout=15) as client:
# 1. Resolve clone URL → repo id
r = await client.get(
f"{BASE}/repositories/lookup",
params={"url": "https://github.com/myorg/payments-api"},
)
repo_id = r.json()["id"]
# 2. Hydrate repo + capped deps + capped dependents + artifacts
ctx = (await client.get(f"{BASE}/repositories/{repo_id}/context")).json()
# Freshness check — the single rule every agent should implement
repo = ctx["repository"]
if repo["last_activity_at"] > repo["last_scanned_at"]:
print("WARN: graph is stale — fall back to file exploration, or trigger a rescan")
const BASE = "https://api.riftmap.dev/api/v1";
const HEADERS = { "X-API-Key": process.env.RIFTMAP_API_KEY! };
// 1. Resolve clone URL → repo id
const lookup = await fetch(
`${BASE}/repositories/lookup?url=https://github.com/myorg/payments-api`,
{ headers: HEADERS },
);
const { id: repoId } = await lookup.json();
// 2. Hydrate repo + capped deps + capped dependents + artifacts
const ctx = await (
await fetch(`${BASE}/repositories/${repoId}/context`, { headers: HEADERS })
).json();
// Freshness check — the single rule every agent should implement
if (ctx.repository.last_activity_at > ctx.repository.last_scanned_at) {
console.warn("graph is stale — fall back to file exploration, or trigger a rescan");
}
The OpenAPI schema is at
app.riftmap.dev/openapi.json .
Drop it into Claude Code, Cursor, an MCP server, or any agent runtime that consumes OpenAPI.
One rule every agent should implement.
last_activity_at > last_scanned_at treat the graph as stale
Every repo response carries last_scanned_at, last_commit_sha,
last_activity_at, and archived. If the repo has been pushed to since
Riftmap last looked at it, new dependency declarations may exist that aren't yet in the graph.
For an interactive agent, "stale" usually means warn the user and proceed with the caveat.
For a CI gate, it means trigger a rescan and re-poll before letting the merge through.
archived: true is also a strong signal — archived repos are a frequent source of
phantom edges in older graphs, and most agent decisions should weight them lower.
Three places this lands.
- Claude Code · Cursor · Codex
In-IDE tool call before planning
Drop the OpenAPI schema into the agent runtime as a tool. Before the agent plans a refactor that touches a shared module, it calls
/contextand folds the dependents list into its plan — no more locally-correct changes that break downstream consumers. - CI gate
Block merge on stale graphs
On every PR that touches a shared component, your pipeline calls
/impactand posts the consumer list as a comment. Iflast_activity_at > last_scanned_at, trigger a rescan and re-poll before letting the merge through. - Custom agents
Any OpenAPI-capable runtime
The schema lives at app.riftmap.dev/openapi.json and stays current — CI fails the build if it drifts from the routes. Wire it into LangGraph, AutoGen, your own MCP server, or any tool layer that consumes OpenAPI.
Questions agents (and the engineers wiring them) ask.
More context in the agent integration guide and the API reference.
01 Do I need MCP, or is the HTTP API enough?
The HTTP API is the recommended path today and works with any agent runtime that can call HTTP or consume an OpenAPI schema — Claude Code, Cursor, Codex, custom LangGraph or MCP agents, CI pipelines. An MCP server wrapping the same three endpoints is on the roadmap but not required.
02 How fresh is the data my agent receives?
Every repo response carries four freshness fields: last_scanned_at, last_commit_sha, last_activity_at, and archived. The single rule agents must implement: if last_activity_at > last_scanned_at, the repo has been pushed to since Riftmap last looked at it — treat the dependency data as stale and either warn the user, fall back to a simpler analysis, or trigger a rescan and retry.
03 How is this different from code search or @-mention context in my IDE?
Code search is text matching across files an agent already has cloned — it answers "where does this string appear?" Riftmap is a parser-derived graph across an entire org — it answers "what depends on this?" with edges built from Terraform source blocks, Dockerfile FROM lines, go.mod requires, GitLab CI includes, and nine more ecosystems. The graph spans every repo in your org, not just the ones the agent has open.
04 What does the agent get back?
For /context: the repo node with freshness fields, up to 100 direct dependencies and 100 direct dependents (with _total counts), and the list of artifacts the repo produces (Docker images, Helm charts, Terraform modules, packages). Every dependency edge carries the version_constraint declared by the consumer, so the agent can tell who pins to a tag versus who floats on a branch.
05 Are there rate limits?
Yes — every response includes rate-limit headers so the agent can pace itself. Limits scale with your plan; the free tier supports comfortable interactive use from a coding agent. CI pipelines doing bulk operations may want to batch.
06 Can I self-host this for my agents?
A self-hosted deployment option is on the roadmap. Today the API is served from app.riftmap.dev as a managed service — the same workspace your team uses for the UI also serves the API, no separate setup. Free tier includes API access on every plan.
Give your agent the graph.
Free tier includes 15 repos and full API access. ~90 seconds to first scan; the API is live the moment the scan finishes.