Public API · Overview & authentication

OctopusLab exposes a REST API at https://octopuslabapi-production.up.railway.app/api/v1 for programmatic access on behalf of an organization. v1 is small and stable: list / create projects, list deployments, list audits. More endpoints land as the platform grows; nothing in v1 will break.

Base URL

https://octopuslabapi-production.up.railway.app/api/v1

Public endpoints sit under /public/* and use API-key auth. Endpoints without /public/ are the dashboard backend and require a Supabase JWT — they're not meant for external use.

Generate an API key

  1. Open /app/settings → API keys.
  2. Type a name (e.g. CI deploy bot) and click Создать ключ.
  3. Copy the ok_… value displayed exactly once. There's no way to retrieve it later — if you lose it, revoke + create a new one.

Keys belong to an organization, not a user. They survive the user who created them getting removed from the org. Revoke via the trash icon next to the key row; revoked keys return 401 instantly.

Authentication

Set the Authorization header:

Authorization: Bearer ok_aB12c34D5e6F7g8H9i0J

Every request to /public/* is scoped to the org that owns the key — there's no cross-org access, no project hand-off, no impersonation.

Verify the key works

curl -H "Authorization: Bearer ok_…" \
  https://octopuslabapi-production.up.railway.app/api/v1/public/me

Returns the org's id, slug, name, plan, and the scopes on the calling key. If you get a 401 with "Invalid API key", double-check the prefix matches what's in Settings (the first 12 chars).

Errors

HTTP status codes follow standard REST conventions:

  • 200 — success, body is JSON.
  • 400 — malformed body. The response includes Zod issue details: which field, why.
  • 401 — missing or invalid Authorization header.
  • 403 — key is fine but the operation is not allowed (e.g. project slug conflict).
  • 404 — the resource doesn't exist for this org. Treated as a "not found" even if the id exists in another org.
  • 500 — bug on our side. Open an issue with the response body so we can trace it.

Rate limits

Today there are no hard rate limits beyond Postgres / sandbox concurrency. We watch per-key burn in the admin panel — if a key is wedged in a loop, we'll throttle it explicitly and email the org owner. A documented limit (req / minute per plan) ships with v1.1.

Versioning

We don't break v1. Anything that would break — different field names, different defaults — ships under /v2/*. Until then your ok_… keys will keep working.

Next

See Endpoint reference for every route in v1 with full request / response examples.