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

# Overview

> Get started with the Mesa HTTP API.

The Mesa HTTP API provides direct programmatic access to repository management, API keys, file operations, and version control. Use one of our SDKs when you want a client library, or call the HTTP API directly when you want full control over requests and transport behavior.

<Tip>
  Looking for client libraries instead of raw HTTP requests? Start with the [TypeScript SDK reference](/content/reference/ts/index).
</Tip>

## Base URL

All API endpoints are available at:

```
https://api.mesa.dev/v1
```

## Authentication

Every API request carries a bearer credential in the `Authorization` header. For new integrations, use a short-lived access token:

```bash theme={null}
curl -H "Authorization: Bearer $MESA_ACCESS_TOKEN" \
  https://api.mesa.dev/v1/{org}/repo
```

API keys remain accepted for compatibility. See [Authentication](/content/concepts/authentication) for private keys and access-token minting.

## Request Format

* All request bodies should be JSON with `Content-Type: application/json`
* Path parameters use the format `/{org}/{repo}/...` where `org` is your organization slug
* Query parameters are used for filtering, pagination, and optional settings

## Response Format

Most endpoints return JSON responses. However, some endpoints support content negotiation via the `Accept` header to return alternative formats:

| Endpoint                    | Default                              | Alternative                            |
| --------------------------- | ------------------------------------ | -------------------------------------- |
| `GET /{org}/{repo}/content` | `application/json` (base64 encoded)  | `application/octet-stream` (raw bytes) |
| `GET /{org}/{repo}/diff`    | `application/json` (structured diff) | `text/plain` (raw unified diff)        |

Example JSON response:

```json theme={null}
{
  "id": "repo_123",
  "name": "my-repo",
  "default_bookmark": "main"
}
```

Example requesting raw file content:

```bash theme={null}
curl -H "Authorization: Bearer $MESA_ACCESS_TOKEN" \
  -H "Accept: application/octet-stream" \
  https://api.mesa.dev/v1/{org}/{repo}/content?path=README.md
```

## Pagination

List endpoints support cursor-based pagination:

| Parameter | Type   | Description                                     |
| --------- | ------ | ----------------------------------------------- |
| `limit`   | number | Maximum items to return (default: 50, max: 100) |
| `cursor`  | string | Cursor from previous response for next page     |

Paginated responses include:

```json theme={null}
{
  "items": [...],
  "next_cursor": "abc123",
  "has_more": true
}
```

## Error Handling

Errors return a consistent JSON structure with an appropriate HTTP status code:

```json theme={null}
{
  "error": {
    "code": "REPO_NOT_FOUND",
    "message": "Repository 'my-repo' not found"
  }
}
```

### Error Codes

| Code                 | HTTP Status | Description                                   |
| -------------------- | ----------- | --------------------------------------------- |
| `UNAUTHORIZED`       | 401         | Invalid or missing credential                 |
| `FORBIDDEN`          | 403         | Valid credential but insufficient permissions |
| `REPO_NOT_FOUND`     | 404         | Repository does not exist                     |
| `BOOKMARK_NOT_FOUND` | 404         | Bookmark (branch) does not exist              |
| `COMMIT_NOT_FOUND`   | 404         | Commit SHA not found                          |
| `FILE_NOT_FOUND`     | 404         | File path not found                           |
| `REPO_EXISTS`        | 409         | Repository already exists                     |
| `BOOKMARK_EXISTS`    | 409         | Bookmark (branch) already exists              |
| `MERGE_CONFLICT`     | 409         | Merge cannot be completed due to conflicts    |
| `INVALID_REQUEST`    | 400         | Malformed request body or parameters          |

Server errors (5xx) additionally include an `error.trace_id`. Quote it when reporting an issue.

## Scopes

Access tokens and compatible API keys use scoped permissions:

| Scope   | Description                                                               |
| ------- | ------------------------------------------------------------------------- |
| `read`  | View repositories, changes, bookmarks, and content                        |
| `write` | Modify repositories, changes, bookmarks, and content                      |
| `admin` | Everything `write` can do, plus API key management and webhook management |

Scope hierarchy: **`admin`** → **`write`** → **`read`**. Each scope includes everything below it.