Skip to main content

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.

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 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: 
curl -X POST "https://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_<random>. Use them as either header: 
X-API-Key: rfm_live_xxx                    # canonical
Authorization: Bearer rfm_live_xxx         # convenience alias
See 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?”: 
curl "https://riftmap.dev/api/v1/repositories/lookup?url=https://github.com/myorg/payments-api" \
  -H "X-API-Key: $RIFTMAP_API_KEY"
Sample response (truncated): 
{
  "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.