Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.riftmap.dev/llms.txt

Use this file to discover all available pages before exploring further.

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 }. Composes four endpoints into one call. 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
  • 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://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/lookupResolve a clone URL or org/repo slug → Riftmap repo.
GET /repositories/{id}Repo details, including freshness fields.
GET /repositories/{id}/contextSingle‑call agent bundle (repo + capped deps + capped dependents + artifacts).
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.
GET /artifacts/{id}/consumersWho consumes this artifact and at which version.
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.