Overview - Mesa Docs

The Mesa HTTP API provides direct programmatic access to repository management, 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

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

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

See 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:

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

Example requesting raw file content:

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:

{
  "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 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 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 webhook management and other privileged operations

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