API Overview

Authentication, base URL, rate limits, error handling, and pagination for the Outpost REST API

The Outpost REST API provides programmatic access to repositories, machines, services, jobs, namespaces, SSH keys, secrets, and more. All requests and responses use JSON.

Base URL

All API requests are made relative to the /auth/v1/ base path:

https://outpost.run/auth/v1/

https://outpost.run/auth/v1/

All endpoint paths in this documentation are relative to the base URL. For example, GET /auth/v1/users means:

GET https://outpost.run/auth/v1/users

GET https://outpost.run/auth/v1/users

Authentication

The Outpost API supports two authentication methods: Bearer tokens and API keys. Both are passed via the Authorization header.

Bearer token

Obtain a Bearer token by authenticating through the OAuth/OIDC flow or by creating a Personal Access Token (PAT). Include it in the Authorization header:

curl https://outpost.run/auth/v1/users 
  -H "Authorization: Bearer <access_token>"

curl https://outpost.run/auth/v1/users 
  -H "Authorization: Bearer <access_token>"

API key

Generate an API key from the Outpost dashboard under Settings > API Keys. API keys use the format key_name$key_secret and are passed with the API-Key scheme:

curl https://outpost.run/auth/v1/users 
  -H "Authorization: API-Key my-key$sk_live_a1b2c3d4e5f6g7h8i9j0"

curl https://outpost.run/auth/v1/users 
  -H "Authorization: API-Key my-key$sk_live_a1b2c3d4e5f6g7h8i9j0"

Keep your credentials safe

Never commit tokens or API keys to version control. Rotate keys immediately if compromised. API keys can be managed via the `/auth/v1/api_keys` endpoints.

Personal Access Tokens

You can also create and manage Personal Access Tokens (PATs) programmatically:

# Create a new PAT
curl -X POST https://outpost.run/auth/v1/pat 
  -H "Authorization: Bearer <access_token>" 
  -H "Content-Type: application/json" 
  -d '{"name": "ci-token", "expires_in_days": 90}'

# Create a new PAT
curl -X POST https://outpost.run/auth/v1/pat 
  -H "Authorization: Bearer <access_token>" 
  -H "Content-Type: application/json" 
  -d '{"name": "ci-token", "expires_in_days": 90}'

# List your PAT
curl https://outpost.run/auth/v1/pat/ci-token 
  -H "Authorization: Bearer <access_token>"

# List your PAT
curl https://outpost.run/auth/v1/pat/ci-token 
  -H "Authorization: Bearer <access_token>"

Content type

All requests with a body must include the Content-Type: application/json header. All responses return JSON.

curl -X POST https://outpost.run/auth/v1/acme/repositories 
  -H "Authorization: Bearer <access_token>" 
  -H "Content-Type: application/json" 
  -d '{"name": "my-repo", "visibility": "private"}'

curl -X POST https://outpost.run/auth/v1/acme/repositories 
  -H "Authorization: Bearer <access_token>" 
  -H "Content-Type: application/json" 
  -d '{"name": "my-repo", "visibility": "private"}'

Rate limits

API requests are rate-limited per authentication credential:

Plan	Rate limit	Burst limit
Free	60 requests/min	10 req/s
Team	300 requests/min	30 req/s
Enterprise	1,000 requests/min	100 req/s

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1710764400

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1710764400

When you exceed the rate limit, the API returns 429:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "retry_after": 12
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "retry_after": 12
  }
}

Error format

All errors follow a consistent JSON structure:

{
  "error": {
    "code": "not_found",
    "message": "Repository 'acme/nonexistent' not found.",
    "request_id": "req_8f3a2b1c4d5e"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Repository 'acme/nonexistent' not found.",
    "request_id": "req_8f3a2b1c4d5e"
  }
}

HTTP status codes

Status	Badge	Description
200	200	Request succeeded
201	201	Resource created
204	204	Resource deleted (no content)
400	400	Bad request -- invalid parameters
401	401	Unauthorized -- missing or invalid credentials
403	403	Forbidden -- insufficient permissions
404	404	Not found -- resource does not exist
409	409	Conflict -- resource already exists
422	422	Unprocessable entity -- validation error
429	429	Rate limit exceeded
500	500	Internal server error

Common error codes

Error code	Description
`invalid_request`	The request body is malformed or missing required fields
`authentication_failed`	The provided credentials are invalid or expired
`permission_denied`	The authenticated user lacks permission for this action
`not_found`	The requested resource does not exist
`already_exists`	A resource with the same identifier already exists
`rate_limit_exceeded`	Too many requests in the current window
`quota_exceeded`	Account quota for this resource type has been reached

Pagination

List endpoints return paginated results. Use the page and per_page query parameters to control pagination.

curl "https://outpost.run/auth/v1/acme/repositories?page=2&per_page=25" 
  -H "Authorization: Bearer <access_token>"

curl "https://outpost.run/auth/v1/acme/repositories?page=2&per_page=25" 
  -H "Authorization: Bearer <access_token>"

Paginated responses include metadata in the response body:

{
  "data": [],
  "pagination": {
    "page": 2,
    "per_page": 25,
    "total": 142,
    "total_pages": 6
  }
}

{
  "data": [],
  "pagination": {
    "page": 2,
    "per_page": 25,
    "total": 142,
    "total_pages": 6
  }
}

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-indexed)
`per_page`	integer	`20`	Items per page (max 100)

Versioning

The API is versioned via the URL path. The current version is v1. All endpoints are prefixed with /auth/v1/.

Health and diagnostics

You can check the API health status and version without authentication:

GET `/auth/v1/health` -- Health check

curl https://outpost.run/auth/v1/health

{
  "status": "ok"
}

{
  "status": "ok"
}

GET `/auth/v1/version` -- Get API version

curl https://outpost.run/auth/v1/version

GET `/auth/v1/whoami` -- Get the currently authenticated user

curl https://outpost.run/auth/v1/whoami 
  -H "Authorization: Bearer <access_token>"

curl https://outpost.run/auth/v1/whoami 
  -H "Authorization: Bearer <access_token>"

{
  "user_id": "usr_3f8a1b2c",
  "username": "jane",
  "email": "[email protected]",
  "namespace": "acme"
}

{
  "user_id": "usr_3f8a1b2c",
  "username": "jane",
  "email": "[email protected]",
  "namespace": "acme"
}

API reference

Repositories -- Create, list, and manage Git repositories
Machines -- Provision and control development machines
Services -- Deploy and scale production services
Jobs -- Submit and monitor batch jobs

Next Repositories →