Skip to main content
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://api.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 + a slim ownership summary 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.