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 Riftmap API is a small, paginated REST API that exposes the dependency graph Riftmap builds from your connected orgs. It’s designed to be called by AI coding agents and CI pipelines that need to answer “if I change repo X, what else breaks?”

​
Base URL

https://api.riftmap.dev
All endpoints are prefixed with /api/v1.

​
Authentication

All endpoints require a workspace API key. Keys look like rfm_live_<random> and can be passed as either header: 
# Canonical
curl https://api.riftmap.dev/api/v1/repositories \
  -H "X-API-Key: rfm_live_xxx"

# Convenience alias
curl https://api.riftmap.dev/api/v1/repositories \
  -H "Authorization: Bearer rfm_live_xxx"
Keys are workspace‑scoped — you never pass a workspace_id. See Authentication for the full header matrix, rate limits, and revocation.

​
The endpoint surface

The full agent‑facing surface, with one‑liners. Each row links to the auto‑generated reference page in the sidebar for the full request/response shape.
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.
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.
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 typical agent call pattern is lookup → context → impact. See Agent integration for the recommended flow, the freshness check rule, and the four core flows in curl / Python / TypeScript.
/impact is not file-scoped. It’s a repo-to-repo BFS — there is no path, file, or job query parameter, and FastAPI silently ignores unknown query params (so a hallucinated filter name returns the same fan-out as no filter). For “who consumes file X in repo Y”, call /repositories/{id}/dependents and grep the listed consumer repos directly; per-file edges aren’t stored in the graph. For artifact-version consumers (Docker image / Helm chart / Terraform module), use /artifacts/{id}/consumers — that one is version-aware.

​
Conventions

  • Versioning — All endpoints are prefixed with /api/v1.
  • Pagination — List endpoints accept limit (1–500, default 100) and offset (default 0) query params. The total matching row count is returned in the X-Total-Count response header so a client can compute page counts in one round‑trip. Out‑of‑range values return 422.
  • Workspace isolation — Foreign‑workspace requests return 404, never 403, to avoid leaking existence.
  • Freshness — Every repo response carries last_scanned_at, last_commit_sha, last_activity_at, and archived. If last_activity_at > last_scanned_at, treat the data as stale.
  • Errors — JSON body with a detail field and an appropriate HTTP status code. Agents should explicitly handle 401, 404, 409 (ambiguous lookup), 422, and 429 (Retry-After honoured).

​
OpenAPI schema

Live /openapi.json and /docs are gated off in production. The schema is generated in CI from the dev‑mode app and shipped at a stable static URL: 
https://app.riftmap.dev/openapi.json
CI fails the build if the committed schema drifts from the routes, so the static file is always current.
For LLM agents: fetch this URL with raw curl (or your runtime’s HTTP client) and parse the JSON yourself. WebFetch‑style summarizing tools tend to collapse the schema down to “endpoints exist but aren’t listed here” because of size — you’ll lose the concrete paths you came for.
curl -s https://app.riftmap.dev/openapi.json | jq '.paths | keys'

​
Where to start

Agent integration

The lookup → context → impact pattern, the freshness rule, and the full surface in one page.

Code examples

The four core flows in curl, Python (httpx), and TypeScript (fetch).

Authentication

Create a workspace API key and learn the header conventions.

Quickstart

Sign up, connect an org, and make your first API call in five minutes.
The individual operations in the sidebar are generated from the OpenAPI schema above and include full request/response shapes, query parameters, and error codes.