Skip to main content
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. For an agent in a working tree at github.com/myorg/repo:
1

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.
2

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.
3

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
4

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:
FieldMeaning
last_scanned_atWall‑clock time of the last successful scan that processed this repo.
last_commit_shaThe commit SHA observed at that scan.
last_activity_atThe most recent commit / push timestamp from the platform API.
archivedWhether 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:
ParameterTypeDefaultMax
limitinteger100500
offsetinteger0—
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

EndpointOne-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}/contextRecommended second hop. Single‑call bundle: repo + capped deps + capped dependents + artifacts + slim ownership summary.
GET /repositories/{id}/dependenciesDirect dependency declarations, paginated, deduplicated.
GET /repositories/{id}/dependentsDirect dependents, paginated, deduplicated.
GET /repositories/{id}/impactTransitive downstream blast radius via Python BFS. Repo-level; not file-scoped (no path/file/job query param).
GET /repositories/{id}/ownershipPer-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-riskRanked findings feed of concentration-risk repos (high fan-in × low bus factor). Query overrides min_dependents / max_bus_factor.
GET /artifacts/{id}/consumersWho consumes this artifact and at which version (version‑aware).
GET /artifacts/{id}/versionsAll versions seen across the org.
GET /connected-orgs/{id}/graphFull 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.