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.

The four most common agent flows, end‑to‑end. Every snippet expects two environment variables: 
RIFTMAP_API_KEY=rfm_live_xxx
RIFTMAP_BASE_URL=https://riftmap.dev/api/v1
The Python examples use httpx (async). The TypeScript examples use the runtime‑native fetch (Node 22+ / modern browsers).

​
1. Resolve a clone URL

The agent has a working tree at github.com/myorg/payments-api and needs to find the corresponding Riftmap repo. 
curl -s "$RIFTMAP_BASE_URL/repositories/lookup?url=https://github.com/myorg/payments-api" \
  -H "X-API-Key: $RIFTMAP_API_KEY"
Returns the repo row including freshness fields. Use full_path=myorg/payments-api instead of url= if you only have the slug.

​
2. Hydrate context in one round‑trip

Once you have the repo ID, fetch repo + capped dependencies + capped dependents + artifacts in a single call. 
curl -s "$RIFTMAP_BASE_URL/repositories/$REPO_ID/context" \
  -H "X-API-Key: $RIFTMAP_API_KEY"
Use dependencies_total and dependents_total to detect when you need to paginate the full lists separately (the bundled arrays are capped at 100).

​
3. Compute the transitive blast radius

When you actually need to know “if I change repo A, what transitively breaks?”, call /impact. This runs a Python BFS over confidence‑filtered edges. 
curl -s "$RIFTMAP_BASE_URL/repositories/$REPO_ID/impact?max_depth=3&min_confidence=0.8" \
  -H "X-API-Key: $RIFTMAP_API_KEY"
max_depth defaults to 10 (range 1–20). min_confidence defaults to 0.8 — drop to 0.5 if you want to include heuristic matches in the radius.

​
4. Walk the local subgraph

For visualisation, or for an agent that wants the local neighbourhood rather than the full transitive set, request a subgraph anchored at a repo. 
curl -s "$RIFTMAP_BASE_URL/connected-orgs/$ORG_ID/graph?root=$REPO_ID&depth=2&min_confidence=0.8" \
  -H "X-API-Key: $RIFTMAP_API_KEY"
Returns { nodes: [{id, type, label, metadata: {archived, last_activity_at, health_status, …}}], edges: [{source, target, dependency_type, version_constraint, confidence}] }. The shape is G6‑ready, but plain enough to drive any visualisation library.

​
Pagination

For dependencies / dependents lists past 100 items: 
# First page
curl -s -D - "$RIFTMAP_BASE_URL/repositories/$REPO_ID/dependents?limit=500&offset=0" \
  -H "X-API-Key: $RIFTMAP_API_KEY"
# Inspect X-Total-Count in headers; loop with offset += 500.

​
Errors agents should handle

StatusMeaningRecommended action
401Missing or invalid API keySurface to user; never retry.
404Repo not in this workspace, or never scannedTry lookup with the alternate parameter; fall back to “unknown repo”.
409Lookup matched multiple reposDisambiguate using full_path.
422Out‑of‑range pagination, or invalid query paramFix the request; do not retry.
429Rate limit (mutations only)Honour Retry-After header before retrying.