> ## Documentation Index
> Fetch the complete documentation index at: https://docs.riftmap.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Riftmap's REST API for querying cross-repository dependencies and change impact.

The Riftmap API is a small, paginated REST API that exposes the dependency graph Riftmap builds from your connected orgs. It's designed to be called by AI coding agents and CI pipelines that need to answer **"if I change repo X, what else breaks?"**

## Base URL

```
https://api.riftmap.dev
```

All endpoints are prefixed with `/api/v1`.

## Authentication

All endpoints require a workspace API key. Keys look like `rfm_live_<random>` and can be passed as either header:

```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 + artifacts.                                    |
| `GET /repositories/{id}/dependencies`              | Direct dependency declarations, paginated, deduplicated.                                                                               |
| `GET /repositories/{id}/dependents`                | Direct dependents, paginated, deduplicated.                                                                                            |
| `GET /repositories/{id}/impact`                    | Transitive downstream blast radius via Python BFS. **Repo-level; not file-scoped.**                                                    |
| `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.

<Tip>
  **`/impact` is not file-scoped.** It's a repo-to-repo BFS — there is no `path`, `file`, or `job` query parameter, and FastAPI silently ignores unknown query params (so a hallucinated filter name returns the same fan-out as no filter). For "who consumes file X in repo Y", call `/repositories/{id}/dependents` and grep the listed consumer repos directly; per-file edges aren't stored in the graph. For artifact-version consumers (Docker image / Helm chart / Terraform module), use `/artifacts/{id}/consumers` — that one *is* version-aware.
</Tip>

## Conventions

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

## OpenAPI schema

Live `/openapi.json` and `/docs` are gated off in production. The schema is generated in CI from the dev‑mode app and shipped at a stable static URL:

```
https://app.riftmap.dev/openapi.json
```

CI fails the build if the committed schema drifts from the routes, so the static file is always current.

<Tip>
  **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'
  ```
</Tip>

## Where to start

<CardGroup cols={2}>
  <Card title="Agent integration" icon="robot" href="/agents/overview">
    The lookup → context → impact pattern, the freshness rule, and the full surface in one page.
  </Card>

  <Card title="Code examples" icon="code" href="/agents/examples">
    The four core flows in curl, Python (httpx), and TypeScript (fetch).
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Create a workspace API key and learn the header conventions.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Sign up, connect an org, and make your first API call in five minutes.
  </Card>
</CardGroup>

The individual operations in the sidebar are generated from the OpenAPI schema above and include full request/response shapes, query parameters, and error codes.