Agent integration

The API is designed to be a first‑class tool for AI coding agents (Claude Code, Cursor, Cline) and CI pipelines doing planning or audit work in repos that depend on each other across an org.

Why the API matters more than the UI

The graph UI is for humans. The API is for agents and pipelines: an agent fixing repo A needs to know what depends on A before it starts so the change can stay green. That’s a tool call, not a tab.

Recommended call pattern

For an agent in a working tree at github.com/myorg/repo:

Resolve the local clone URL to a Riftmap repo

GET /repositories/lookup?url=https://github.com/myorg/repo

Handles SSH/HTTPS and .git suffix variants. Returns 404 on miss, 409 on ambiguous match. Provide exactly one of url or full_path.

Hydrate context in one round-trip

GET /repositories/{id}/context

Returns

{ repository, dependencies (capped 100, with dependencies_total), dependents (capped 100, with dependents_total and dependent_repositories_total), artifacts, ownership }

. Both lists are declaration rows: a repository that uses several of this repo’s actions or packages appears once per use, so dependents_total counts uses and dependent_repositories_total counts repositories. Composes the dependency endpoints into one call. The ownership block is a slim { bus_factor, top_author_name, human_author_count } summary (null until the org is scanned with the ownership signal enabled). Impact is deliberately omitted — call /impact separately when blast radius is actually needed.

Drill in as needed

More than 100 dependents? GET /repositories/{id}/dependents?limit=500&offset=0 — the consumer is target_repository_id; group rows by raw_reference to answer “which repos use this action / package”
Transitive blast radius? GET /repositories/{id}/impact?max_depth=3 — inherits the min_confidence default; see The confidence rule.
Who maintains this — is it a single-maintainer risk? GET /repositories/{id}/ownership for the full contributor list, or GET /connected-orgs/{org_id}/ownership-risk for the org-wide ranked findings feed.
Neighbourhood graph for visualisation? GET /connected-orgs/{org_id}/graph?root={id}&depth=2

Decide trust

If last_activity_at > last_scanned_at, the data is stale. The agent can warn the user, fall back to a simpler analysis, or trigger a rescan and retry.

The freshness rule

Every repo response carries four freshness fields:

Field	Meaning
`last_scanned_at`	Wall‑clock time of the last successful scan that processed this repo.
`last_commit_sha`	The commit SHA observed at that scan.
`last_activity_at`	The most recent commit / push timestamp from the platform API.
`archived`	Whether the repo is archived on GitHub/GitLab.

The single rule agents must implement: if last_activity_at > last_scanned_at, treat the dependency data as stale. The repo has been pushed to since Riftmap last looked at it; new dependency declarations may exist that are not yet in the graph.

For a CI gate, “stale” usually means “trigger a rescan and re‑poll”. For an interactive agent, “stale” usually means “warn the user, then proceed with the caveat surfaced in the response”. archived: true is also a strong signal — archived repos are a frequent source of phantom edges in older graphs.

The confidence rule

Freshness tells you whether the data is current. Confidence tells you how much to trust an individual edge. Not every edge is equally certain. Formal parser edges — a package.json dependency, a go.mod require — are deterministic. Heuristic edges, where a git URL was found by pattern‑matching a file, are scored by the kind of file they came from: a URL in a Makefile is something a machine fetches, the same URL in a README is something a human reads. Traversal endpoints (/impact, and ?root= subgraphs) therefore take a min_confidence floor, defaulting to 0.4 — which admits every reference a machine could act on and excludes only the tier that means “a human reads this”.

Omit min_confidence unless you specifically mean to override it. The server default is the intended answer, and sending 0 disables the floor entirely. Every /impact response echoes applied_min_confidence and excluded_by_confidence, so a narrowed answer is never silent: an empty affected_repositories alongside a non‑zero excluded_by_confidence means “filtered out”, not “nothing breaks”.

Each affected repo carries its own confidence — the weakest edge on the strongest chain reaching it. To get a stricter answer, filter that field client‑side rather than re‑requesting. confidence >= 0.8 keeps deterministic parser edges plus build‑file and manifest evidence, using data the response already carries. A lower‑confidence edge is a real reference to the repo, but it may be commentary rather than a live dependency. The default deliberately errs toward including them: for “what breaks if I change this?”, a missing dependent is a worse answer than an extra one you can check.

Pagination contract

All list endpoints (dependencies, dependents, repositories, artifacts, scans, members) follow the same shape:

Parameter	Type	Default	Max
`limit`	integer	`100`	`500`
`offset`	integer	`0`	—

Response header X-Total-Count carries the total matching rows so the client can compute page counts in one round‑trip. Out‑of‑range values return 422.

Auth

Workspace API keys (X-API-Key: rfm_live_… or Authorization: Bearer rfm_live_…). Keys are workspace‑scoped — the agent never needs to pass a workspace_id. See Authentication for the full matrix and rate limits.

Static OpenAPI schema

Live /openapi.json and /docs stay disabled in production — they would otherwise hand attackers a complete endpoint inventory plus validation rules. The schema is generated in CI from the dev‑mode app and shipped with the frontend build at a stable static URL:

https://app.riftmap.dev/openapi.json

Agents and MCP servers fetch from that URL. CI fails the build if the committed schema drifts from the routes, so the static file is always current.

The full surface

Endpoint	One-liner
`GET /repositories/lookup?url=…` or `?full_path=…`	Resolve a git remote URL (param: `url`, not `clone_url`) or `org/repo` slug (param: `full_path`) → Riftmap repo. Pass exactly one.
`GET /repositories/{id}`	Repo details, including freshness fields.
`GET /repositories/{id}/context`	Recommended second hop. Single‑call bundle: repo + capped deps + capped dependents + artifacts + slim ownership summary.
`GET /repositories/{id}/dependencies`	Direct dependency declarations, paginated, deduplicated.
`GET /repositories/{id}/dependents`	Direct dependents, one row per consumer declaration, paginated. The consumer is `target_repository_id`; group by `raw_reference` for per-action or per-package consumers.
`GET /repositories/{id}/impact`	Transitive downstream blast radius via Python BFS. Repo-level; not file-scoped (no `path`/`file`/`job` query param). Echoes `applied_min_confidence` and `excluded_by_confidence`; each affected repo carries its own `confidence`.
`GET /repositories/{id}/ownership`	Per-repo bus factor + human contributor list (paginated). Names only, never emails (PII). Zeros/empty until the ownership signal is enabled.
`GET /connected-orgs/{id}/ownership-risk`	Ranked findings feed of concentration-risk repos (high fan-in × low bus factor). Query overrides `min_dependents` / `max_bus_factor`.
`GET /artifacts/{id}/consumers`	Who consumes this artifact and at which version (version‑aware).
`GET /artifacts/{id}/versions`	All versions seen across the org.
`GET /connected-orgs/{id}/graph`	Full org graph or subgraph anchored at a repo.

The full schema with request/response shapes, query params, and error codes is at API Reference.

Next: code samples

The most common four flows — lookup, context, impact, subgraph — in curl, Python, and TypeScript: Examples.

Getting Started