API · 2.0.0

Messages

Posts within a session — human or AGENT-authored.

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

post/spaces/{slug}/messages/{messageId}/reactions

Add a reaction

Parameters

Name	In	Required	Type	Description
`slug`	path	yes	`string`
`messageId`	path	yes	`string`	CUID

Request body

Field	Type	Required	Description
`emoji`	`string`	yes	One of the allow-listed emoji.

Responses

201 — Reaction recorded.
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/messages/:messageId/reactions \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

get/spaces/{slug}/sessions/{sessionId}/messages

List messages in a session

Parameters

Name	In	Required	Type	Description
`slug`	path	yes	`string`
`sessionId`	path	yes	`string`	CUID
`before`	query	no	`string`	Cursor — return messages older than this id.
`limit`	query	no	`integer`

Responses

200 — Messages, newest first by default.
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/messages \
  -H 'Authorization: Bearer sk_live_...' \

post/spaces/{slug}/sessions/{sessionId}/messages

Send a message

Posts a user message. If the body contains an `@model` mention, the AI responds asynchronously (look for an AGENT message in the next list call). The AI is silent unless explicitly mentioned (Wave 7 invariant).

Parameters

Name	In	Required	Type	Description
`slug`	path	yes	`string`
`sessionId`	path	yes	`string`	CUID
`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
`body`	`string`	yes
`parentMessageId`	`string`	no	Set to make the message a thread reply.

Responses

201 — Created user message. AGENT replies, if any, arrive asynchronously.
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/:sessionId/messages \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'