An API for the agent doing the work
Everything the map knows about a repository, over plain HTTP, read-only. Meant for a coding agent that should check what a change touches before it makes the change, and for any script that wants the same answer.
- 8
- routes, all reads
- 120
- requests a minute, per key
- 0
- writes a key can make
1. What it is
The same data the canvas draws, served as JSON from https://api.cleap.dev. A repository, its entry points, every node and how they connect, and the source behind any one of them.
Nothing here is a second system. The canvas calls these routes with a person's session; a key calls the same routes and gets the same answers, minus one thing (section 6). If the map is right, the API is right, and when the map changes on the next sync, so does every answer below.
2. Get a key
A workspace owner or admin creates one in the app under Settings, in the section named API keys. It is shown once, at creation, and never again.
A key looks like cleap_sk_… and belongs to the workspace that made it, so it can read exactly the repositories that workspace has connected and nothing else. Only a hash is stored; losing the value means making a new one. Revoking is a timestamp, not a delete, so a leaked key can never be minted again by accident.
3. Authenticate
One header on every request. The same header a signed-in person's browser sends.
curl "https://api.cleap.dev/repo/<repo_id>" \ -H "Authorization: Bearer cleap_sk_..."
A repository the key cannot see answers 404, the same as one that does not exist. There is no 403 to tell an outsider which ids are real. Reads on the repository and graph routes are limited to 120 requests a minute, counted per key, so one runaway loop caps that key and not everyone behind the same address.
4. The routes
Eight, all reads. Repository ids come from the app.
| GET /repo/:id | A repository: name, sync status, node and edge counts, the map's bounds (world_bbox) and its zoom bands. |
| GET /repo/:id/status | Sync status alone. Cheap enough to poll while a first sync runs. |
| GET /repo/:id/entry-points | Where execution starts: routes, pages, commands and handlers, each with the node it lives in. |
| GET /repo/:id/labels | A flat index of every node: technical label, plain-language label, category and position. Search over this. |
| GET /repo/:id/snapshots | The repository's size over time: node, edge and orphan counts per structural change. |
| GET /graph | Nodes and edges inside a window of the map. repo_id, bbox=minX,minY,maxX,maxY and zoom are all required; world_bbox from the repository call is the whole map. |
| GET /node/:id | One node: labels, category, path, breadcrumb, connections and timeline. |
| GET /node/:id/source | The file behind a file or symbol node, fetched from GitHub at call time and never stored, with the symbol's line range. |
Node ids contain :: and /, so URL-encode them. Every field the map draws is in the graph response: technical_label, plain_label, category, provenance, importance, depth, position, sync freshness, and the GitHub signals the sync could fetch (contributors, open pull requests, Dependabot alerts).
5. A first walk
The order an agent would actually take, from a repository id to a line of code.
# 1. Is the map ready, and how big is it? curl "https://api.cleap.dev/repo/<repo_id>" -H "$AUTH" # 2. Where does execution start? curl "https://api.cleap.dev/repo/<repo_id>/entry-points" -H "$AUTH" # 3. Find a node by name (search this index yourself) curl "https://api.cleap.dev/repo/<repo_id>/labels" -H "$AUTH" # 4. What does it touch? curl "https://api.cleap.dev/node/<node_id, url-encoded>" -H "$AUTH" # 5. Read the code behind it curl "https://api.cleap.dev/node/<node_id, url-encoded>/source" -H "$AUTH"
Where AUTH is Authorization: Bearer cleap_sk_…. The graph route is for drawing a region; for "what does this file depend on" the node route's connections is the shorter path.
6. What a key cannot do
Anything that changes state. An agent can look, not act.
Triggering a sync, connecting a repository, managing integrations or keys, editing a label, and asking cleap a question in Ask all need a signed-in person, and answer a key with 403 and the sentence "This endpoint requires a signed-in user, not an API key". Per-person label overrides are a preference, not a fact about the code, so they are always null to a key.
7. Without a key
The showcase maps are readable with no credential at all, for trying the shapes before you connect anything.
| GET /showcase | The showcase repositories, with their counts. |
| GET /showcase/repo/:id | One of them, same shape as the repository call above. |
| GET /showcase/graph | A window of its map, same parameters as the graph call above. |
| GET /showcase/node/:id | One of its nodes. |
8. For your agent
A skill file that teaches an agent the walk in section 5, and when to take it.
Read https://cleap.dev/skills/cleap/SKILL.md and use cleap to check what this change touches before you make it. My key is in CLEAP_API_KEY.
That is the whole prompt. The file is plain markdown at cleap.dev/skills/cleap/SKILL.md, and cleap.dev/llms.txt carries the same route list for anything that reads that convention.
9. Not yet
Said plainly, so nobody builds against something that is not there.
There is no MCP server; use HTTP. There are no write routes, and none planned before there is a way to attribute a write to a person. Keys are free and uncounted during the beta; whether agent access is ever metered is undecided, and this page will say so before anything changes. Path tracing, the "what breaks if I change this" answer across many hops, is not built on the service yet; today the node route's connections are one hop.
Every route on this page is checked against the running service's own route table on every change to either. A route that disappears from the service disappears from here, or the build fails.