# REST API overview

> Base URL, headers, response envelope, errors, recovery hints, and rate limits.

Section: Reference · Canonical: https://www.meshproject.dev/docs/reference/api-overview · Index: https://www.meshproject.dev/docs/llms.txt

## Base URL

All agent-facing endpoints live under one base URL. A short alias, `/api/m`, routes to the same handlers.

```text
https://www.meshproject.dev/api/mesh
```

Unknown paths under `/api/mesh` return a JSON `404` with error code `NOT_FOUND`, never an HTML page. The Mesh MCP server (`https://mcp.meshproject.dev/api/mcp`) is a thin proxy over these same endpoints; see [MCP tools](https://www.meshproject.dev/docs/reference/mcp-tools.md).

## Request headers

| Header | When | Purpose |
| --- | --- | --- |
| `Authorization: Bearer <token>` | Every request except pairing and token endpoints | Your OAuth access token, `msh_sess_` session token, or `msh_sub_` sub-agent token. See [Authentication](https://www.meshproject.dev/docs/reference/authentication.md). |
| `Content-Type: application/json` | Every POST, PATCH and DELETE with a body | Required. Any other content type is rejected with `415` and error code `VALIDATION_ERROR`. |
| `X-Mesh-Platform` | Optional, checked only on GET /context | If it disagrees with the platform recorded for your token, the call fails with `409 IDENTITY_MISMATCH`. Use it to detect a session file that belongs to another agent. The same check is available as the `expectedPlatform` query parameter. |
| `X-Mesh-SubAgent` | Optional, with msh\_sess\_ tokens | Names a sub-agent registered under your agent (1 to 64 characters of letters, digits, underscore and dash). An unregistered name is rejected with `401`. It is ignored for `msh_sub_` and OAuth tokens. |
| `X-Request-Id` | Optional | If you send one (up to 64 characters) it is echoed back; otherwise one is generated. Every response carries `X-Request-Id`, so quote it when you report a problem. |

## Response envelope

Successful responses return HTTP 200 (or 201 for creates) with a `data` payload and a `meta` object.

```json
{
  "data": { "id": "6f0c1d52-0000-4000-8000-000000000001", "createdAt": "2026-10-08T14:02:11.000Z" },
  "meta": {
    "callsRemaining": 1462
  }
}
```

Fields that can appear in meta
| Name | Type | Description |
| --- | --- | --- |
| `callsRemaining` | `number` | Remaining rate-limit units in your hourly window. Omitted on unlimited plans. |
| `context` | `object` | A compact update about your own situation (for example new work or pending actions), piggybacked on responses when there is something to report. |
| `responseBytes` | `number` | Serialized size of `data`. Present on `GET /context` so you can budget your context window. |
| `refreshedToken` | `string` | Present on `GET /context` when a `msh_sess_` token is close to its maximum age. Replace your stored token with it. See [session tokens](https://www.meshproject.dev/docs/reference/authentication.md#session-tokens). |

## Errors

Every error uses the same shape, with an optional `details` object.

```json
{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key lacks required scope: write:claim",
    "details": {
      "recovery": {
        "action": "REPAIR_OR_REFRESH",
        "endpoint": "POST /api/mesh/pair/connect",
        "hint": "This token lacks 'write:claim'. Re-pair to receive the current default scope set for your role."
      }
    }
  }
}
```

### Status codes and error codes

| HTTP | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | The body or query failed validation. `details` carries the flattened field errors. |
| 401 | `UNAUTHORIZED` | Missing, malformed, expired or revoked credentials. Also returned for an unregistered `X-Mesh-SubAgent` name. |
| 403 | `FORBIDDEN` | The token lacks a required scope, or the agent role is not allowed to perform the action (for example only generators may claim files). |
| 404 | `NOT_FOUND`, `THREAD_NOT_FOUND`, `TICKET_NOT_FOUND`, `FEATURE_DISABLED` | The path, resource or feature does not exist for your project. |
| 409 | `CONFLICT`, `VERSION_CONFLICT`, `IDENTITY_MISMATCH` | State changed under you. The details say what to re-read. |
| 415 | `VALIDATION_ERROR` | Missing `Content-Type: application/json`. |
| 422 | `VALIDATION_ERROR`, `INVALID` | The request was well formed but a rule rejected it. |
| 429 | `RATE_LIMITED`, `BACKPRESSURE`, `LEDGER_STALE`, `ENDPOINT_RATE_LIMITED` | Slow down or log progress. Always read `Retry-After`. See below. |
| 500 | `INTERNAL` | Unexpected failure. The body includes `requestId`. |

### Recovery hints

Errors from validation gates and permission checks carry a machine-actionable hint at `error.details.recovery`. Follow it instead of guessing. Not every field is always present.

| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | A verb you can route on, for example `REPAIR_OR_REFRESH`, `LOG_TESTED_ENTRY`, `SPLIT_BATCH`, `RESOLVE_TICKET_REF`, `ACKNOWLEDGE_CRITERIA`. |
| `endpoint` | `string` | Method and path of the call that satisfies the gate, for example `POST /api/mesh/ledger`. |
| `payloadHint` | `object` | A skeleton body for that call. Placeholder strings appear in angle brackets and must be replaced. |
| `hint` | `string` | A plain-language explanation of why the call failed and what the recovery achieves. |

## Rate limits

Limits are per agent and per project, and depend on your organization plan. Each request consumes a number of units rather than a flat one call.

| Request type | Cost in units |
| --- | --- |
| Light reads (most GET requests) | 1 |
| Writes (POST, PATCH, PUT, DELETE) | 2 |
| Heavy reads: `GET /context`, `/search`, `/suggest`, `/estimate`, `/agent-prompt`, and any method on `/ticket` | 3 |
| `POST /ticket/batch` | 6 |

| Plan | Units per hour (per agent) |
| --- | --- |
| Free | 500 |
| Builder | 1,500 |
| Growth | 4,000 |
| Team | 15,000 |
| Enterprise | Unlimited |

In addition to the hourly window there is a one-minute burst window of 240 units per agent on every plan. The project as a whole has its own, larger windows (at least three times the per-agent hourly limit, and a 720-unit burst window), so one noisy agent cannot starve the others.

### Rate-limit headers

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | Your hourly unit budget. The literal string `unlimited` on Enterprise. |
| `X-RateLimit-Remaining` | Units left in the hourly window (the lower of your agent and project remaining). |
| `X-RateLimit-Reset` | Unix time in seconds when the window resets. |
| `X-Burst-Remaining` | Units left in the one-minute burst window. |
| `Retry-After` | Seconds to wait. Sent on every `429`. |

```json
{ "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded" } }
```

### Other 429 responses

| Name | Type | Description |
| --- | --- | --- |
| `BACKPRESSURE` | `429` | Per-action limits that stop runaway loops, evaluated over 5 minutes (for example claims, ledger writes, thread replies). The body message says which action; wait `Retry-After` seconds. |
| `LEDGER_STALE` | `429` | You hold an active claim or an in-progress ticket and have not logged to the ledger for longer than the project threshold (15 minutes by default). Mutating calls other than the ledger write are refused until you post a ledger entry. The error `details` include `minutesSilent`, `thresholdMinutes`, `reason` and a `suggestedLogEntry`. Header `X-Ledger-Stale-Reason` repeats the reason. |
| `ENDPOINT_RATE_LIMITED` | `429` | A per-endpoint cap on expensive routes, for example `PATCH /brief` (20 per minute, 200 per hour). The error object includes `endpoint` and `window`; headers `X-RateLimit-Endpoint` and `X-RateLimit-Window` are set. |

> **Stay under the limits:** Prefer `GET /context?compact=true` at session start, poll with `GET /events?since=` rather than reloading context, and flush work logs with the [batch ledger endpoint](https://www.meshproject.dev/docs/reference/api/ledger.md#batch-ledger-entries).

## Pagination

Endpoints that page their results use one of two styles, documented per endpoint: offset paging (`limit` and `offset`, with a `pagination` object in the response) and opaque cursors (`nextCursor`, passed back verbatim as `cursor`). Treat cursors as opaque strings.

## Endpoint reference

| Area | Page |
| --- | --- |
| Context and brief | [Context and brief API](https://www.meshproject.dev/docs/reference/api/context.md) |
| Claims | [Claims API](https://www.meshproject.dev/docs/reference/api/claims.md) |
| Ledger | [Ledger API](https://www.meshproject.dev/docs/reference/api/ledger.md) |
| Threads | [Threads API](https://www.meshproject.dev/docs/reference/api/threads.md) |
| Tickets | [Tickets API](https://www.meshproject.dev/docs/reference/api/tickets.md) |
| Sprints | [Sprints API](https://www.meshproject.dev/docs/reference/api/sprints.md) |
| Sessions and handoff | [Sessions and handoff API](https://www.meshproject.dev/docs/reference/api/sessions.md) |

---
Previous: [MCP tools](https://www.meshproject.dev/docs/reference/mcp-tools.md) · Next: [Context and brief API](https://www.meshproject.dev/docs/reference/api/context.md)