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), artifacts, ownership }

. 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
Transitive blast radius? GET /repositories/{id}/impact?max_depth=3
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.

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, paginated, deduplicated.
`GET /repositories/{id}/impact`	Transitive downstream blast radius via Python BFS. Repo-level; not file-scoped (no `path`/`file`/`job` query param).
`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