API · 2.0.0
Sessions
Conversation threads inside a Project.
5 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
/spaces/{slug}/sessionsList sessions in a Project
Auth: your signed-in session (cookie __Secure-next-auth.session-token). API keys are not accepted.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
slug | path | yes | string |
Responses
200- Sessions.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/spaces/:slug/sessions \
-H 'Cookie: __Secure-next-auth.session-token=<session cookie>'post
/spaces/{slug}/sessionsCreate a session
Auth: your signed-in session (cookie __Secure-next-auth.session-token). API keys are not accepted.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
slug | path | yes | string | |
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 | Description |
|---|---|---|---|
name | string | yes | |
description | string | no | |
participantUserIds | string[] | no | |
defaultAgent | string | no | Slug of the default model/agent. |
Responses
201- Created session.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/spaces/:slug/sessions \
-H 'Cookie: __Secure-next-auth.session-token=<session cookie>' \
-H 'Content-Type: application/json' \
-d '{ ... }'get
/spaces/{slug}/sessions/{sessionId}Get a session
Auth: your signed-in session (cookie __Secure-next-auth.session-token). API keys are not accepted.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
slug | path | yes | string | |
sessionId | path | yes | string | CUID |
Responses
200- The session.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/spaces/:slug/sessions/:sessionId \
-H 'Cookie: __Secure-next-auth.session-token=<session cookie>'patch
/spaces/{slug}/sessions/{sessionId}Update a session
Auth: your signed-in session (cookie __Secure-next-auth.session-token). API keys are not accepted.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
slug | path | yes | string | |
sessionId | path | yes | string | CUID |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
title | string | no | |
model | string | no |
Responses
200- Updated session.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 PATCH https://switchy.build/api/spaces/:slug/sessions/:sessionId \
-H 'Cookie: __Secure-next-auth.session-token=<session cookie>' \
-H 'Content-Type: application/json' \
-d '{ ... }'delete
/spaces/{slug}/sessions/{sessionId}Archive a session
Soft-deletes the session. Messages remain in the DB for audit.
Auth: your signed-in session (cookie __Secure-next-auth.session-token). API keys are not accepted.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
slug | path | yes | string | |
sessionId | path | yes | string | CUID |
Responses
204- Archived. No body.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 DELETE https://switchy.build/api/spaces/:slug/sessions/:sessionId \
-H 'Cookie: __Secure-next-auth.session-token=<session cookie>'