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

# Quickstart

> From signup to first API call in about 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_<random>`. 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).