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