Switchy
Sign up
API · 2.0.0

Spaces

Projects (formerly "Spaces") — containers of scoped memory, Slack/Teams channel mappings, and tasks 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 Projects

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

Parameters

NameInRequiredTypeDescription
pagequerynointeger
limitquerynointeger

Responses

  • 200 - Paginated list of Projects.
  • 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 Project

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 Project.
  • 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 Project

Parameters

NameInRequiredTypeDescription
projectIdpathyesstringCUID

Responses

  • 200 - The Project.
  • 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→