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, each listing how it authenticates. This is the session-authenticated API the web app uses; if you have an API key, use the v1 API instead (see the overview). Responses use the standard envelope; the overview also covers shapes and error codes.

get/projects

List Projects

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

Auth: your signed-in session (cookie __Secure-next-auth.session-token). API keys are not accepted.

Parameters

Name	In	Required	Type	Description
`page`	query	no	`integer`
`limit`	query	no	`integer`

Responses

200 - Paginated list of Projects.
400 - Validation failed. `error.code = VALIDATION_ERROR`. `error.details.errors` lists per-field issues from zod.
401 - No valid credentials for this operation's `security` requirement. `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 'Cookie: __Secure-next-auth.session-token=<session cookie>'

post/projects

Create a Project

Auth: your signed-in session (cookie __Secure-next-auth.session-token). API keys are not accepted.

Parameters

Name	In	Required	Type	Description
`Idempotency-Key`	header	no	`string`	Opaque client-generated UUID. The first request wins; identical follow-ups within 24h return the original response. Recommended on all POST endpoints.

Request body

Field	Type	Required
`name`	`string`	yes
`description`	`string`	no
`tags`	`string[]`	no

Responses

201 - Created Project.
400 - Validation failed. `error.code = VALIDATION_ERROR`. `error.details.errors` lists per-field issues from zod.
401 - No valid credentials for this operation's `security` requirement. `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 'Cookie: __Secure-next-auth.session-token=<session cookie>' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

get/projects/{projectId}

Get a Project

Auth: your signed-in session (cookie __Secure-next-auth.session-token). API keys are not accepted.

Parameters

Name	In	Required	Type	Description
`projectId`	path	yes	`string`	CUID

Responses

200 - The Project.
400 - Validation failed. `error.code = VALIDATION_ERROR`. `error.details.errors` lists per-field issues from zod.
401 - No valid credentials for this operation's `security` requirement. `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 'Cookie: __Secure-next-auth.session-token=<session cookie>'