API · 2.0.0
Org
Members + invitations.
6 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.
post
/invitations/{token}/acceptAccept an invitation
Requires a signed-in session whose email matches the invitation, otherwise 403 `EMAIL_MISMATCH`. The token is unguessable and single-use: a missing, expired, revoked, or already-accepted token returns 410 `INVITATION_INVALID`.
Auth: your signed-in session (cookie __Secure-next-auth.session-token). API keys are not accepted.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
token | path | yes | string |
Responses
200- Accepted; caller is now a member.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/invitations/:token/accept \
-H 'Cookie: __Secure-next-auth.session-token=<session cookie>'get
/org/{orgId}/invitationsList pending invitations
Auth: your signed-in session (cookie __Secure-next-auth.session-token). API keys are not accepted.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
orgId | path | yes | string | CUID |
Responses
200- Invitations.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/org/:orgId/invitations \
-H 'Cookie: __Secure-next-auth.session-token=<session cookie>'post
/org/{orgId}/invitationsInvite a teammate
Auth: your signed-in session (cookie __Secure-next-auth.session-token). API keys are not accepted.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
orgId | 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 |
|---|---|---|---|
email | string | yes | Invitee email. |
role | "ADMIN" | "MEMBER" | yes |
Responses
201- Invitation created and emailed.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/org/:orgId/invitations \
-H 'Cookie: __Secure-next-auth.session-token=<session cookie>' \
-H 'Content-Type: application/json' \
-d '{ ... }'get
/org/{orgId}/membersList org members
Auth: your signed-in session (cookie __Secure-next-auth.session-token). API keys are not accepted.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
orgId | path | yes | string | CUID |
Responses
200- Members.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/org/:orgId/members \
-H 'Cookie: __Secure-next-auth.session-token=<session cookie>'patch
/org/{orgId}/members/{userId}Change a member's role
Auth: your signed-in session (cookie __Secure-next-auth.session-token). API keys are not accepted.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
orgId | path | yes | string | CUID |
userId | path | yes | string | CUID |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
role | Role | yes |
Responses
200- Updated member.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/org/:orgId/members/:userId \
-H 'Cookie: __Secure-next-auth.session-token=<session cookie>' \
-H 'Content-Type: application/json' \
-d '{ ... }'delete
/org/{orgId}/members/{userId}Remove a member from the org
Auth: your signed-in session (cookie __Secure-next-auth.session-token). API keys are not accepted.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
orgId | path | yes | string | CUID |
userId | path | yes | string | CUID |
Responses
204- Removed.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/org/:orgId/members/:userId \
-H 'Cookie: __Secure-next-auth.session-token=<session cookie>'