API · 2.0.0
Org
Members + invitations.
6 operations. All requests need Authorization: Bearer sk_.... Responses use the standard envelope; see overview for shapes and error codes.
post
/invitations/{token}/acceptAccept an invitation
Public endpoint — token is unguessable and one-time-use. Caller must be authenticated as the invitee email or the request fails 403.
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— 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/invitations/:token/accept \
-H 'Authorization: Bearer sk_live_...' \get
/org/{orgId}/invitationsList pending invitations
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— 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/org/:orgId/invitations \
-H 'Authorization: Bearer sk_live_...' \post
/org/{orgId}/invitationsInvite a teammate
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— 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/org/:orgId/invitations \
-H 'Authorization: Bearer sk_live_...' \
-H 'Content-Type: application/json' \
-d '{ ... }'get
/org/{orgId}/membersList org members
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— 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/org/:orgId/members \
-H 'Authorization: Bearer sk_live_...' \patch
/org/{orgId}/members/{userId}Change a member's role
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— 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/org/:orgId/members/:userId \
-H 'Authorization: Bearer sk_live_...' \
-H 'Content-Type: application/json' \
-d '{ ... }'delete
/org/{orgId}/members/{userId}Remove a member from the org
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— 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/org/:orgId/members/:userId \
-H 'Authorization: Bearer sk_live_...' \