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"

[Warning] 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

Authentication

Tokens -- Create and manage service account tokens

Compute

Machines -- Provision and control cloud development machines
Services -- Deploy and scale production services
Jobs -- Submit and monitor batch compute jobs
Fleets -- Manage warm pools of pre-initialized nodes

Projects & Deployments

Projects -- Create and manage projects with git-based deployments
Environments -- Manage project environments and variables
Deployments -- Track and control deployment rollouts
Cron Jobs -- Schedule recurring tasks

Networking

Domains -- Custom domains with automatic TLS certificates
DNS Providers -- Configure DNS providers for domain management

Storage

Volumes -- Persistent block storage volumes
Storage -- Cloud object storage mounts (S3, GCS, Azure Blob)

Infrastructure

Catalog -- Browse instance types, GPU availability, and pricing
Registries -- Container registry credentials for private images
Git Providers -- Connect external Git providers

Observability & Events

Webhooks -- Real-time event notifications
Logs -- Search, stream, and manage logs

Source Control

Repositories -- Create, list, and manage Git repositories

Next Create a machine →