# Examples Source: https://docs.riftmap.dev/agents/examples Copy-paste Riftmap API examples in curl, Python, and TypeScript: resolve a repo, hydrate context, compute blast radius, and walk the dependency subgraph. The four most common agent flows, end‑to‑end. Every snippet expects two environment variables: ```bash theme={null} RIFTMAP_API_KEY=rfm_live_xxx RIFTMAP_BASE_URL=https://api.riftmap.dev/api/v1 ``` The Python examples use `httpx` (async). The TypeScript examples use the runtime‑native `fetch` (Node 22+ / modern browsers). *** ## 1. Resolve a clone URL The agent has a working tree at `github.com/myorg/payments-api` and needs to find the corresponding Riftmap repo. ```bash curl theme={null} curl -s "$RIFTMAP_BASE_URL/repositories/lookup?url=https://github.com/myorg/payments-api" \ -H "X-API-Key: $RIFTMAP_API_KEY" ``` ```python Python theme={null} import os import httpx BASE = os.environ["RIFTMAP_BASE_URL"] HEADERS = {"X-API-Key": os.environ["RIFTMAP_API_KEY"]} async def lookup(clone_url: str) -> dict | None: async with httpx.AsyncClient(headers=HEADERS, timeout=10) as client: r = await client.get(f"{BASE}/repositories/lookup", params={"url": clone_url}) if r.status_code == 404: return None r.raise_for_status() return r.json() ``` ```typescript TypeScript theme={null} const BASE = process.env.RIFTMAP_BASE_URL!; const HEADERS = { "X-API-Key": process.env.RIFTMAP_API_KEY! }; export async function lookup(cloneUrl: string) { const url = new URL(`${BASE}/repositories/lookup`); url.searchParams.set("url", cloneUrl); const r = await fetch(url, { headers: HEADERS }); if (r.status === 404) return null; if (!r.ok) throw new Error(`lookup failed: ${r.status}`); return r.json(); } ``` Returns the repo row including freshness fields. Use `full_path=myorg/payments-api` instead of `url=` if you only have the slug. *** ## 2. Hydrate context in one round‑trip Once you have the repo ID, fetch repo + capped dependencies + capped dependents + artifacts + a slim ownership summary in a single call. ```bash curl theme={null} curl -s "$RIFTMAP_BASE_URL/repositories/$REPO_ID/context" \ -H "X-API-Key: $RIFTMAP_API_KEY" ``` ```python Python theme={null} async def get_context(repo_id: str) -> dict: async with httpx.AsyncClient(headers=HEADERS, timeout=15) as client: r = await client.get(f"{BASE}/repositories/{repo_id}/context") r.raise_for_status() ctx = r.json() # Freshness check repo = ctx["repository"] if repo["last_activity_at"] and repo["last_scanned_at"]: if repo["last_activity_at"] > repo["last_scanned_at"]: print(f"WARN: stale data for {repo['full_path']}") return ctx ``` ```typescript TypeScript theme={null} export async function getContext(repoId: string) { const r = await fetch(`${BASE}/repositories/${repoId}/context`, { headers: HEADERS }); if (!r.ok) throw new Error(`context failed: ${r.status}`); const ctx = await r.json(); const { last_activity_at, last_scanned_at, full_path } = ctx.repository; if (last_activity_at && last_scanned_at && last_activity_at > last_scanned_at) { console.warn(`stale data for ${full_path}`); } return ctx; } ``` Use `dependencies_total` and `dependents_total` to detect when you need to paginate the full lists separately (the bundled arrays are capped at 100). Both lists are declaration rows, so a repository using several of this repo's actions or packages appears once per use: `dependent_repositories_total` is the number of distinct repositories. *** ## 3. Compute the transitive blast radius When you actually need to know "if I change repo A, what *transitively* breaks?", call `/impact`. This runs a Python traversal over confidence-filtered edges. ```bash curl theme={null} curl -s "$RIFTMAP_BASE_URL/repositories/$REPO_ID/impact?max_depth=3" \ -H "X-API-Key: $RIFTMAP_API_KEY" ``` ```python Python theme={null} async def impact(repo_id: str, max_depth: int = 3, min_confidence: float | None = None) -> dict: async with httpx.AsyncClient(headers=HEADERS, timeout=20) as client: params: dict = {"max_depth": max_depth} # Omit min_confidence to take the server default (0.4). if min_confidence is not None: params["min_confidence"] = min_confidence r = await client.get(f"{BASE}/repositories/{repo_id}/impact", params=params) r.raise_for_status() return r.json() # Result shape: { source_repository, affected_repositories: [{id, name, full_path, depth, confidence}], # total_affected, max_depth_reached, applied_min_confidence, excluded_by_confidence } ``` ```typescript TypeScript theme={null} export async function impact(repoId: string, maxDepth = 3, minConfidence?: number) { const url = new URL(`${BASE}/repositories/${repoId}/impact`); url.searchParams.set("max_depth", String(maxDepth)); // Omit min_confidence to take the server default (0.4). if (minConfidence !== undefined) url.searchParams.set("min_confidence", String(minConfidence)); const r = await fetch(url, { headers: HEADERS }); if (!r.ok) throw new Error(`impact failed: ${r.status}`); return r.json(); } ``` `max_depth` defaults to 10 (range 1–20). `min_confidence` defaults to **0.4**, which admits every reference a machine could act on and excludes only references a human reads (prose, templates, generated blobs). Two fields on the response keep a filtered answer honest: * `applied_min_confidence` — the floor actually used, so you can tell a narrowed answer from a complete one. * `excluded_by_confidence` — how many repos the floor removed. An empty `affected_repositories` with a non-zero count here means "filtered out", not "nothing breaks". Each affected repo's own `confidence` is the weakest edge on the strongest chain reaching it. **To narrow the radius, filter that field client-side rather than re-requesting** — `confidence >= 0.8` gives you deterministic parser edges plus build-file and manifest evidence, using data the response already carries. *** ## 4. Walk the local subgraph For visualisation, or for an agent that wants the local neighbourhood rather than the full transitive set, request a subgraph anchored at a repo. ```bash curl theme={null} curl -s "$RIFTMAP_BASE_URL/connected-orgs/$ORG_ID/graph?root=$REPO_ID&depth=2" \ -H "X-API-Key: $RIFTMAP_API_KEY" ``` ```python Python theme={null} async def subgraph(org_id: str, root_repo_id: str, depth: int = 2) -> dict: async with httpx.AsyncClient(headers=HEADERS, timeout=15) as client: r = await client.get( f"{BASE}/connected-orgs/{org_id}/graph", params={"root": root_repo_id, "depth": depth}, ) r.raise_for_status() return r.json() ``` ```typescript TypeScript theme={null} export async function subgraph(orgId: string, rootRepoId: string, depth = 2) { const url = new URL(`${BASE}/connected-orgs/${orgId}/graph`); url.searchParams.set("root", rootRepoId); url.searchParams.set("depth", String(depth)); const r = await fetch(url, { headers: HEADERS }); if (!r.ok) throw new Error(`graph failed: ${r.status}`); return r.json(); } ``` Returns `{ nodes: [{id, type, label, metadata: {archived, last_activity_at, health_status, …}}], edges: [{source, target, dependency_type, version_constraint, confidence}] }`. The shape is G6‑ready, but plain enough to drive any visualisation library. *** ## Pagination For `dependencies` / `dependents` lists past 100 items: ```bash curl theme={null} # First page curl -s -D - "$RIFTMAP_BASE_URL/repositories/$REPO_ID/dependents?limit=500&offset=0" \ -H "X-API-Key: $RIFTMAP_API_KEY" # Inspect X-Total-Count in headers; loop with offset += 500. ``` ```python Python theme={null} async def all_dependents(repo_id: str) -> list[dict]: out, offset, limit = [], 0, 500 async with httpx.AsyncClient(headers=HEADERS, timeout=20) as client: while True: r = await client.get( f"{BASE}/repositories/{repo_id}/dependents", params={"limit": limit, "offset": offset}, ) r.raise_for_status() page = r.json() out.extend(page) total = int(r.headers.get("X-Total-Count", len(out))) offset += limit if offset >= total: return out ``` ```typescript TypeScript theme={null} export async function allDependents(repoId: string) { const out: unknown[] = []; let offset = 0; const limit = 500; while (true) { const url = new URL(`${BASE}/repositories/${repoId}/dependents`); url.searchParams.set("limit", String(limit)); url.searchParams.set("offset", String(offset)); const r = await fetch(url, { headers: HEADERS }); if (!r.ok) throw new Error(`dependents failed: ${r.status}`); out.push(...(await r.json())); const total = Number(r.headers.get("X-Total-Count") ?? out.length); offset += limit; if (offset >= total) return out; } } ``` ### Group dependents by action or package Each `/dependents` row is one use: the consuming repository is `target_repository_id` / `target_repository_name`, and `raw_reference` is what it uses — for GitHub Actions the full `uses:` path, such as `grafana/shared-workflows/actions/send-slack-message`. Grouping on it answers "which repos use this action, pinned where?" before you deprecate or break it. ```python Python theme={null} from collections import defaultdict async def consumers_by_reference(repo_id: str) -> dict[str, dict[str, set[str]]]: by_ref: dict[str, dict[str, set[str]]] = defaultdict(lambda: defaultdict(set)) for row in await all_dependents(repo_id): # owner/repo names are case-insensitive on GitHub, so group on the lowercased path ref = row["raw_reference"].lower() by_ref[ref][row["target_repository_name"]].add(row["version_constraint"] or "") return by_ref # {action path: {consumer repo: {pins}}} ``` A consumer last scanned before v1.25.0 still reports the bare `owner/repo` of the hub as its `raw_reference` until it is rescanned. *** ## Errors agents should handle | Status | Meaning | Recommended action | | ------ | ----------------------------------------------- | ----------------------------------------------------------------------- | | `401` | Missing or invalid API key | Surface to user; never retry. | | `404` | Repo not in this workspace, or never scanned | Try `lookup` with the alternate parameter; fall back to "unknown repo". | | `409` | Lookup matched multiple repos | Disambiguate using `full_path`. | | `422` | Out‑of‑range pagination, or invalid query param | Fix the request; do not retry. | | `429` | Rate limit (mutations only) | Honour `Retry-After` header before retrying. | # MCP & CLI roadmap Source: https://docs.riftmap.dev/agents/mcp-cli-roadmap Riftmap's MCP server and CLI roadmap: why both are deferred while the HTTP API serves AI agents today, plus the planned tool surface, commands, and env auth. The current API is sufficient for agent integration via raw HTTP — every flow on this site works today against `https://api.riftmap.dev/api/v1` with a workspace API key. Two packaging layers are designed but **deferred until there's pull from real users**. Building them before users ask risks designing for hypothetical workflows. ## MCP server (`riftmap-mcp`) Wraps the agent‑facing endpoints as MCP tools so Claude Code, Cursor, and Cline can use them without any HTTP plumbing in the agent's prompt. **Planned layout:** * Published to PyPI as a separate package: `pipx install riftmap-mcp`. * Python implementation using Anthropic's official `mcp` SDK. **Planned tool surface:** ``` riftmap_lookup_repository # → GET /repositories/lookup riftmap_get_context # → GET /repositories/{id}/context riftmap_get_dependents # → GET /repositories/{id}/dependents riftmap_get_dependencies # → GET /repositories/{id}/dependencies riftmap_get_impact # → GET /repositories/{id}/impact riftmap_get_subgraph # → GET /connected-orgs/{id}/graph ``` **Auth:** environment variables only. ```bash theme={null} RIFTMAP_API_KEY=rfm_live_xxx RIFTMAP_BASE_URL=https://api.riftmap.dev/api/v1 # default ``` ## CLI (`riftmap`) Same surface as a shell command for CI pipelines and humans who'd rather pipe JSON than write `curl` invocations. **Planned commands:** ```bash theme={null} riftmap lookup --url https://github.com/myorg/repo riftmap context riftmap dependents --limit 500 riftmap dependencies riftmap impact --max-depth 3 riftmap subgraph --root --depth 2 ``` * Ships as a `riftmap` console\_script on PyPI, separate from internal operator tooling. * JSON output by default (agent‑friendly); `--pretty` flag for human reading. * Same env contract as the MCP server. ## Order when building CLI first — its auth and base‑URL plumbing is reused by the MCP server, which then becomes thin tool definitions over the CLI logic. ## Why not now The data and endpoints are the load‑bearing piece. Packaging is mechanical once the surface is stable. If you want either of these tomorrow and would actually use it, email **[hello@riftmap.dev](mailto:hello@riftmap.dev)** — concrete demand is what unblocks the build. # Agent integration Source: https://docs.riftmap.dev/agents/overview How AI coding agents and CI pipelines call the Riftmap API: lookup, context, and impact endpoints, the freshness rule for stale data, the confidence floor applied to blast-radius traversals, pagination, and auth. 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`: ```http theme={null} 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`. ```http theme={null} 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. * 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](#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` 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](/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](/api-reference/introduction). ## Next: code samples The most common four flows — lookup, context, impact, subgraph — in curl, Python, and TypeScript: [Examples](/agents/examples). # Create Api Key Source: https://docs.riftmap.dev/api-reference/api-keys/create-api-key /openapi.json post /api/v1/workspaces/{workspace_id}/api-keys Create a named API key for the workspace and return its plaintext value exactly once at creation — store it now, it is never shown again. Owner or Admin only. # List Api Keys Source: https://docs.riftmap.dev/api-reference/api-keys/list-api-keys /openapi.json get /api/v1/workspaces/{workspace_id}/api-keys List all API keys for the workspace with their name, prefix, creation and last-used times, and revocation status. Owner or Admin only; the raw key is never shown. # Revoke Api Key Source: https://docs.riftmap.dev/api-reference/api-keys/revoke-api-key /openapi.json delete /api/v1/workspaces/{workspace_id}/api-keys/{key_id} Revoke a workspace API key by ID, setting its revoked timestamp so it can no longer authenticate. Owner or Admin only; returns 409 if the key was already revoked. # Get a single artifact by ID, with consumer count and orphan flag. Source: https://docs.riftmap.dev/api-reference/artifacts/get-a-single-artifact-by-id-with-consumer-count-and-orphan-flag /openapi.json get /api/v1/artifacts/{artifact_id} Fetch an artifact by ID in the caller's workspace, with consumer_count and is_orphan from the latest scan. Requires the Pro artifact dashboard; 404 if not found. # List all versions of this artifact seen across the org, with consumer counts. Source: https://docs.riftmap.dev/api-reference/artifacts/list-all-versions-of-this-artifact-seen-across-the-org-with-consumer-counts /openapi.json get /api/v1/artifacts/{artifact_id}/versions List every version constraint of this artifact seen across the org in the latest scan, each with its state and consumer count, ordered by popularity. Pro feature. # List artifacts (Docker images, packages, modules) produced in a connected org. Source: https://docs.riftmap.dev/api-reference/artifacts/list-artifacts-docker-images-packages-modules-produced-in-a-connected-org /openapi.json get /api/v1/connected-orgs/{connected_org_id}/artifacts List all known artifacts in a connected org, including orphans. Each response row carries ``consumer_count`` + ``is_orphan``. Orphans are artifacts the org produces but nothing in the org consumes — valuable dead-weight signal, not noise. **Upstream aliases are excluded by default** (issue #258). A repo that forks an upstream project and keeps its package identity registers as the producer of the upstream coordinate — a forked ``go.mod`` still says ``module go.opentelemetry.io/otel`` — so listing every row meant listing other people's packages: 15,741 production rows against 4,477 the orgs actually publish. Every row carries ``is_first_party``; pass ``include_upstream_aliases=true`` to get them all back. An upstream-alias artifact is exactly one with ``is_first_party: false``. A fork that rewrote its coordinate into its own namespace (``github.com/acme/go-i18n``) is first-party and is always listed. Paginated via ``limit`` / ``offset`` query params (default 100, max 500). ``X-Total-Count`` counts the rows matching the same filter as the page, so it is the first-party total by default and the all-rows total with ``include_upstream_aliases=true``. ``X-Upstream-Alias-Count`` always carries the excluded-row count, so a client can name what the default hides without a second request. # List repositories consuming this artifact, with pinned versions. Source: https://docs.riftmap.dev/api-reference/artifacts/list-repositories-consuming-this-artifact-with-pinned-versions /openapi.json get /api/v1/artifacts/{artifact_id}/consumers List repositories consuming this artifact from the latest scan, with each pinned version, on-latest vs lagging counts, and a version-state breakdown. Pro feature. # Accept Tos Source: https://docs.riftmap.dev/api-reference/auth/accept-tos /openapi.json post /api/v1/auth/accept-tos Record that the current user accepts the current Terms of Service. Called when a user accepts an updated ToS via the in-app banner or the /accept-terms blocking page. Updates tos_accepted_at and tos_version on the user record. Returns the accepted version and timestamp so the frontend can update state immediately without a full /auth/me refetch. # Cancel Account Deletion Source: https://docs.riftmap.dev/api-reference/auth/cancel-account-deletion /openapi.json post /api/v1/auth/account/cancel-deletion Cancel a pending account deletion during the 30-day grace period. Requires re-authentication — all sessions are revoked when deletion is scheduled, so the user must log in again. A valid session JWT is proof of re-authentication. # Change Password Source: https://docs.riftmap.dev/api-reference/auth/change-password /openapi.json post /api/v1/auth/password/change Change the current user's password after verifying the old one, bump the token version to invalidate other JWTs, revoke all other sessions, and re-issue this cookie. # Confirm Password Reset Source: https://docs.riftmap.dev/api-reference/auth/confirm-password-reset /openapi.json post /api/v1/auth/password/reset/confirm Verify a single-use password reset token, set the new password, bump the token version, auto-verify the email, and revoke all sessions. Returns 400 on a stale link. # Delete Account Source: https://docs.riftmap.dev/api-reference/auth/delete-account /openapi.json post /api/v1/auth/account/delete Schedule account deletion with a 30-day GDPR grace period. Instead of immediately hard-deleting, this sets deletion_scheduled_at = now()+30 days, revokes all active sessions (forces re-authentication), and returns 202. A Celery Beat task runs daily and performs the actual hard-delete once the grace period expires. Users can cancel by re-authenticating and calling POST /auth/account/cancel-deletion. Cascade behaviour (applied at hard-delete time): - Workspaces where user is the sole member are deleted entirely (including Stripe customer). - Workspaces where user is the sole owner but has other members → 409 (transfer first). - Workspaces where there are other owners → user's membership removed; workspace survives. # Get Me Source: https://docs.riftmap.dev/api-reference/auth/get-me /openapi.json get /api/v1/auth/me Return the authenticated user with their workspaces, linked OAuth providers, and role in the active workspace. Requires session auth; rejects API-key auth with 403. # List Providers Source: https://docs.riftmap.dev/api-reference/auth/list-providers /openapi.json get /api/v1/auth/providers Return the names of OAuth providers currently enabled on the server, such as GitHub and GitLab. Unauthenticated; the frontend uses it to render login buttons. # Login Source: https://docs.riftmap.dev/api-reference/auth/login /openapi.json post /api/v1/auth/login Authenticate a user by email and password, then set httponly access and refresh cookies. Rate-limited per email; returns the current user, workspaces, and role. # Logout Source: https://docs.riftmap.dev/api-reference/auth/logout /openapi.json post /api/v1/auth/logout Log the current user out by revoking the session tied to the access cookie and clearing the auth cookies. Idempotent and safe to call even without a valid cookie. # Oauth Callback Source: https://docs.riftmap.dev/api-reference/auth/oauth-callback /openapi.json get /api/v1/auth/oauth/{provider}/callback Handle the OAuth provider callback: validate the state, exchange the code for tokens, require a verified email, find or create the user, then set session cookies. # Oauth Start Source: https://docs.riftmap.dev/api-reference/auth/oauth-start /openapi.json get /api/v1/auth/oauth/{provider}/start Begin the OAuth login flow: generate a CSRF state, cache it in Redis with the sanitized redirect target, and redirect the browser to the provider authorize endpoint. # Refresh Token Source: https://docs.riftmap.dev/api-reference/auth/refresh-token /openapi.json post /api/v1/auth/refresh Refresh the access token using the refresh cookie. Rotates the refresh token. Implements refresh-token reuse detection (SEC-20260420-006). Each session row carries ``used_at`` (set on rotation) and ``replaced_by_id`` (forward chain link). If a client presents a token whose row has ``used_at`` set, the token is being replayed — either by an attacker who stole the cookie before the legitimate client rotated it, or by a buggy client retrying the same token. Either way we burn the entire rotation family so a stolen cookie is worth at most one rotation cycle and the theft is loud. # Register Source: https://docs.riftmap.dev/api-reference/auth/register /openapi.json post /api/v1/auth/register Create a new user account with the given email and password, provision their first workspace, owner membership, and default API key, then send a verification email. # Request Password Reset Source: https://docs.riftmap.dev/api-reference/auth/request-password-reset /openapi.json post /api/v1/auth/password/reset/request Email a single-use password reset link to the given address when an account exists. Always returns 200 without revealing whether the email is registered. Capped. # Resend Verification Email Source: https://docs.riftmap.dev/api-reference/auth/resend-verification-email /openapi.json post /api/v1/auth/email/verify/resend Resend the email-verification link to the logged-in user's address. Requires session auth; no-ops if already verified, and returns 503 if the mail service is down. # Set Password Source: https://docs.riftmap.dev/api-reference/auth/set-password /openapi.json post /api/v1/auth/password/set Set an initial password for an OAuth-only account that has none yet. Requires session auth and fails with 400 if a password already exists; use change-password. # Update Me Source: https://docs.riftmap.dev/api-reference/auth/update-me /openapi.json patch /api/v1/auth/me Update the current user's full name, email, or onboarding flag. Changing email needs the current password and forces re-verification. Session auth only, no API keys. # Verify Email Source: https://docs.riftmap.dev/api-reference/auth/verify-email /openapi.json post /api/v1/auth/email/verify Consume a signed, time-limited email-verification token and mark the account's email as verified. Unauthenticated; returns 400 when the token is invalid or expired. # Add Seats Source: https://docs.riftmap.dev/api-reference/billing/add-seats /openapi.json post /api/v1/workspaces/{workspace_id}/billing/seats Increase the seat add-on quantity on the workspace's Stripe subscription with prorated billing, updating extra_seats and logging an audit event. Owner-only. # Attach Payment Method Source: https://docs.riftmap.dev/api-reference/billing/attach-payment-method /openapi.json post /api/v1/workspaces/{workspace_id}/billing/payment-methods Attach a confirmed PaymentMethod to the customer and optionally set as default. Called after Stripe Elements ``confirmSetup`` resolves on the frontend. We attach synchronously (rather than waiting for the ``payment_method.attached`` webhook) so the UI can render the new card immediately after the modal closes. # Cancel Subscription Source: https://docs.riftmap.dev/api-reference/billing/cancel-subscription /openapi.json post /api/v1/workspaces/{workspace_id}/billing/cancel Schedule subscription cancellation at period end and record exit-survey row. Sets ``cancel_at_period_end=true`` on the Stripe subscription. Inserts a row in ``subscription_cancellations`` capturing the optional reason + free-text. The row is immutable — resuming the subscription does NOT delete it; it's an event log, not state. # Change Plan Source: https://docs.riftmap.dev/api-reference/billing/change-plan /openapi.json post /api/v1/workspaces/{workspace_id}/billing/change-plan Switch between Pro and Business plans on an existing subscription. Replaces the base plan subscription item in Stripe and removes any seat add-ons (extra_seats resets to 0 — re-add after switching if needed). Pre-flight checks (409 with structured body): - ``org_disconnect_required``: target plan allows fewer org connections than are currently connected. Disconnect excess orgs first, then retry. - ``member_eviction_required``: target plan's included seats are fewer than the current member count. Supply ``member_ids_to_evict`` (exactly the overflow count) to proceed atomically. # Create Checkout Session Source: https://docs.riftmap.dev/api-reference/billing/create-checkout-session /openapi.json post /api/v1/workspaces/{workspace_id}/billing/checkout Create a Stripe Checkout session to upgrade the workspace to the 'pro' or 'business' plan. Owner only; returns 409 if a live subscription already exists. # Create Portal Session Source: https://docs.riftmap.dev/api-reference/billing/create-portal-session /openapi.json post /api/v1/workspaces/{workspace_id}/billing/portal Create a Stripe Customer Portal session for managing the workspace's subscription and payment methods. Owner only; returns 400 if no Stripe customer exists yet. # Create Setup Intent Source: https://docs.riftmap.dev/api-reference/billing/create-setup-intent /openapi.json post /api/v1/workspaces/{workspace_id}/billing/payment-methods/setup-intent Create a Stripe SetupIntent for in-app card collection via Stripe Elements. Returns the SetupIntent ``client_secret`` plus the publishable key bound to the backend's Stripe environment, so the frontend never needs a ``VITE_`` env var for the publishable key (and can't drift from the backend's mode). # Get Billing History Source: https://docs.riftmap.dev/api-reference/billing/get-billing-history /openapi.json get /api/v1/workspaces/{workspace_id}/billing/history Return a unified, date-desc list of invoices and credit notes for the workspace. Returns up to 50 of each kind per page. Each source (invoices, credit notes) paginates independently via Stripe's native ``starting_after`` cursor; callers thread the returned ``next_invoice_cursor`` / ``next_credit_note_cursor`` back as query params to fetch the next page. ``has_more`` is true when either cursor is non-null. Proration line items are embedded in their parent invoice description — they are NOT emitted as standalone events. # Get Billing Status Source: https://docs.riftmap.dev/api-reference/billing/get-billing-status /openapi.json get /api/v1/workspaces/{workspace_id}/billing Return the workspace's billing status — plan, subscription status, seat count and limit, trial and billing-period end, and over-seat/org/repo flags. Owner only. # Get Billing Usage Source: https://docs.riftmap.dev/api-reference/billing/get-billing-usage /openapi.json get /api/v1/workspaces/{workspace_id}/billing/usage Return detailed resource usage vs plan limits for the workspace: repo, seat, and org-connection counts, feature flags, and subscription status. Owner only. # Get Payment Info Source: https://docs.riftmap.dev/api-reference/billing/get-payment-info /openapi.json get /api/v1/workspaces/{workspace_id}/billing/payment-info Return the workspace's default card payment method and recent invoices from Stripe. Owner role only; responds 400 when the workspace has no Stripe customer yet. # Get Plan Catalog Source: https://docs.riftmap.dev/api-reference/billing/get-plan-catalog /openapi.json get /api/v1/billing/plans Return available plan pricing and limits from Stripe (cached 1 hour). Accessible to any authenticated user so it works during workspace creation. Falls back to hardcoded defaults when Stripe is not configured or unreachable. # Preview Change Plan Source: https://docs.riftmap.dev/api-reference/billing/preview-change-plan /openapi.json get /api/v1/workspaces/{workspace_id}/billing/change-plan/preview Preview the proration and recurring-amount impact of switching plans. Read-only: does not mutate Stripe state or workspace state. Warnings mirror the 409 conflicts that ``change_plan`` would raise (org overflow, member overflow) so the frontend can surface them before the user commits. # Preview pending charges that will bill on the final invoice if not waived Source: https://docs.riftmap.dev/api-reference/billing/preview-pending-charges-that-will-bill-on-the-final-invoice-if-not-waived /openapi.json get /api/v1/workspaces/{workspace_id}/billing/cancel/preview Return the queued (uninvoiced) Stripe invoice items for this workspace's customer. Used by ``CancelPanel`` to surface orphan prorations BEFORE the user confirms cancellation — a queued $134 charge from a prior plan-switch will still flush onto the final cycle invoice unless explicitly waived via ``cancel?waive_pending_charges=true``. Implementation note: uses ``InvoiceItem.list(pending=True)`` directly rather than ``Invoice.create_preview`` because the latter conflates renewal recurring line items with prorations and requires brittle line-flag classification on Stripe API ``2025-03-31.basil`` (see comment on ``preview_change_plan``). # Preview Seat Change Source: https://docs.riftmap.dev/api-reference/billing/preview-seat-change /openapi.json get /api/v1/workspaces/{workspace_id}/billing/seats/preview Preview the proration and recurring-amount impact of adding or removing seat add-ons. ``seat_delta`` is signed — positive = adding, negative = removing. Mirrors the ``change-plan/preview`` contract so ``AddSeatsPanel`` / ``RemoveSeatsPanel`` can render the same "What you'll pay" breakdown before the user confirms. Read-only: does not mutate Stripe or workspace state. # Remove Seats Source: https://docs.riftmap.dev/api-reference/billing/remove-seats /openapi.json delete /api/v1/workspaces/{workspace_id}/billing/seats Remove extra seat add-ons from the existing subscription. Reduces the seat add-on quantity by ``seats_to_remove``. Cannot go below zero extra seats. If the quantity reaches zero the add-on line item is removed from the subscription entirely. When the reduction would put the workspace over the new seat limit, the caller must supply ``member_ids_to_evict`` — exactly as many IDs as the overflow count. If they are not supplied, the endpoint returns 409 with ``type="member_eviction_required"`` and the full list of evictable members (non-owners, sorted newest-first) so the frontend can render a picker. The Stripe item modification and the member removals are committed together so the workspace is never left in a partially-updated state. # Resume Subscription Source: https://docs.riftmap.dev/api-reference/billing/resume-subscription /openapi.json post /api/v1/workspaces/{workspace_id}/billing/resume Clear ``cancel_at_period_end`` on a subscription pending cancellation. The webhook handler for ``customer.subscription.updated`` will clear ``workspace.cancel_at`` when Stripe echoes the change; we also clear it optimistically here so the UI banner disappears immediately. # Stripe Webhook Source: https://docs.riftmap.dev/api-reference/billing/stripe-webhook /openapi.json post /api/v1/webhooks/stripe Verify the Stripe signature on an incoming webhook, then process the event idempotently: unknown types are skipped and duplicates deduped via stripe_events table. # Create Connected Org Source: https://docs.riftmap.dev/api-reference/connected-orgs/create-connected-org /openapi.json post /api/v1/connected-orgs Add a new connected org and automatically trigger a full scan. Owner/Admin only (session auth): registering an org submits a platform credential, expands scan scope, and consumes the plan repo cap — a mutation the workspace role model reserves for Admin/Owner. API-key auth is owner-equivalent and bypasses the role check. Accepts two auth modes: - PAT mode: body contains url + access_token - OAuth mode: body contains oauth_org_login (uses the user's linked identity token) A full scan is automatically queued after the org is created. The response includes ``initial_scan_id`` which can be used to poll scan progress via GET /api/v1/scans/{scan_id}. # Delete Connected Org Source: https://docs.riftmap.dev/api-reference/connected-orgs/delete-connected-org /openapi.json delete /api/v1/connected-orgs/{connected_org_id} Delete a connected org. Cascade-deletes all associated repositories, scans, and artifacts, and removes the encrypted token from the database. Note: platform-side token revocation is NOT performed automatically. Users should revoke the GitHub/GitLab PAT or OAuth token manually after disconnecting (see GitHub token settings or GitLab token settings). # Get Connected Org Source: https://docs.riftmap.dev/api-reference/connected-orgs/get-connected-org /openapi.json get /api/v1/connected-orgs/{connected_org_id} Fetch a connected org by its ID, scoped to the authenticated workspace; any member may read it. Returns 404 when no org with that ID exists in the workspace. # Get Connected Org Stats Source: https://docs.riftmap.dev/api-reference/connected-orgs/get-connected-org-stats /openapi.json get /api/v1/connected-orgs/{connected_org_id}/stats Aggregate statistics for one connected org: repository, declaration and deduped dependency-edge counts, artifact orphan/consumption breakdowns, and the declaration-outcome breakdown naming why each parsed dependency did or did not become a graph edge. Dependency figures are scoped per repository to its own current scan, not to a single org-wide one. # List Connected Orgs Source: https://docs.riftmap.dev/api-reference/connected-orgs/list-connected-orgs /openapi.json get /api/v1/connected-orgs List every connected org registered in the authenticated workspace, ordered alphabetically by name; any workspace member may read it. Returns each org record. # Ranked findings feed: high-fan-in repos with low bus factor (spec §8). Shares and counts are computed over a trailing window (default 365 days), excluding merge commits, with bot identities stripped; each item carries the `window` (start/end) and `computed_at` it was computed for. Source: https://docs.riftmap.dev/api-reference/connected-orgs/ranked-findings-feed:-high-fan-in-repos-with-low-bus-factor-spec-§8-shares-and-counts-are-computed-over-a-trailing-window-default-365-days-excluding-merge-commits-with-bot-identities-stripped;-each-item-carries-the-`window`-startend-and-`computed_at`-it-was-computed-for /openapi.json get /api/v1/connected-orgs/{connected_org_id}/ownership-risk Return the ranked concentration-risk feed for a connected org. **Default mode** (no overrides): returns repos where the stored ``is_concentration_risk`` is true (fan-in >= org P75 with floor 5, AND ``0 < bus_factor <= bus_factor_ceiling`` — defaults 5 and 2 per spec §2). **Override mode** (either ``min_dependents`` or ``max_bus_factor`` given): ignores the stored flag and uses the inline predicate ``bus_factor > 0 AND bus_factor <= max_bus_factor AND dependents_count >= min_dependents`` (each clause is no-op when its param is omitted). ``bus_factor = 0`` (no human commits) is always excluded. Ordered ``risk_score DESC, top_author_share DESC, repository_id ASC``. Paginated via ``limit`` / ``offset``; ``X-Total-Count`` carries the full matching set. Returns an empty list when no signal rows exist for the org's latest scan (``OWNERSHIP_SIGNAL_ENABLED=false`` or pre-backfill). Raw emails are never returned (PII). Shares and counts are windowed: each item carries the ``window`` (``start``/``end``, a trailing ``window_days`` period — default 365) and ``computed_at`` (scan-finalisation time) the figures were computed over, so a ``top_author_share`` of 0.82 reads as "last 12 months", not all-time. This matches the per-repo ``/repositories/{id}/ownership`` window. # Update Connected Org Source: https://docs.riftmap.dev/api-reference/connected-orgs/update-connected-org /openapi.json put /api/v1/connected-orgs/{connected_org_id} Update mutable connected org settings. Editable fields: `name`, `heuristic_patterns`, and `access_token` (PAT rotation). Immutable: `platform`, `platform_id`, `url` — disconnect and re-register to change. Rotating the token also clears the auth-failure auto-pause, resuming scheduled rescans immediately. Token rotation is rejected (409) for OAuth-registered orgs because the stored token is a copy of the user's linked identity. Rotating here would silently desync the org from the identity. # Get the dependency graph (full org or subgraph anchored at a repo). Source: https://docs.riftmap.dev/api-reference/graph/get-the-dependency-graph-full-org-or-subgraph-anchored-at-a-repo /openapi.json get /api/v1/connected-orgs/{connected_org_id}/graph Return the dependency graph for a connected org. Without ``root``: full graph for the org. With ``root=``: subgraph anchored at that repo, including up to ``depth`` hops in both directions (upstream + downstream). Designed for AI coding agents that want a focused neighbourhood instead of the whole org. Nodes are repositories; edges are resolved dependencies from the most recent completed scan. Format is G6-compatible. **Confidence differs between the two modes, deliberately.** With ``root``, ``min_confidence`` (default 0.4) governs both the traversal and the edges returned, and the response echoes it as ``applied_min_confidence``. Without ``root``, no floor is applied — the full-org graph returns every ``manifest`` edge so clients can filter for themselves, and ``applied_min_confidence`` is ``null``. That asymmetry is why the org and workspace dependency counters match this endpoint exactly: browsing is a different question from asking what breaks. # Transitive downstream blast radius (repo-level BFS). NOT file-path scoped — accepts only `max_depth` + `min_confidence`. Source: https://docs.riftmap.dev/api-reference/impact/transitive-downstream-blast-radius-repo-level-bfs-not-file-path-scoped-—-accepts-only-`max_depth`-+-`min_confidence` /openapi.json get /api/v1/repositories/{repo_id}/impact Get the full downstream impact of changing this repository. Returns all repositories that depend on this one, directly or transitively, up to ``max_depth`` hops away. Use this before publishing a breaking change. **Repo-level scope, not file-scoped.** This endpoint computes a BFS over repo-to-repo dependency edges; it does **not** trace specific files, jobs, or symbols within the source repo. There is no ``path``, ``paths``, ``file``, or ``job`` query parameter — agents asking "who consumes file X in repo Y" should call ``/repositories/{id}/dependents`` and then grep the consumer repos directly, since per-file edges aren't stored in the graph. GitHub Actions are the exception: every ``/dependents`` row carries the full ``uses:`` path in ``raw_reference`` (e.g. ``grafana/shared-workflows/actions/send-slack-message``), so "who uses action or reusable workflow X" is answered by filtering those rows, no grep needed. Unknown query parameters are silently ignored by FastAPI, which can mask hallucinated filter names — if a filter doesn't appear in this signature, it's not honoured. For artifact-level consumers (who pulls Docker image / Helm chart / Terraform module X and at what version), use ``/artifacts/{id}/consumers`` instead — that endpoint *is* version-aware. **Confidence.** Traversal follows only edges at or above ``min_confidence``, which defaults to 0.4: every reference a machine could act on, excluding only the tier that means a human reads it (prose, templates, generated blobs). The floor that was applied is echoed as ``applied_min_confidence``, the repos it removed are counted in ``excluded_by_confidence`` so a truncated answer is never silent, and each affected repo carries the confidence of the weakest edge on the strongest chain that reached it — so a stricter blast radius is a filter over this response, not a second request. # API reference Source: https://docs.riftmap.dev/api-reference/introduction Riftmap's REST API reference: authenticated endpoints for cross-repository dependencies, dependents, and change-impact blast radius, called by AI agents and CI. 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_` and can be passed as either header: ```bash theme={null} # 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](/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. | 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 (with `dependent_repositories_total`) + artifacts. | | `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.** Confidence-floored (default `0.4`); echoes `applied_min_confidence` and `excluded_by_confidence`. | | `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 typical agent call pattern is **lookup → context → impact**. See [Agent integration](/agents/overview) 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. GitHub Actions are the exception: each dependents row carries the full `uses:` path in `raw_reference` (e.g. `grafana/shared-workflows/actions/send-slack-message`), so "who uses action X" is a filter over those rows. 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. * **Confidence** — Traversal endpoints (`/impact`, and `/connected-orgs/{id}/graph?root=`) apply a `min_confidence` floor, default **0.4**, which excludes only references a human reads rather than a machine acts on. Omit the parameter to take that default. `/impact` echoes `applied_min_confidence` and `excluded_by_confidence`, and each affected repo carries its own `confidence` — filter that field client‑side for a stricter answer rather than re‑requesting. See [The confidence rule](/agents/overview#the-confidence-rule). * **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. ```bash theme={null} curl -s https://app.riftmap.dev/openapi.json | jq '.paths | keys' ``` ## Where to start The lookup → context → impact pattern, the freshness rule, and the full surface in one page. The four core flows in curl, Python (httpx), and TypeScript (fetch). Create a workspace API key and learn the header conventions. 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. # Accept Invitation Source: https://docs.riftmap.dev/api-reference/invitations/accept-invitation /openapi.json post /api/v1/invitations/{token}/accept Accept an invitation by token, joining the workspace with the invited role. Requires a logged-in user with a verified email address; an email-kind invitation must additionally be redeemed by the address it was sent to. Rate-limited, single-use, seat-capped. # Create Invitation Source: https://docs.riftmap.dev/api-reference/invitations/create-invitation /openapi.json post /api/v1/workspaces/{workspace_id}/invitations Create an email or copyable-link invitation to a workspace, returning its one-time token. Owner or Admin with a verified email only; email invites are mailed out. Editor-role invites are seat-checked here, so an invitation that could never be accepted is refused at send time rather than failing for the invitee. # List Invitations Source: https://docs.riftmap.dev/api-reference/invitations/list-invitations /openapi.json get /api/v1/workspaces/{workspace_id}/invitations List a workspace's active invitations — pending, not revoked, not fully used — with their role, kind, use count, and expiry. Owner or Admin only; no tokens. # Preview Invitation Source: https://docs.riftmap.dev/api-reference/invitations/preview-invitation /openapi.json get /api/v1/invitations/{token} Preview an invitation by its raw token before accepting — returns the workspace name, inviter, role, and a masked hint of the invited address for email-kind invites. Public, no auth; 404 if the token is invalid or expired. # Revoke Invitation Source: https://docs.riftmap.dev/api-reference/invitations/revoke-invitation /openapi.json delete /api/v1/workspaces/{workspace_id}/invitations/{invitation_id} Revoke a workspace invitation by ID so its link or email can no longer be accepted. Owner or Admin only; returns 204, or 404 if the invitation is unknown. Revoking frees any editor seat the pending invitation was reserving. # Leave Workspace Source: https://docs.riftmap.dev/api-reference/memberships/leave-workspace /openapi.json post /api/v1/workspaces/{workspace_id}/leave Remove your own membership from a workspace, given a browser session. Returns 204. The last Owner cannot leave until ownership is transferred to another member. # List Members Source: https://docs.riftmap.dev/api-reference/memberships/list-members /openapi.json get /api/v1/workspaces/{workspace_id}/members List all members of a workspace. Any member can access. Paginated via ``limit`` / ``offset`` query params (default 100, max 500). ``X-Total-Count`` response header carries the unfiltered row count. # Remove Member Source: https://docs.riftmap.dev/api-reference/memberships/remove-member /openapi.json delete /api/v1/workspaces/{workspace_id}/members/{user_id} Delete a member's workspace membership by user ID. Owner or Admin only. Cannot remove the last Owner, or yourself — use the leave endpoint instead. Returns 204. # Update Member Role Source: https://docs.riftmap.dev/api-reference/memberships/update-member-role /openapi.json patch /api/v1/workspaces/{workspace_id}/members/{user_id} Change a workspace member's role. Owner or Admin only; the last Owner cannot be demoted, Admins cannot promote to Owner, and promoting a viewer checks seat limits. # Health Source: https://docs.riftmap.dev/api-reference/meta/health /openapi.json get /health Liveness probe — always returns 200 if the process is up. Suitable for Railway / Docker HEALTHCHECK and load-balancer pings. Does not perform any subsystem checks so it never leaks internal hostnames, DSN fragments, or exception details. Use /health/detailed (admin-gated) for rich subsystem diagnostics, or /ready (public) for a strict ready-to-serve check. # Health Detailed Source: https://docs.riftmap.dev/api-reference/meta/health-detailed /openapi.json get /health/detailed Detailed subsystem health — requires admin API key (X-API-Key header). Verifies database, Redis broker, Redis state, Celery workers, Redis memory pressure, and clone-directory disk space. Rich exception details are written to the application log at WARN/ERROR level and are NOT included in the HTTP response body — the body only carries "ok", "warning: ", or "degraded" per subsystem. # Ready Source: https://docs.riftmap.dev/api-reference/meta/ready /openapi.json get /ready Readiness probe — public, unauthenticated. Returns 200 only when this API process can reach its own datastores: Postgres and both Redis DBs. Returns 503 with the failing subsystem names ({"status": "not_ready", "failed": [...]}). Subsystem-level *detail* (hostnames, exceptions) is logged via structlog and never returned in the body. Deliberately does **not** probe Celery workers. That leg was a Celery `inspect().ping()` — a broadcast RPC over the broker with a 2.5 s budget — and it flapped: on 2026-08-20 it produced ten 503s in 19 minutes, interleaved with 200s, while worker CPU sat at 0.2%. Worker liveness is covered twice over by signals that ask the workers directly: each worker service exposes its own /ready sidecar (broker reachability plus a 90 s Celery heartbeat, src/workers/healthcheck.py), and the `synthetic-probe` beat task runs every minute behind a Sentry cron monitor. `/health/detailed` still reports worker status for on-demand diagnosis. Intended for Betterstack / external monitoring. **Do not** wire this as Railway's container healthcheck — a 30 s Redis blip would restart the API. See docs/deployment/external-monitoring.md. # Bus-factor signal + capped human contributors for one repo (spec §8). Source: https://docs.riftmap.dev/api-reference/repositories/bus-factor-signal-+-capped-human-contributors-for-one-repo-spec-§8 /openapi.json get /api/v1/repositories/{repo_id}/ownership Return the ownership signal for one repo, scoped to the latest scan of its org. Contributors are humans only, ordered by ``commit_count DESC``. Returns 200 with zeros / null / empty arrays when no signal exists yet (the feature flag ``OWNERSHIP_SIGNAL_ENABLED`` is off, or the scan ran before backfill) — the endpoint stays callable without agents needing a "flag-off" branch. Paginated via ``limit`` / ``offset``; ``X-Total-Count`` carries the full human contributor count. Raw emails are never returned (PII contract). # Get a single repository by ID, including freshness fields. Source: https://docs.riftmap.dev/api-reference/repositories/get-a-single-repository-by-id-including-freshness-fields /openapi.json get /api/v1/repositories/{repo_id} Fetch one repository by ID, scoped to the authenticated workspace via its connected org. Returns the full row including freshness fields; raises 404 if no match. # List repositories discovered in a connected org. Source: https://docs.riftmap.dev/api-reference/repositories/list-repositories-discovered-in-a-connected-org /openapi.json get /api/v1/connected-orgs/{connected_org_id}/repositories List all repositories discovered in a connected org. Paginated via ``limit`` / ``offset`` query params (default 100, max 500). ``X-Total-Count`` response header carries the unfiltered row count. # List the dependency declarations this repository makes. Source: https://docs.riftmap.dev/api-reference/repositories/list-the-dependency-declarations-this-repository-makes /openapi.json get /api/v1/repositories/{repo_id}/dependencies Get all dependency declarations from this repo's latest scan. Paginated via ``limit`` / ``offset`` (default 100, max 500). ``X-Total-Count`` carries the post-dedup total so agents know whether to fetch additional pages. # List the repositories that directly depend on this repository. Source: https://docs.riftmap.dev/api-reference/repositories/list-the-repositories-that-directly-depend-on-this-repository /openapi.json get /api/v1/repositories/{repo_id}/dependents Get the declarations in other repositories that resolve to this repository, one row per declaration. Each row is one use: the consuming repository is ``target_repository_id`` / ``target_repository_name`` (count distinct values of it for the number of dependent repositories), and ``source_file`` / ``source_line`` locate the use in it. Rows are deduplicated at read time on declaration identity — consumer repository, dependency type, version constraint, source file, raw reference and source line — so a consumer that calls several GitHub Actions or reusable workflows of this repository, or the same one on several lines, appears once per use. Group by ``lower(raw_reference)`` to list consumers per action, workflow or package: for GitHub Actions it is the full ``uses:`` path, such as ``grafana/shared-workflows/actions/send-slack-message``. A row whose consumer was last scanned before v1.25.0 carries only the bare ``owner/repo`` there. Paginated via ``limit`` / ``offset`` (default 100, max 500). ``X-Total-Count`` carries the post-dedup total of these declarations, not of repositories. # Recommended first hydration call after `/lookup`: repo + capped deps + capped dependents + artifacts in one round-trip. Source: https://docs.riftmap.dev/api-reference/repositories/recommended-first-hydration-call-after-`lookup`:-repo-+-capped-deps-+-capped-dependents-+-artifacts-in-one-round-trip /openapi.json get /api/v1/repositories/{repo_id}/context Return the repo, capped direct dependents/dependencies, and artifacts in one call. **This is the recommended second call** for AI coding agents auditing a repo (after ``/repositories/lookup`` resolves the ID). One request collapses what would otherwise be three or four. The freshness fields on ``repository`` (``last_scanned_at``, ``last_activity_at``, ``last_commit_sha``, ``archived``) let the agent decide whether to trust the data or trigger a rescan. Direct dependents and dependencies are capped at 100 rows each; the ``dependencies_total`` and ``dependents_total`` fields carry the post-dedup count so the agent knows when to paginate via the dedicated ``/dependencies`` and ``/dependents`` endpoints. Both lists are declaration rows, so a repository used through several actions or packages takes several dependent rows: ``dependent_repositories_total`` is the number of distinct repositories behind ``dependents_total``. For transitive blast radius (multi-hop downstream), call ``/repositories/{id}/impact`` after this — it is deliberately *not* bundled here because not every agent flow needs it. # Resolve a clone URL or org/repo slug to a repository (pass exactly one of `url` or `full_path`). Source: https://docs.riftmap.dev/api-reference/repositories/resolve-a-clone-url-or-orgrepo-slug-to-a-repository-pass-exactly-one-of-`url`-or-`full_path` /openapi.json get /api/v1/repositories/lookup Resolve an agent-supplied identifier to a Riftmap repository row. Designed for AI coding agents and CI integrations: an agent in ``github.com/myorg/repo`` can ask Riftmap for the matching repository without enumerating the workspace. **Pass exactly one of ``url`` or ``full_path``** — passing both, neither, or any other parameter (e.g. ``clone_url=``, ``name=``, ``repo=``) returns 400. The parameter is named ``url`` (not ``clone_url``) even though it accepts what most platforms call a "clone URL". URL matching first attempts a normalised ``clone_url`` match, then falls back to the ``org/repo`` segment of the URL against ``full_path``. Returns 409 if more than one repo matches; 404 if none. # Cancel Scan Source: https://docs.riftmap.dev/api-reference/scans/cancel-scan /openapi.json post /api/v1/scans/{scan_id}/cancel Cancel a pending or running scan. Sets the scan status to 'cancelled' immediately. The Celery worker checks this flag at each repository boundary and stops gracefully. Stays member-permitted as an operational action (mirrors ``trigger_scan``'s note); only read-only viewers are excluded (repricing B3). # Get Scan Source: https://docs.riftmap.dev/api-reference/scans/get-scan /openapi.json get /api/v1/scans/{scan_id} Retrieve the current status and progress of a single scan by ID, scoped to the caller's workspace by its connected org. Returns 404 if no matching scan exists. # List Scans Source: https://docs.riftmap.dev/api-reference/scans/list-scans /openapi.json get /api/v1/connected-orgs/{connected_org_id}/scans List all scans for a connected org, newest first. Paginated via ``limit`` / ``offset`` query params (default 100, max 500). ``X-Total-Count`` response header carries the unfiltered row count. # Trigger Scan Source: https://docs.riftmap.dev/api-reference/scans/trigger-scan /openapi.json post /api/v1/connected-orgs/{connected_org_id}/scans Trigger a new scan for a connected org. Owner/Admin only (session auth): triggering a scan exercises the stored platform credential and consumes worker capacity — a mutation the workspace role model reserves for Admin/Owner. API-key auth is owner-equivalent and bypasses the role check. (Cancelling an in-flight scan stays member-permitted as an operational action.) Accepts an optional JSON body with ``scan_type``: ``"incremental"`` (default) skips repos unchanged since the last scan; ``"full"`` re-scans every repo. Creates a Scan record immediately (status=pending) and dispatches the scan to a Celery worker. Poll GET /scans/{scan_id} for progress. # Create Workspace Source: https://docs.riftmap.dev/api-reference/workspaces/create-workspace /openapi.json post /api/v1/workspaces Create a new workspace for the current user and make them Owner. Each user may own at most one free workspace. If they already own a free workspace, they must subscribe to a paid plan before creating another. # Create Workspace With Checkout Source: https://docs.riftmap.dev/api-reference/workspaces/create-workspace-with-checkout /openapi.json post /api/v1/workspaces/create-with-checkout Create a new workspace and immediately open a Stripe Checkout session for it. Used when the caller already owns a free workspace and wants to create an additional paid workspace. The workspace is provisioned with plan="free" first; the webhook handler upgrades it to the chosen plan once Stripe confirms payment. Requires: session auth, Stripe enabled. # Delete Workspace Source: https://docs.riftmap.dev/api-reference/workspaces/delete-workspace /openapi.json delete /api/v1/workspaces/{workspace_id} Permanently delete a workspace and everything it owns — connected orgs, scans, memberships, API keys, and invitations all cascade. Owner-only; returns 204. # Export Workspace Source: https://docs.riftmap.dev/api-reference/workspaces/export-workspace /openapi.json get /api/v1/workspaces/{workspace_id}/export GDPR right-to-portability export for a workspace. Returns a JSON file containing all workspace data. Secrets are redacted: access_token_encrypted is omitted from connected orgs, and key_hash is omitted from API keys (only the safe prefix is included). Rate limited to 1 export per workspace per hour. Requires Owner or Admin role. # Get Workspace Source: https://docs.riftmap.dev/api-reference/workspaces/get-workspace /openapi.json get /api/v1/workspaces/{workspace_id} Fetch a single workspace by ID, returning its name, slug, plan, and metadata. Scoped to the caller's own workspace — responds 404 if the ID is any other workspace. # Get Workspace Stats Source: https://docs.riftmap.dev/api-reference/workspaces/get-workspace-stats /openapi.json get /api/v1/workspaces/{workspace_id}/stats Aggregate statistics across every connected org in the workspace: repository and dependency counts, artifact orphan breakdowns, last scan summary, and the declaration-outcome breakdown. # List Oauth Orgs Source: https://docs.riftmap.dev/api-reference/workspaces/list-oauth-orgs /openapi.json get /api/v1/workspaces/{workspace_id}/oauth-orgs/{provider} List GitHub orgs or GitLab groups accessible via the user's linked OAuth identity. Used by the frontend org-picker so users can connect an org without pasting a PAT. Requires session auth — the token lives on the user's identity row, not the workspace. # List Workspaces Source: https://docs.riftmap.dev/api-reference/workspaces/list-workspaces /openapi.json get /api/v1/workspaces Return all workspaces the authenticated user is a member of. For API key auth: returns the single workspace the key belongs to (total always 1). Paginated via ``limit`` / ``offset`` query params (default 100, max 500). ``X-Total-Count`` response header carries the unfiltered row count. # Read the workspace's plan entitlements (any member) Source: https://docs.riftmap.dev/api-reference/workspaces/read-the-workspaces-plan-entitlements-any-member /openapi.json get /api/v1/workspaces/{workspace_id}/entitlements Return the plan entitlements for a workspace: its plan key, per-feature flags (`scheduled_scans`, `continuous_scans`, `api_production`, `artifact_dashboard`, `multi_org`), billable seat usage, the seat ceiling (`null` means unlimited), and whether plan limits are enforced on this deployment at all. Readable by every member including viewers, which is the point — the equivalent billing routes are owner-only, so non-owners had no way to learn what their plan allows and clients defaulted to allowing everything. Carries no billing identifiers, invoice data, or billing contact. Feature flags are *effective*: when `billing_enforced` is false every flag is true, matching what the API will actually serve. Deliberately cheap: one COUNT for seat usage, with plan and features read off the workspace row the auth dependency has already loaded. Every member hits this on page load, so resist adding live usage counts here. # Regenerate Api Key Source: https://docs.riftmap.dev/api-reference/workspaces/regenerate-api-key /openapi.json post /api/v1/workspaces/{workspace_id}/api-key/regenerate [Deprecated] Rotate API key. Use POST /workspaces/{id}/api-keys instead. Owner/Admin only: this mints an owner-equivalent credential (API keys bypass role/email-verification checks), so a plain member must not be able to call it. # Transfer Ownership Source: https://docs.riftmap.dev/api-reference/workspaces/transfer-ownership /openapi.json post /api/v1/workspaces/{workspace_id}/transfer Transfer ownership to another member. Caller is demoted to Admin; target is promoted to Owner. Requires session auth — API keys cannot transfer ownership (no user identity to demote). # Update Workspace Source: https://docs.riftmap.dev/api-reference/workspaces/update-workspace /openapi.json put /api/v1/workspaces/{workspace_id} Update a workspace's display name, optionally regenerating its slug from the new name when regenerate_slug is set. Owner or Admin only; returns the updated record. # Authentication Source: https://docs.riftmap.dev/authentication Authenticate to the Riftmap API with workspace API keys via the X-API-Key or Authorization: Bearer header, covering key creation, rate limits, and revocation. The Riftmap API uses **workspace API keys** for all programmatic access. Keys are scoped to a single workspace, bypass role checks (they're owner‑equivalent within their workspace), and never require a `workspace_id` parameter. ## Create a key In the app: 1. Pick the workspace from the user menu. 2. Navigate to **Settings → API keys**. 3. Click **Create new key**, give it a label (e.g. `claude-code-laptop`, `ci-staging`), and copy the raw key. The plaintext key is shown **once** at creation time. After that, only the SHA‑256 hash and a short prefix (`rfm_live_xxxx…`) are stored. If you lose it, revoke the old key and mint a new one. A workspace can have multiple keys — best practice is one per environment or per agent, so revocation is granular. ## Header conventions Riftmap accepts the API key on either of two headers. Use whichever is more natural for your client. ### Canonical: `X-API-Key` ```bash theme={null} curl "https://api.riftmap.dev/api/v1/repositories/lookup?url=https://github.com/myorg/repo" \ -H "X-API-Key: rfm_live_xxx" ``` ### Convenience alias: `Authorization: Bearer` The `Authorization` header is checked **only** when the value starts with `rfm_` — this avoids collision with user JWTs that share the same header in browser sessions. ```bash theme={null} curl "https://api.riftmap.dev/api/v1/repositories/lookup?url=https://github.com/myorg/repo" \ -H "Authorization: Bearer rfm_live_xxx" ``` ### Priority order Within a single request the server checks, in order: `X-API-Key` → `Authorization: Bearer rfm_*` → session cookie → 401. Mixing two methods is fine; the first to match wins. ### 401 body ```json theme={null} { "detail": "Authentication required. Provide X-API-Key, Authorization: Bearer , or log in." } ``` ## Cross‑workspace isolation Every authenticated response is scoped to the workspace that owns the API key. Attempts to reach another workspace's resources return **404**, not 403 — we deliberately don't leak whether the resource exists. ## Rate limits | Surface | Limit | Notes | | ------------------------------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------- | | Read endpoints | Generous (no per-request cap today) | `GET /repositories`, `GET /context`, `GET /impact`, `GET /graph`, etc. Subject to change as usage grows. | | Authenticated mutations (`POST` / `PUT` / `PATCH` / `DELETE`) | 60 / minute per key | Keyed by API key prefix. Configurable via `RATELIMIT_AUTHENTICATED_MUTATIONS`. | On limit exceeded, the response is `429` with `{ "detail": "...", "retry_after": N }` and a `Retry-After: N` header. Both `Retry-After` and `X-Request-ID` are exposed via CORS, so browser `fetch()` can read them directly. ## Revoking a key `DELETE /workspaces/{id}/api-keys/{key_id}` — or click the trash icon in **Settings → API keys**. Revocation is immediate; subsequent requests with the revoked key return 401. ## Storing keys safely * Do **not** check API keys into git. Treat them like any other production secret. * Do **not** ship them in client‑side bundles — workspace keys are owner‑equivalent within their workspace and must stay server‑side. * For local development against the production API, use a `.env.local` file (or your shell's secret manager) and reference the key as `RIFTMAP_API_KEY`. # Week of May 15, 2026 Source: https://docs.riftmap.dev/changelog/2026-05-15 Riftmap's May 15, 2026 release: auto-scan on org connect, new agent-friendly API endpoints for repo lookup and context, subgraph filtering, and pagination. ## New features **Auto-scan when connecting an org.** Connecting a new GitHub or GitLab org now kicks off a full scan automatically. The response includes an `initial_scan_id` you can poll for progress, so the "Connect & scan" flow finally does both in one click. See the [quickstart](/quickstart). **Look up a repository by URL.** A new `GET /repositories/lookup` endpoint accepts `url=` or `full_path=` and resolves to a Riftmap repo. It handles SSH and HTTPS forms with or without the `.git` suffix, so agents starting from a git remote no longer need to enumerate the workspace. See the [endpoint reference](/api-reference/repositories/resolve-a-git-remote-url-or-full-path-to-a-repository-in-this-workspace). **Single-call repo context.** A new `GET /repositories/{id}/context` endpoint returns the repo, its direct dependents and dependencies (with totals), and the artifacts it produces — everything an agent needs to reason about a repo in one request. See the [endpoint reference](/api-reference/repositories/single-call-context-bundle-for-ai-coding-agents). **Subgraph filtering on the org graph.** `GET /connected-orgs/{id}/graph` now accepts `?root=&depth=N` to return only a repo and its upstream and downstream neighbors within N hops. Useful for keeping agent context windows small on large orgs. See the [endpoint reference](/api-reference/graph/get-the-dependency-graph-full-org-or-subgraph-anchored-at-a-repo). ## Updates **Pagination on dependency endpoints.** [`/repositories/{id}/dependencies`](/api-reference/repositories/list-the-dependency-declarations-this-repository-makes) and [`/repositories/{id}/dependents`](/api-reference/repositories/list-the-repositories-that-directly-depend-on-this-repository) now support `limit` (1–500, default 100) and `offset`, with an `X-Total-Count` response header for total result size. **Freshness fields on repository responses.** Repository payloads now include `last_commit_sha`, `last_activity_at`, and `archived`, so you can detect "pushed since last scan" without a second call. **Polished OpenAPI metadata.** Every agent-facing route now has a one-line summary in the OpenAPI schema, improving the experience for LLMs and code generators reading it. ## Bug fixes **Graceful scan dispatch on org connect.** If the background scan dispatcher fails when connecting an org, the org is still created and returned cleanly instead of erroring out. # Week of May 22, 2026 Source: https://docs.riftmap.dev/changelog/2026-05-22 Riftmap's May 22, 2026 release broadens Helm, Python, Terraform, and Ansible dependency detection, adds a /ready health probe, and self-heals Stripe billing. ## New features **`/ready` health probe.** A new public `/ready` endpoint returns `200` only when Postgres, both Redis instances, and at least one scan worker are reachable, and `503` otherwise. Point external uptime monitors at it to catch half-broken states the main `/health` endpoint can't see. **Idempotent scans.** `POST /connected-orgs/{id}/scans` now rejects a second scan for an org that already has one pending or running with a `409 Conflict`. Safe to retry from agents and CI without queuing duplicates. **Broader Helm, Python, Terraform, and Ansible detection.** Riftmap now recognizes cross-repo consumption from `helmfile.yaml`, `kustomization.yaml`'s `helmCharts`, Poetry and uv dependency tables, and Ansible Galaxy `requirements.yml`. Previously these declarations were invisible — orgs heavy on Helm or Python will see substantially more edges on the next scan. **Container image edges from Helm chart templates.** Scans now extract `image:` references from `charts/*/templates/*.yaml` even when they contain Go template directives, surfacing `k8s_container_image` consumption that was previously dropped at parse time. ## Updates **Faster recovery from stuck scans.** The stuck-scan reaper now runs every 15 minutes instead of daily and uses task state (not just age) to decide what to clear, so a hard-killed scan no longer blocks an org's queue for hours. **Search-jump camera stability.** Clicking a graph search result reliably pans to the target node and opens the detail panel without the graph re-fitting and undoing the pan. Subsequent searches in the same session also stay stable. **GitHub container registry attribution.** Docker image artifacts produced by GitHub-hosted repos now resolve to `ghcr.io//` instead of an invalid host, so consumer matching across GitHub orgs works correctly. ## Bug fixes **Artifact consumers reflect the latest scan.** [`/artifacts/{id}/consumers`](/api-reference/artifacts/list-repositories-consuming-this-artifact-with-pinned-versions), `/artifacts/{id}/versions`, and the `/stats` endpoints could return stale pinned versions and inflated orphan counts after a re-scan because they read across all historical scans. They now scope to the latest scan per org, so edited constraints show up immediately and `consumers_lagging` is correct. **Stripe checkout self-heal.** Workspaces whose subscription was canceled out-of-order with a late `invoice.payment_succeeded` webhook could get stuck unable to re-checkout. The checkout endpoint now reconciles with Stripe before returning `409`, and the plan card surfaces a clear next action instead of a generic error. **Worker boot resilience.** The worker healthcheck sidecar now starts before the broker connection, so a slow Redis at boot no longer causes the platform to mark workers unhealthy and restart them in a loop. **Cleaner dependency graphs.** The resolver now rejects several classes of bogus artifacts that were polluting org graphs: * Vendored `package.json` files (e.g. Hugo themes, vendored frontend assets) no longer register as npm packages "produced by" the host repo. * Vendored or subchart `Chart.yaml` files no longer attribute Helm charts to the wrong repo. * Go modules with bare names (`module foo`) or bare hosts (`module github.com`) are dropped instead of prefix-matching unrelated consumers. * Self-edges (a repo declaring a dependency on its own artifact via a sub-module) are filtered from the resolver chain. These changes mean noticeably fewer phantom edges on the next scan, especially for orgs with vendored dependencies or multi-module Go repos. # Week of June 2, 2026 Source: https://docs.riftmap.dev/changelog/2026-06-02 Ownership & bus-factor signal (preview): find single-maintainer repos everyone depends on, from git-history scans, new API endpoints, and a bus-factor overlay. ## New features **Ownership & bus-factor signal (opt-in preview).** Riftmap can now extract human contributor data from git history during a scan and derive a per-repo **bus factor** — the number of developers who'd have to leave before a repo is effectively unmaintained. Crossed with the existing fan-in graph, it surfaces the repos that matter most: **high blast radius × single maintainer** — the build/CI/base-image substrate that everyone depends on but nobody owns. Activity-based health checks miss these (a repo can have a commit this morning and a bus factor of 1); anchoring bus factor to the dependency graph is what makes the finding actionable. The signal ships **off by default** and is enabled per deployment via `OWNERSHIP_SIGNAL_ENABLED`. The new API endpoints below are always callable and return empty / zero / `null` payloads until it's turned on and an org has been re-scanned — so agents never need a flag-aware branch. * **`GET /repositories/{id}/ownership`** — per-repo bus factor, top-author share, human author count, and the full human contributor list (paginated, bots stripped). Names only, never emails. * **`GET /connected-orgs/{id}/ownership-risk`** — the ranked findings feed of concentration-risk repos (high fan-in × low bus factor), ordered by risk score. `min_dependents` / `max_bus_factor` overrides for ad-hoc queries. * **`GET /repositories/{id}/context`** now carries a slim `ownership` summary (`bus_factor`, `top_author_name`, `human_author_count`), so an agent can answer "who maintains this, and is changing it risky?" in the same round-trip it already makes. In the app, a **bus-factor overlay** colours graph nodes by maintainer concentration and a **Concentration Risk** panel lists the flagged repos, with an "Owners" tab on every repo's detail view. **Privacy:** contributor data is git **author metadata only** — no commit messages, diffs, or file blobs. It's workspace-scoped, cascade-deleted on workspace deletion and the 30-day GDPR purge, and the API only ever returns names, never emails. See [Security](/security). # Week of July 4, 2026 Source: https://docs.riftmap.dev/changelog/2026-07-04 Riftmap's July 2026 security audit, fully remediated: role-gated config mutations, SSRF-validated org URLs, a hardened scanner, and single-use password resets. ## Security **Full-codebase security audit, fully remediated.** Riftmap's second full-codebase audit (after April 2026) covered the backend, the scanner pipeline that handles untrusted repository content, the frontend, dependencies, and infrastructure. It found **no critical issues**, and every finding — three high, six medium, and a tail of low-severity hardening items — was fixed with an accompanying regression test before the record was published. The complete remediation record is [public in the repository](https://github.com/DanielWestgaard/Riftmap/blob/main/docs/audits/SECURITY_AUDIT_2026-07-04.md); the control-by-control summary is the verified-controls table in [docs/security.md](https://github.com/DanielWestgaard/Riftmap/blob/main/docs/security.md). Two changes are visible in the API and worth calling out for integrators: * **Configuration mutations now require the Owner or Admin role** (session auth). `POST /connected-orgs` (registering an org), `POST /connected-orgs/{id}/scans` (triggering a scan), and creating or rotating workspace API keys (including the deprecated `/api-key/regenerate`) return **403** for plain members. Workspace API keys are owner-equivalent and unaffected — CI pipelines keep working unchanged. Cancelling an in-flight scan deliberately remains member-permitted. * **Connected-org URLs are validated against SSRF.** The PAT-mode `url` must be a public `https://` host; addresses resolving to private, loopback, link-local, or cloud-metadata ranges return **422** at registration and are re-checked at scan time. Self-hosted GitLab / GitHub Enterprise on a public address is unaffected; self-hosted Riftmap deployments scanning an internal platform can opt out with `SCAN_ALLOW_PRIVATE_HOSTS=true`. Under the hood, the same wave hardened the scanner against hostile repository content (symlinks are neutralised at clone time, file walks never read outside the clone tree, and working trees above a size cap are rejected), made password-reset links single-use, equalised login timing so response latency can't reveal whether an email is registered, and added a Content-Security-Policy to the app document at `app.riftmap.dev` (rolling out report-only, then enforcing). # Week of September 15, 2026 Source: https://docs.riftmap.dev/changelog/2026-09-15 Riftmap now records every GitHub Actions uses: line with its full action or workflow path, resolves org .github repositories, and lists dependents one row per use. ## Improvements **Every GitHub Actions `uses:` line, with the action it names.** For a repository that ships several actions or reusable workflows, Riftmap used to record only `owner/repo` — never which action a consumer called — and kept just the first reference to that repository in each workflow file. It now stores one declaration per `uses:` line: `raw_reference` is the full path (`grafana/shared-workflows/actions/send-slack-message`, or `owner/repo/.github/workflows/release.yml` for a reusable workflow), `version_constraint` is that line's own ref, and `source_line` is the line it is written on, even when the same line is repeated across jobs. Local `./` and self-repository `$/` references are skipped. **Reusable workflows in an org's `.github` repository now resolve.** `cloudposse/.github/.github/workflows/x.yml` was cut down to the bare owner and never became an edge. It now resolves to `cloudposse/.github`, and GitHub Actions references match their repository case-insensitively, as GitHub does (`posthog/.github` → `PostHog/.github`). ## API changes * **`GET /repositories/{id}/dependents` returns one row per use.** Rows are deduplicated on declaration identity — consumer, dependency type, version, file, `raw_reference` and line — so a consumer using several of a repository's actions or packages appears once per use. The consuming repository is `target_repository_id`; group by `raw_reference` to list consumers per action or package. `X-Total-Count` counts these declarations, not repositories. See [Group dependents by action or package](/agents/examples#group-dependents-by-action-or-package). * **`GET /repositories/{id}/context`** adds `dependent_repositories_total`, the number of distinct repositories behind `dependents_total`. * **`GET /artifacts/{id}/versions`** `consumer_count` now counts distinct consuming repositories per version. It used to count declarations, so a repository declaring the same version twice (two Dockerfiles, a dev and a peer entry) was counted twice. * **Declaration counts rise on rescan.** Repeated declarations of one reference in a file — a second `uses:` of an action, an npm package listed as both a dev and a peer dependency, a repeated Dockerfile `FROM` — are now separate rows, so `total_declarations` and the `declaration_outcomes` buckets grow for an org once it is rescanned. Graph edges and repository-level dependent counts are unchanged. The API changes apply as soon as they ship. The parsing and resolution changes apply to a repository once it is rescanned; until then its rows keep the earlier shape, so its `/dependents` rows carry only the hub's `owner/repo`. # Changelog Source: https://docs.riftmap.dev/changelog/overview Follow the Riftmap changelog for weekly product updates and improvements, where each entry covers the user-facing changes shipped to the platform that week. Follow along as Riftmap evolves. Each entry covers user-facing changes shipped that week. # What Riftmap detects Source: https://docs.riftmap.dev/coverage The dependency coupling Riftmap detects today — package manifests, container images, Terraform modules and CI workflows across eight ecosystems — what it deliberately does not detect yet, and why a correctly scanned org can still produce a near-empty dependency graph. Riftmap answers one question: *if I change repo X, what else breaks?* It answers it by reading what your repositories **declare** — manifests, lockfiles, Dockerfiles, Terraform sources, CI workflow references — and resolving those declarations to other repositories in the same org. That approach is deterministic and has no per-repo configuration, which is the point. It also has a definite edge, and this page is where that edge is written down. ## What we detect | Coupling | Read from | Examples | | ----------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------- | | **npm packages** | `package.json`, workspaces | internal scoped packages, `workspace:` siblings | | **Python requirements** | `requirements*.txt`, `pyproject.toml`, Poetry, PDM | private-index packages, `git+` requirements | | **Go modules** | `go.mod` | `require` directives, including sub-packages | | **Container images** | `Dockerfile`, `Dockerfile.*`, `*.Dockerfile`, `Containerfile`, `docker-compose.yml` | `FROM` base images, `COPY --from` stages | | **Terraform modules** | `*.tf`, module blocks | `git::https://…` and registry sources | | **Helm charts** | `Chart.yaml` | chart dependencies | | **CI workflows** | GitHub Actions, GitLab CI | reusable workflows, `uses:` actions, `include:` | | **Raw git URLs** | anywhere in a scanned file | clone URLs that name an in-org repo | Riftmap also detects what each repo **produces** — Docker images, npm packages, Python distributions, Helm charts, Terraform modules — and matches producers to consumers, so an edge can exist even when the two repos never name each other directly. ## What we do not detect yet **Runtime coupling.** A service that calls another service over HTTP declares nothing about it in any manifest. If your repos are named `billing-api`, `zoho-client`, `orders-client`, most of your real architecture is service-to-service HTTP — and Riftmap cannot currently see any of it. This is the single largest gap, and the one most likely to explain a near-empty graph. **Contract-level coupling.** Shared OpenAPI specs, protobuf definitions and GraphQL schemas describe exactly the dependencies that runtime coupling creates. Parsing them is the planned answer to the gap above. **Shared infrastructure.** Two services on the same database, queue or bucket are coupled in practice and identical in every manifest. **Monorepo-internal imports.** Within a single repository, Riftmap maps what that repo depends on — not how its internal packages depend on each other. **Vendored and copy-pasted code.** Code duplicated rather than depended on leaves no declaration behind. ## Why your graph might look empty A scan can be completely correct and still produce very few edges. The usual cause is not a bug and not a misconfiguration: * **You don't publish internal packages.** If nothing in your org depends on anything else in your org *by name*, there is no manifest-level edge to find. Orgs that build many standalone services and share nothing through a package registry legitimately have almost no packaging coupling. * **Your coupling is runtime, not packaging.** See above. This is very common for services organisations, and it is our gap, not yours. * **The scan didn't see everything.** Check the scan on the Scans page: `failed_repos > 0` means some repos could not be processed, and a repository-limit banner means some were skipped by your plan. When a graph is mostly unconnected repositories, Riftmap now says so directly rather than rendering a field of dots without explanation, and hides the unconnected repos by default so the real edges are visible. Nothing is deleted — the count is stated and one click brings them back. A low resolution rate is **not** in itself a problem. Most declarations in any real repository point at third-party packages (`react`, `fastapi`, `alpine`), and those are supposed to stay unresolved. The only meaningful question is whether an unresolved reference names a repo in your own org. `GET /connected-orgs/{id}/stats` answers exactly that question, in the `declaration_outcomes` object. It splits every declaration Riftmap parsed into five buckets that sum to `total_declarations`: | bucket | meaning | | ----------------------- | ----------------------------------------------------------------------------------------------------------------- | | `resolved_in_org` | Became an edge in your graph. | | `external` | Names nothing in your org — `react`, `alpine`, `actions/checkout`. Correctly not in your graph. | | `self_reference` | A repo importing its own subpackage, or an image tagged from its own repo. Not a cross-repo edge. | | `local_reference` | A `workspace:`, `catalog:`, `link:`, `file:` or `portal:` constraint. Lives in the same repository by definition. | | **`unresolved_in_org`** | **Names your org and produced no edge — the only bucket worth investigating.** | Across everything Riftmap has scanned, `unresolved_in_org` is 0.81% of all declarations. That is a total across orgs, not a promise about yours — individual orgs range from 0% to roughly a fifth, usually because one repeated reference shape doesn't parse. What makes the number useful is that it is small and *nameable*: if yours looks high, the references behind it are a short list, and sending it to us is the fastest way to get that shape supported. `resolved_in_org` is normally larger than `total_dependencies`, and that is expected: it counts declarations, while `total_dependencies` counts the deduplicated edges they collapse into. Two `require` lines pointing at the same repository are two declarations and one edge. ## Tell us what we're missing If your repositories depend on each other in a way this page doesn't cover, that is the most useful thing you can send us — it is how coverage gets prioritised. Email [hello@riftmap.dev](mailto:hello@riftmap.dev) and describe the coupling. # Riftmap Source: https://docs.riftmap.dev/introduction Riftmap scans GitHub and GitLab orgs to map cross-repo dependencies — Terraform, Docker, Helm, Go, npm — and serves a change-impact API for AI agents and CI. > **If I change repo X, what else breaks?** Riftmap scans a GitLab group or GitHub organization, automatically discovers how repositories depend on each other across ecosystems, and exposes a queryable dependency graph and change‑impact API. It's designed as a first‑class tool for AI coding agents and CI pipelines that need to know the blast radius of a change *before* shipping it. ## What it does 1. **Scans** every repo in a connected org with a read‑only platform token. 2. **Parses** ecosystem‑specific dependency declarations — Terraform `module {}`, Dockerfile `FROM`, Python `requirements.txt` / `pyproject.toml`, GitHub Actions `uses:`, Helm `Chart.yaml`, Go `go.mod`, npm, Kustomize, Kubernetes manifests, and more. 3. **Detects artifacts** each repo *produces* (Docker images, Helm charts, Terraform modules, Python/Go packages…). 4. **Resolves** every declaration to a known repo or artifact via a per‑ecosystem resolver chain. 5. **Stores** edges in Postgres and exposes them through a small, paginated REST API. 6. **Answers** `GET /repositories/{id}/impact` with the transitive downstream blast radius via a Python BFS. ## Who this is for * **AI coding agents** (Claude Code, Cursor, Cline) that need cross‑repo context to plan a change without hallucinating dependencies. * **CI pipelines** that need to gate a merge on "did anything downstream just lose a contract?". * **Platform / infra teams** that want a queryable map of how their org actually fits together, without per‑repo config files. ## Zero per‑repo configuration Riftmap discovers everything from the actual code in the repos you connect. There are no `riftmap.yaml` files, no annotations, no manifests. Connect once at the org level with a read‑only token; everything else is automatic. ## What's next Sign up, connect your first org, and make your first API call in five minutes. The recommended call pattern for AI agents: lookup → context → impact, with a freshness check rule. Create a workspace API key and learn the header conventions. Full interactive reference, generated from the live OpenAPI schema. # Quickstart Source: https://docs.riftmap.dev/quickstart Riftmap quickstart: sign up, connect a GitHub or GitLab org, trigger a dependency scan, mint an API key, and make your first repo-lookup call in five minutes. This guide walks through the shortest path to a working Riftmap integration: sign up, connect an org, run a scan, mint an API key, and resolve a repo by URL. ## 1. Create an account Sign up at [app.riftmap.dev/register](https://app.riftmap.dev/register). The free plan includes one workspace, up to 15 repos, and one connected org — enough to validate the integration end‑to‑end before deciding whether a paid plan makes sense. ## 2. Connect a GitHub or GitLab org After registration the onboarding wizard prompts you to connect your first org. Two paths: * **OAuth** (one click) — works for GitLab today and for GitHub orgs where your linked account already has `repo` scope. * **Personal Access Token (PAT)** — recommended for GitHub. A fine‑grained PAT with `Contents: Read‑only` + `Metadata: Read‑only` is enough; classic PATs need `repo` + `read:org`. Riftmap stores the token encrypted at rest with Fernet and never makes a write call against your org. ## 3. Trigger the first scan Once the org is connected, Riftmap kicks off an initial scan automatically. A full scan of a small org typically completes in under a minute; larger orgs scale roughly with `(repo count) × (avg manifest count)`. You can also trigger a scan manually: ```bash theme={null} curl -X POST "https://api.riftmap.dev/api/v1/connected-orgs/$ORG_ID/scans" \ -H "X-API-Key: $RIFTMAP_API_KEY" \ -H "Content-Type: application/json" \ -d '{"scan_type": "full"}' ``` ## 4. Create a workspace API key In the app: **Settings → API keys → Create new key**. The raw key is shown **once** — copy it into your secret manager immediately. Keys are workspace‑scoped, so they never need a `workspace_id` parameter. Keys look like `rfm_live_`. Use them as either header: ```bash theme={null} X-API-Key: rfm_live_xxx # canonical Authorization: Bearer rfm_live_xxx # convenience alias ``` See [Authentication](/authentication) for the full header conventions. ## 5. Make your first call The most common agent entry point is "I have a clone URL — what does Riftmap know about this repo?": ```bash theme={null} curl "https://api.riftmap.dev/api/v1/repositories/lookup?url=https://github.com/myorg/payments-api" \ -H "X-API-Key: $RIFTMAP_API_KEY" ``` Sample response (truncated): ```json theme={null} { "id": "8c72…", "connected_org_id": "3a91…", "name": "payments-api", "full_path": "myorg/payments-api", "clone_url": "https://github.com/myorg/payments-api.git", "default_branch": "main", "last_scanned_at": "2026-05-08T09:14:22Z", "last_commit_sha": "e3bad69…", "last_activity_at": "2026-05-08T08:51:00Z", "archived": false } ``` The freshness fields (`last_scanned_at`, `last_commit_sha`, `last_activity_at`, `archived`) appear on every repo response. Agents should compare `last_activity_at` to `last_scanned_at` to decide whether the data is fresh enough to act on. ## Next step Most agent integrations need more than a single repo lookup. The recommended pattern for hydrating context in one round‑trip is documented in [Agent integration → Overview](/agents/overview). # Security Source: https://docs.riftmap.dev/security Riftmap security: how to report a vulnerability, how scanned source code and tokens are handled, plus our auth design, GDPR data export, and audit history. ## Reporting a vulnerability If you've found a security issue in Riftmap, please **disclose it privately** rather than posting it publicly. Email **[hello@riftmap.dev](mailto:hello@riftmap.dev)** with reproduction steps and any relevant version, request, or environment info. We aim to acknowledge within two business days. Goes straight to maintainers. Please use this channel rather than opening a public issue anywhere. ### What's in scope * The hosted product at `app.riftmap.dev`, its API at `api.riftmap.dev`, and the marketing site at `riftmap.dev` * The static schema and docs at `docs.riftmap.dev` and `app.riftmap.dev/openapi.json` ### What's out of scope * Reports based purely on automated scanner output without a working proof‑of‑concept * Volumetric DoS / brute-force findings against the hosted product (we have rate limits; please don't try to find their thresholds) * Issues that require a privileged position the attacker shouldn't have (e.g. "if I steal an owner's API key, I can act as that owner") * Social engineering of staff or customers ### What we'll do 1. Acknowledge the report. 2. Triage and confirm the issue, or push back with reasoning. 3. Develop and ship a fix; coordinate disclosure timing with you. 4. Credit you in release notes if you'd like (and if the fix is shipped). We don't currently run a paid bug-bounty program, but we do appreciate the work and will say so publicly when a fix lands. ## What Riftmap does with your data Short version: * **Source code is never stored.** Repos are shallow-cloned (depth=1) into a per-scan temporary directory at `0700` permissions, parsed for dependency manifests, and `rmtree`'d in a `try/finally`. Only the dependency graph metadata persists in the database. * **Scanned repos are treated as hostile input.** Clones run with symlinks disabled (`core.symlinks=false`) and the file walks skip symlinks and never read outside the clone tree — a malicious repo can't point the scanner at `/etc/passwd` or the worker's environment. Working trees above a total size cap are rejected before parsing. * **The scan worker can't be aimed at internal networks.** Every organisation URL and clone URL must be public `https://` — hosts resolving to private, loopback, link-local, or cloud-metadata addresses are rejected at registration (422) and re-checked at connect time. Upstream error bodies are never echoed into scan results. * **Contributor data is opt-in.** The ownership / bus-factor signal is off by default. When a workspace enables it, Riftmap extracts contributor names and emails from git **author metadata only** (no commit messages, diffs, or file blobs) to compute a per-repo bus factor. This personal data is workspace-scoped and cascade-deleted on workspace deletion and the 30-day GDPR purge; the API ever returns contributor **names only**, never emails. * **Tokens are encrypted at rest** with Fernet. The encryption key lives in env (`ENCRYPTION_KEY`) and is required at startup outside dev mode. * **Cross-workspace isolation** is enforced at every endpoint: workspace API keys can't reach another workspace's data, and foreign-workspace requests return 404 (not 403, to avoid leaking existence). * **GDPR data export** is available at `GET /workspaces/{id}/export` (owner/admin only). Account deletion is at `POST /auth/account/delete` with a 30-day grace period. ## Auth design (one-pager) | Surface | Auth | Notes | | ---------------- | ------------------------------------------------------- | ------------------------------------------- | | Browser sessions | JWT cookies (15-min access, 30-day refresh, `HttpOnly`) | Set by `/auth/login` and OAuth callback. | | API integrations | Workspace API keys (`rfm_live_…`) | SHA-256 hashed at rest; raw key shown once. | Mutations are rate-limited per identity. Cross-workspace access returns 404. Configuration mutations — registering a connected org, triggering a scan, creating or rotating API keys — require the **Owner or Admin** role for session users (workspace API keys are owner-equivalent by design). Password-reset links are single-use, and login timing is constant for unknown emails. See [Authentication](/authentication) for the header conventions and limit specifics. ## Responsible exposure decisions We deliberately: * **Disable live `/openapi.json` and `/docs` in production** — agents read the static schema published from CI at [`app.riftmap.dev/openapi.json`](https://app.riftmap.dev/openapi.json), which is reviewed and exported deliberately rather than auto-introspected from a running prod server. * **Return 404, not 403, for cross-workspace requests** — so attackers can't enumerate which workspace IDs are real. * **Return rate-limit errors with a precise `Retry-After`** rather than silently dropping requests — predictable behaviour beats opaque failure. If you find a place where these defaults haven't been applied, that's exactly the kind of report we want. ## Audit history Riftmap goes through recurring full-codebase security audits — most recently **April 2026** and **July 2026** — covering the backend, the scanner pipeline (untrusted repository content), the frontend, dependencies, and infrastructure. Every finding is remediated with an accompanying regression test, and the complete remediation records are public: * [July 2026 audit & remediation record](https://github.com/DanielWestgaard/Riftmap/blob/main/docs/audits/SECURITY_AUDIT_2026-07-04.md) — no critical findings; all findings fixed before publication. * [Verified controls table](https://github.com/DanielWestgaard/Riftmap/blob/main/docs/security.md) — every documented control cross-checked against the code, including what we deliberately risk-accept. This is also where the user-facing security summary on the marketing site is sourced from.