Skip to main content
The Depot HTTP API provides programmatic access to Git repository management, file operations, commits, and branches. It’s designed for AI agents, automation pipelines, and CI/CD integrations.

​
Base URL

All API endpoints are available at: 
https://depot.mesa.dev/api/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://depot.mesa.dev/api/v1/{org}/repos
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_branch": "main"
}
Example requesting raw file content: 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/octet-stream" \
  https://depot.mesa.dev/api/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
BRANCH_NOT_FOUND404Branch does not exist
COMMIT_NOT_FOUND404Commit SHA not found
FILE_NOT_FOUND404File path not found
REPO_EXISTS409Repository already exists
BRANCH_EXISTS409Branch already exists
INVALID_REQUEST400Malformed request body or parameters
QUOTA_EXCEEDED413Storage quota exceeded

​
Scopes

API keys have scoped permissions that control access:
ScopeDescription
git:readRead repository content, branches, commits
git:writePush commits, create/delete branches
repo:readList and view repository metadata
repo:createCreate new repositories
repo:deleteDelete repositories
adminFull access including API key management
The admin scope grants all permissions. The git:write scope includes git:read.