> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userepo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> REST endpoints for agents and applications.

## Base URL

| Environment    | URL                       |
| -------------- | ------------------------- |
| **Production** | `https://api.userepo.com` |
| Local dev      | `http://localhost:4000`   |

## Authentication

All `/v1/*` requests (except OAuth callbacks and webhooks) require a bearer token:

```http theme={null}
Authorization: Bearer repo_your_key
```

See [Authentication](/authentication) for full details on minting and scoping keys.

## Two endpoint surfaces

Repo exposes two parallel route surfaces:

* **Agent API** (`/v1/*`) — authenticated by `repo_` API keys. This is what your agent code calls.
* **Console API** (`/v1/console/*`) — authenticated by Supabase Auth bearer tokens. This is what the browser console calls. Documented in \[the Console section] (coming soon) — most agent integrations should ignore it.

This reference documents the **Agent API**. If you're building a script or an admin tool that needs human-style access (creating organizations, listing audit events for compliance), use the agent API with an `admin`-scoped key instead.

## Endpoints at a glance

<CardGroup cols={2}>
  <Card title="POST /v1/search" icon="magnifying-glass" href="/api-reference/search">
    Vector search across your org's memory. Returns ranked hits.
  </Card>

  <Card title="POST /v1/context" icon="file-contract" href="/api-reference/context">
    Search + Context Contract with citations, exclusions, and limitations.
  </Card>

  <Card title="POST /v1/ask" icon="message-question" href="/api-reference/ask">
    Grounded answer generation. Citations included.
  </Card>

  <Card title="GET /v1/memory-canvas" icon="diagram-project" href="/api-reference/memory-canvas">
    Graph view of entities, relationships, and sources.
  </Card>

  <Card title="GET/POST/DELETE /v1/api-keys" icon="key" href="/api-reference/api-keys">
    Mint, list, and revoke API keys (admin only).
  </Card>

  <Card title="GET /v1/sources" icon="plug" href="/api-reference/sources">
    List connectors and their health.
  </Card>

  <Card title="GET/POST /v1/sync-runs" icon="arrows-rotate" href="/api-reference/sync-runs">
    View sync history; trigger manual syncs.
  </Card>

  <Card title="POST /v1/ingest" icon="upload" href="/api-reference/ingest">
    Push documents directly without a connector.
  </Card>

  <Card title="GET /v1/audit-events" icon="clipboard-list" href="/api-reference/audit-events">
    Pull the audit trail for compliance review.
  </Card>
</CardGroup>

## Conventions

* **Request body**: JSON. Always include `Content-Type: application/json`.
* **Response body**: JSON. UTF-8.
* **Timestamps**: ISO 8601 UTC, e.g. `2026-05-30T20:14:00.123Z`.
* **IDs**: UUIDv4 unless otherwise noted.
* **Pagination**: cursor-based on endpoints that need it (none yet require it heavily). When introduced, the pattern will be `?cursor=...&limit=...` with a `nextCursor` in the response.

## Errors

See [Errors](/errors) for the full status code catalog. The short version:

| Code | Meaning                                                     |
| ---- | ----------------------------------------------------------- |
| 200  | OK                                                          |
| 201  | Created                                                     |
| 400  | Bad request (validation, missing params, malformed state)   |
| 401  | Missing or invalid bearer token                             |
| 402  | Subscription required (no active plan)                      |
| 403  | Authenticated but lacking the required scope or role        |
| 404  | Resource not found                                          |
| 409  | Conflict (e.g. trying to revoke the key making the request) |
| 429  | Rate limit or credit budget exceeded                        |
| 500  | Server error                                                |
| 502  | Upstream OAuth or provider error                            |
| 503  | Service not configured (e.g. Stripe missing in dev)         |

Error bodies are JSON: `{ "error": "human-readable message" }` plus optional structured fields.