# Riftmap

> Cross-repository dependency mapper for GitLab and GitHub orgs. Scans an org, detects how repos depend on each other across ecosystems (Terraform, Docker, Python, GitHub Actions, GitLab CI, Helm, Go modules, npm, Kustomize, Kubernetes, Ansible), and answers "if I change repo X, what breaks?" via a small REST API designed for AI coding agents and CI pipelines.

## For AI coding agents

- [Agent integration overview](https://docs.riftmap.dev/agents/overview.md): the recommended call pattern (lookup → context → impact), the freshness check rule, the full agent-facing endpoint surface
- [Code examples](https://docs.riftmap.dev/agents/examples.md): curl, Python (httpx), and TypeScript (fetch) snippets for the four core flows — resolve clone URL, hydrate context, compute blast radius, walk subgraph — plus pagination and error handling
- [MCP and CLI roadmap](https://docs.riftmap.dev/agents/mcp-cli-roadmap.md): deferred until users ask; design is documented so the surface stays predictable

## Authentication

- [API keys and headers](https://docs.riftmap.dev/authentication.md): create a workspace API key, choose between `X-API-Key` and `Authorization: Bearer rfm_live_…`, rate limits, revocation

## API reference

- [Full OpenAPI schema](https://riftmap.dev/openapi.json): machine-readable, regenerated in CI on every backend release, served from a stable static URL because the live `/openapi.json` is gated off in production
- [Interactive API reference](https://docs.riftmap.dev/api-reference): auto-generated from the OpenAPI schema, with a try-it-out playground keyed off your workspace API key

## Conventions

- **Pagination** — `limit` (1–500, default 100) and `offset` query params on every list endpoint; `X-Total-Count` response header carries the total matching rows
- **Freshness** — every repo response carries `last_scanned_at`, `last_commit_sha`, `last_activity_at`, `archived`. Agents should check `last_activity_at > last_scanned_at` to detect stale data and decide whether to trigger a rescan
- **Workspace isolation** — API keys are workspace-scoped; foreign-workspace requests return 404, never 403, to avoid leaking existence
- **Auth fallback order** — `X-API-Key` → `Authorization: Bearer rfm_*` → session cookie → 401

## Getting started

- [Quickstart](https://docs.riftmap.dev/quickstart.md): sign up at riftmap.dev/register, connect a GitHub or GitLab org, kick off a scan, mint an API key, make your first lookup call
- [Introduction](https://docs.riftmap.dev/introduction.md): what Riftmap does, who it's for, the seven-step scan-to-graph pipeline

## Trust & security

- [Security policy and data handling](https://docs.riftmap.dev/security.md): vulnerability disclosure via hello@riftmap.dev, in-scope and out-of-scope reports, source-code-never-stored guarantee, token encryption, cross-workspace isolation, auth model