Skip to Content
API ReferenceOverview

API Reference

LobsterCage provides a REST API for managing cages, environment variables, billing, and API keys programmatically.

Base URL

https://api.lobstercage.ai/v1

Authentication

All requests require a Bearer token in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lobstercage.ai/v1/cages

You can authenticate with either:

  • API key — Created via lobster apikeys create or the dashboard
  • Clerk JWT — Issued by the dashboard’s auth flow

Endpoints overview

Cages

MethodPathDescription
GET/cagesList all cages
POST/cagesCreate a new cage
GET/cages/{cageId}Get cage details
PUT/cages/{cageId}Update cage config
DELETE/cages/{cageId}Destroy a cage
POST/cages/{cageId}/startStart a cage
POST/cages/{cageId}/stopStop a cage
POST/cages/{cageId}/hibernateHibernate a cage

Environment variables

MethodPathDescription
GET/cages/{cageId}/envList env var names
PUT/cages/{cageId}/envSet env vars
DELETE/cages/{cageId}/env/{name}Delete an env var

Tunnels

MethodPathDescription
POST/cages/{cageId}/tunnelCreate a tunnel token (ssh, shell, port)
POST/cages/{cageId}/observeCreate an observer token
POST/cages/{cageId}/port-forwardCreate an HTTP proxy token

Billing

MethodPathDescription
GET/billing/statusCurrent balance and usage
POST/billing/portalGet Stripe portal URL

API Keys

MethodPathDescription
GET/apikeysList API keys
POST/apikeysCreate an API key
DELETE/apikeys/{keyId}Revoke an API key

Events

MethodPathDescription
GET/cages/{cageId}/eventsList cage audit events

Error format

All errors return JSON with a consistent shape:

{
  "error": {
    "code": "CAGE_NOT_FOUND",
    "message": "Cage with id 'abc123' not found"
  }
}

Rate limiting

API requests are rate-limited per API key using a sliding window. Current limits are returned in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1700000000
Messaging PlatformsTerms of Service