API · 2.0.0
Sessions
Conversation threads inside a Space.
5 operations. All requests need Authorization: Bearer sk_.... Responses use the standard envelope; see overview for shapes and error codes.
get
/spaces/{slug}/sessionsList sessions in a Space
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— 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/spaces/:slug/sessions \
-H 'Authorization: Bearer sk_live_...' \post
/spaces/{slug}/sessionsCreate a session
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— 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/spaces/:slug/sessions \
-H 'Authorization: Bearer sk_live_...' \
-H 'Content-Type: application/json' \
-d '{ ... }'get
/spaces/{slug}/sessions/{sessionId}Get a session
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— 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/spaces/:slug/sessions/:sessionId \
-H 'Authorization: Bearer sk_live_...' \patch
/spaces/{slug}/sessions/{sessionId}Update a session
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— 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 PATCH https://switchy.build/api/spaces/:slug/sessions/:sessionId \
-H 'Authorization: Bearer sk_live_...' \
-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.
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— 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 DELETE https://switchy.build/api/spaces/:slug/sessions/:sessionId \
-H 'Authorization: Bearer sk_live_...' \