Skip to main content
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 SDK Overview.

​
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:
EndpointDefaultAlternative
GET /{org}/{repo}/contentapplication/json (base64 encoded)application/octet-stream (raw bytes)
GET /{org}/{repo}/diffapplication/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:
ParameterTypeDescription
limitnumberMaximum items to return (default: 50, max: 100)
cursorstringCursor 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

CodeHTTP StatusDescription
UNAUTHORIZED401Invalid or missing API key
FORBIDDEN403Valid key but insufficient permissions
REPO_NOT_FOUND404Repository does not exist
BOOKMARK_NOT_FOUND404Bookmark (branch) does not exist
COMMIT_NOT_FOUND404Commit SHA not found
FILE_NOT_FOUND404File path not found
REPO_EXISTS409Repository already exists
BOOKMARK_EXISTS409Bookmark (branch) already exists
MERGE_CONFLICT409Merge cannot be completed due to conflicts
INVALID_REQUEST400Malformed request body or parameters

​
Scopes

API keys have scoped permissions that control access:
ScopeDescription
readClone, fetch, and view repositories, branches, commits, and content
writeEverything read can do, plus push, create/update/delete repos, branches, and bookmarks
adminEverything write can do, plus API key management and webhook management
Scope hierarchy: admin → write → read. Each scope includes everything below it.