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

# Agent integration

> How AI coding agents and CI pipelines call the Riftmap API: lookup, context, and impact endpoints, the freshness rule for stale data, 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`:

<Steps>
  <Step title="Resolve the local clone URL to a Riftmap 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`.
  </Step>

  <Step title="Hydrate context in one round-trip">
    ```http theme={null}
    GET /repositories/{id}/context
    ```

    Returns `{ repository, dependencies (capped 100, with dependencies_total), dependents (capped 100, with dependents_total), artifacts, ownership }`. 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.
  </Step>

  <Step title="Drill in as needed">
    * More than 100 dependents? `GET /repositories/{id}/dependents?limit=500&offset=0`
    * Transitive blast radius? `GET /repositories/{id}/impact?max_depth=3`
    * 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`
  </Step>

  <Step title="Decide trust">
    If `last_activity_at > last_scanned_at`, the data is stale. The agent can warn the user, fall back to a simpler analysis, or trigger a rescan and retry.
  </Step>
</Steps>

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

<Tip>
  **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.
</Tip>

For a CI gate, "stale" usually means "trigger a rescan and re‑poll". For an interactive agent, "stale" usually means "warn the user, then proceed with the caveat surfaced in the response".

`archived: true` is also a strong signal — archived repos are a frequent source of phantom edges in older graphs.

## Pagination contract

All list endpoints (dependencies, dependents, repositories, artifacts, scans, members) follow the same shape:

| 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, paginated, deduplicated.                                                                                                  |
| `GET /repositories/{id}/impact`                    | Transitive downstream blast radius via Python BFS. **Repo-level; not file-scoped** (no `path`/`file`/`job` query param).                     |
| `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).