Source: https://seerepo.com/docs/api
Markdown source: https://seerepo.com/docs/api.md
Description: Read your maps, their modules, what changed and their figures from your own code or your agent, and make the three changes you allow.

# The SeeRepo API

Use the SeeRepo API to read your project's map from a script, your backend or an AI agent: its modules and parts, a search, what changed since a date, and its figures. It reads; with a key you let write, it also makes three changes (ignore paths, mark a finding false, set a task aside), each in two steps. It comes with every plan.

There are three ways in, with the same key:

| Way in | Use it for |
|---|---|
| API | Your own code or scripts, with plain HTTP |
| [MCP](/docs/mcp) | An AI agent like Claude Code, Codex or Cursor, asking in words |
| [CLI](/docs/cli) | Your terminal: `npx seerepo map` |

## Base URL

`https://seerepo.com/api/v1/`

## Authentication

Every request carries an API key as a Bearer token:

```http
Authorization: Bearer sr_…
```

Create keys in **Settings → API / MCP** (your account's settings, not a project's). Name each one after where it's used, like "Claude Code". The key is shown whole **once**; afterwards only its last 4 characters. Revoke a key there and whatever uses it stops at once.

One key reads every map your account reads: your own and the ones shared with you. It can't read anyone else's: their repos answer as not found.

Keep your key secret: don't put it in front-end code or in a public repo.

## Get started

1. Create a key in **Settings → API / MCP**.
2. List your repos and take the `id` of one:

```sh
curl https://seerepo.com/api/v1/repos \
  -H "Authorization: Bearer $SEEREPO_KEY"
```

3. Read its first level, then follow the `path` of any part to go inside:

```sh
curl "https://seerepo.com/api/v1/repos/REPO_ID/world?path=/" \
  -H "Authorization: Bearer $SEEREPO_KEY"
```

`REPO_ID` may also be `owner/name`, with the slash written `%2F`: `ana%2Ftienda`.

## Endpoints

| Endpoint | What it returns |
|---|---|
| [`GET /me`](/docs/api-me) | The account your key belongs to |
| [`GET /repos`](/docs/api-repos) | The maps your key reads |
| [`GET /repos/:repo/world`](/docs/api-world) | One module: its parts, where it connects, its outside services |
| [`GET /repos/:repo/search`](/docs/api-search) | Parts by name or phrase in every module, and files by path |
| [`GET /repos/:repo/impact`](/docs/api-impact) | What breaks if you touch a file: who names it, how far it gets, which pages and processes |
| [`GET /repos/:repo/events`](/docs/api-events) | The commits since a date, in plain words |
| [`GET /repos/:repo/figures`](/docs/api-figures) | The lifetime figures: commits, AI, lines and files |
| [`GET /repos/:repo/pages`](/docs/api-pages) | Every page: who gets in and the states it handles or misses |
| [`GET /repos/:repo/found`](/docs/api-found) | How search engines and AI see each public page, with proof |
| [`GET /repos/:repo/health`](/docs/api-health) | The score, whether it can ship and the tasks, each with its prompt |
| [`GET /repos/:repo/history`](/docs/api-history) | The last 7 days, the pace and the moments |
| [`GET /repos/:repo/docs`](/docs/api-docs) | The repo's wiki: its tree, and each page with its sources |
| [`GET /repos/:repo/docs/:page`](/docs/api-docs) | One page of the wiki in markdown, with its sources linked to GitHub |
| [`POST /repos/:repo/changes`](/docs/api-changes) | Prepare a change, with a key that writes; `POST /changes/apply` applies it, `POST /changes/:id/undo` undoes it, `GET /repos/:repo/changes` lists them |

The API never returns your code: names, phrases, paths and figures only. A repo on the free look reads as it does in the app: whole up to 300,000 written lines, without what its parts do except its sample; above that, only its first level, with a 402 going inside.

## Responses

Every answer is JSON with the same envelope:

```json
{ "status": "success", "data": { } }
```

## Errors

```json
{ "status": "error", "error": { "code": "not_found", "message": "No repo with that id or name in this account." } }
```

| Status | `code` | When |
|---|---|---|
| 400 | `bad_path`, `bad_query`, `bad_since` | A parameter isn't valid; the message says how to write it |
| 401 | `unauthorized` | No key, a mistyped one or a revoked one |
| 402 | `plan_required` | A module of a free repo above 300,000 written lines, or a free repo's commits in plain words |
| 404 | `not_found`, `no_world` | A repo your account doesn't read, or a path with no module |
| 429 | `rate_limited` | Over the limit; `Retry-After` says how many seconds to wait |

## Limits

60 requests a minute per key. An agent stuck in a loop gets `429` with a `Retry-After` header, and can try again after those seconds.