> ## 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

All API requests require authentication using a Bearer token. Include your API key in the `Authorization` header:

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

API keys can be created and managed through the [Dashboard](https://app.mesa.dev) or via the Admin API endpoints.

## 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 YOUR_API_KEY" \
  -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 API key                 |
| `FORBIDDEN`          | 403         | Valid key 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

API keys have scoped permissions that control access:

| Scope   | Description                                                                              |
| ------- | ---------------------------------------------------------------------------------------- |
| `read`  | Clone, fetch, and view repositories, branches, commits, and content                      |
| `write` | Everything `read` can do, plus push, create/update/delete repos, branches, and bookmarks |
| `admin` | Everything `write` can do, plus API key management and webhook management                |

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