Overview - Mesa Docs

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.

Looking for client libraries instead of raw HTTP requests? Start with the TypeScript SDK reference.

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:

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

API keys can be created and managed through the Dashboard 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:

{
  "id": "repo_123",
  "name": "my-repo",
  "default_bookmark": "main"
}

Example requesting raw file content:

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:

{
  "items": [...],
  "next_cursor": "abc123",
  "has_more": true
}

Error Handling

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

{
  "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.

​Base URL

​Authentication

​Request Format

​Response Format

​Pagination

​Error Handling

​Error Codes

​Scopes

Base URL

Authentication

Request Format

Response Format

Pagination

Error Handling

Error Codes

Scopes