API Reference

The LobstaCloud REST API lets you programmatically manage instances, team members, API keys, and organization settings.

Base URL: https://cloud.redlobsta.com/api

Authentication

All API requests require authentication. There are two methods:

Session Cookie (Browser)

When signed in via the web dashboard, requests use a NextAuth session cookie automatically.

API Key (Programmatic)

For programmatic access, use an API key in the Authorization header:

Authorization: Bearer lob_your_api_key_here

API keys are generated from the dashboard or via the API Keys endpoint. Keys start with the prefix lob_.

curl -H "Authorization: Bearer lob_abc123..." \
  https://cloud.redlobsta.com/api/instances

Error Handling

All errors return a JSON object with an error field. Validation errors include additional details:

{
  "error": "Invalid request",
  "details": [
    {
      "code": "too_small",
      "minimum": 1,
      "type": "string",
      "message": "String must contain at least 1 character(s)",
      "path": ["name"]
    }
  ]
}

Instances

List Instances

GET /api/instances

Returns all instances across all organizations the authenticated user belongs to.

Response: 200 OK

[
  {
    "id": "clxyz123abc",
    "name": "my-lobsta",
    "status": "RUNNING",
    "region": "us-east-1",
    "tier": "PRO",
    "memoryMb": 2048,
    "storageMb": 10240,
    "gatewayUrl": "https://lobsta-clxyz123abc.run.app",
    "gatewayToken": "gw_token_...",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:01:00.000Z",
    "lastActiveAt": "2025-01-16T08:30:00.000Z",
    "organizationId": "clorg456def",
    "organizationName": "My Team",
    "organizationSlug": "my-team"
  }
]

Create Instance

POST /api/instances

Field	Type	Required	Description
`name`	string	✓	Instance name. Lowercase alphanumeric and hyphens. 1–50 chars. Pattern: `^[a-z0-9-]+$`
`region`	string	✓	Deployment region (e.g., `us-east-1`)
`tier`	string	✓	One of: `STARTER`, `PRO`, `BUSINESS`

curl -X POST https://cloud.redlobsta.com/api/instances \
  -H "Authorization: Bearer lob_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-bot",
    "region": "us-east-1",
    "tier": "PRO"
  }'

Response: 201 Created

{
  "id": "clxyz789ghi",
  "name": "production-bot",
  "status": "PROVISIONING",
  "region": "us-east-1",
  "tier": "PRO",
  "memoryMb": 2048,
  "storageMb": 10240,
  "gatewayUrl": null,
  "gatewayToken": null,
  "createdAt": "2025-01-16T12:00:00.000Z"
}

Status	Error	Cause
`400`	Invalid request	Validation failed
`401`	Unauthorized	Not authenticated
`403`	Instance limit reached	Plan limit exceeded
`500`	Failed to create instance	Server error

Get Instance Details

GET /api/instances/:id

Returns full instance details including recent logs and metrics.

Response: 200 OK — includes logs (last 50 entries) and metrics (last 100 data points).

Update Instance

PATCH /api/instances/:id

Field	Type	Description
`name`	string	New instance name (same validation as create)
`tier`	string	New tier: `STARTER`, `PRO`, or `BUSINESS`

curl -X PATCH https://cloud.redlobsta.com/api/instances/clxyz123abc \
  -H "Authorization: Bearer lob_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "renamed-bot"}'

Delete Instance

DELETE /api/instances/:id

Permanently deletes the instance and deprovisions its Cloud Run service.

Required Role: OWNER or ADMIN

Response: 200 OK — { "success": true }

Instance Actions

Perform Action

POST /api/instances/:id/actions

Field	Type	Required	Description
`action`	string	✓	One of: `start`, `stop`, `restart`

Action Rules:

Action	Required Current Status	Result Status
`start`	`STOPPED`	`RUNNING`
`stop`	`RUNNING`	`STOPPED`
`restart`	`RUNNING`	`RUNNING`

curl -X POST https://cloud.redlobsta.com/api/instances/clxyz123abc/actions \
  -H "Authorization: Bearer lob_..." \
  -H "Content-Type: application/json" \
  -d '{"action": "restart"}'

Team Members

List Team Members

GET /api/team

Returns all members of your organization with their roles.

Invite a Member

POST /api/team

Required Role: OWNER or ADMIN

Field	Type	Required	Description
`email`	string	✓	Email address of the person to invite
`role`	string	✓	One of: `ADMIN`, `MEMBER`

curl -X POST https://cloud.redlobsta.com/api/team \
  -H "Authorization: Bearer lob_..." \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "role": "MEMBER"}'

Remove a Member

DELETE /api/team/:memberId

Required Role: OWNER or ADMIN

API Keys

List API Keys

GET /api/api-keys

Returns all API keys for the user's organization (metadata only — key hashes are never returned).

Create API Key

POST /api/api-keys

Required Role: OWNER or ADMIN

Field	Type	Required	Description
`name`	string	✓	A label for the key (1–100 characters)
`expiresInDays`	number	—	Days until expiration (1–365)

⚠️

The key field is only returned on creation. Store it immediately — the server stores only a SHA-256 hash.

Revoke API Key

DELETE /api/api-keys/:id

Required Role: OWNER or ADMIN

Organization Settings

Get Settings

GET /api/settings

Update Settings

PATCH /api/settings

Required Role: OWNER or ADMIN

Field	Type	Description
`name`	string	New organization name (1–100 characters)

Delete Organization

DELETE /api/settings

Required Role: OWNER only. Permanently deletes the organization and all associated data.

Billing

Create Checkout Session

POST /api/stripe/checkout

Field	Type	Required	Description
`plan`	string	✓	One of: `STARTER`, `PRO`, `BUSINESS`
`annual`	boolean	—	`true` for annual billing (2 months free)

Response: 200 OK — returns { "url": "https://checkout.stripe.com/..." }. Redirect the user to complete payment.

Rate Limits

Scope	Limit
Authenticated API requests	100 requests/minute per API key
Instance creation	10 per hour per organization
Team invitations	20 per hour per organization

When rate-limited, you'll receive a 429 Too Many Requests response.

Error Codes Reference

HTTP Status	Error	Description
`400`	Invalid request	Request body failed validation
`401`	Unauthorized	Missing or invalid authentication
`403`	Insufficient permissions	Role lacks required permissions
`403`	Instance limit reached	Plan instance limit exceeded
`404`	Not found	Resource doesn't exist or no access
`409`	Already exists	Duplicate resource (e.g., team invite)
`429`	Too many requests	Rate limit exceeded
`500`	Server error	Internal server error

Billing & Plans