Switchy
Open app
API · 2.0.0

Spaces

Shared chat rooms inside an org. Internally still called "projects" in URLs (see migration guide).

3 operations. All requests need Authorization: Bearer sk_.... Responses use the standard envelope; see overview for shapes and error codes.

get/projects

List Spaces

Returns Spaces visible to the caller in the active org. Pagination via `page` and `limit`.

Parameters

NameInRequiredTypeDescription
pagequerynointeger
limitquerynointeger

Responses

  • 200 — Paginated list of Spaces.
  • 400 — Validation failed. `error.code = VALIDATION_ERROR`. `error.details.errors` lists per-field issues from zod.
  • 401 — Missing or invalid auth. `error.code = AUTH_ERROR`.
  • 403 — Authenticated but not allowed (wrong role, not a member, or org scope mismatch). `error.code = FORBIDDEN`.
  • 404 — Resource does not exist or is invisible to the caller. `error.code = NOT_FOUND`.
  • 409 — Conflict — duplicate slug, race condition, or invalid state transition. `error.code = CONFLICT`.
  • 429 — Rate limit exceeded. `error.code = RATE_LIMIT`. Retry after the window listed in `Retry-After`.
  • 500 — Unexpected server error. `error.code = INTERNAL_ERROR`. Logged with the `requestId` echoed in metadata.
cURL example
curl -X GET https://switchy.build/api/projects \
  -H 'Authorization: Bearer sk_live_...' \
post/projects

Create a Space

Parameters

NameInRequiredTypeDescription
Idempotency-KeyheadernostringOpaque client-generated UUID. The first request wins; identical follow-ups within 24h return the original response. Recommended on all POST endpoints.

Request body

FieldTypeRequiredDescription
namestringyes
descriptionstringno
tagsstring[]no

Responses

  • 201 — Created Space.
  • 400 — Validation failed. `error.code = VALIDATION_ERROR`. `error.details.errors` lists per-field issues from zod.
  • 401 — Missing or invalid auth. `error.code = AUTH_ERROR`.
  • 403 — Authenticated but not allowed (wrong role, not a member, or org scope mismatch). `error.code = FORBIDDEN`.
  • 404 — Resource does not exist or is invisible to the caller. `error.code = NOT_FOUND`.
  • 409 — Conflict — duplicate slug, race condition, or invalid state transition. `error.code = CONFLICT`.
  • 429 — Rate limit exceeded. `error.code = RATE_LIMIT`. Retry after the window listed in `Retry-After`.
  • 500 — Unexpected server error. `error.code = INTERNAL_ERROR`. Logged with the `requestId` echoed in metadata.
cURL example
curl -X POST https://switchy.build/api/projects \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
get/projects/{projectId}

Get a Space

Parameters

NameInRequiredTypeDescription
projectIdpathyesstringCUID

Responses

  • 200 — The Space.
  • 400 — Validation failed. `error.code = VALIDATION_ERROR`. `error.details.errors` lists per-field issues from zod.
  • 401 — Missing or invalid auth. `error.code = AUTH_ERROR`.
  • 403 — Authenticated but not allowed (wrong role, not a member, or org scope mismatch). `error.code = FORBIDDEN`.
  • 404 — Resource does not exist or is invisible to the caller. `error.code = NOT_FOUND`.
  • 409 — Conflict — duplicate slug, race condition, or invalid state transition. `error.code = CONFLICT`.
  • 429 — Rate limit exceeded. `error.code = RATE_LIMIT`. Retry after the window listed in `Retry-After`.
  • 500 — Unexpected server error. `error.code = INTERNAL_ERROR`. Logged with the `requestId` echoed in metadata.
cURL example
curl -X GET https://switchy.build/api/projects/:projectId \
  -H 'Authorization: Bearer sk_live_...' \
←PreviousAPI overviewNextSessions→