Workspace API

The Workspace API provides information about your workspace's plan, usage, and session context. It also includes owner-only management operations like ownership transfer and workspace deletion.

Note

For a user guide on workspace settings in the dashboard, see Workspace Settings.

Endpoints

Method	Path	Description
`GET`	`/v1/workspace`	Get workspace info, limits, and live usage
`GET`	`/v1/workspace/me`	Get current session info (role, permissions)
`POST`	`/v1/workspace/transfer-ownership`	Transfer ownership to another admin
`POST`	`/v1/workspace/delete`	Schedule workspace deletion

Get Workspace Info

Returns the current workspace's plan, limits (from the plans table), and live usage counters computed from source tables.

bash

curl "https://synapse-api.pyrx.tech/v1/workspace" \

-H "Authorization: Bearer <jwt>"

Auth: JWT (dashboard). Any authenticated member.

Response

json

{

"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",

"name": "PYRX Insurance",

"plan": "growth",

"monthly_email_limit": 100000,

"contacts_limit": 100000,

"monthly_events_limit": 1000000,

"flows_limit": 100,

"data_retention_days": 365,

"monthly_emails_sent": 24530,

"contacts_count": 18420,

"monthly_events_used": 156200,

"events_today": 3842,

"active_flows_count": 12

}

Field	Description
`monthly_email_limit`	Max emails per month for the current plan
`contacts_limit`	Max contacts allowed
`monthly_events_limit`	Max events per month
`flows_limit`	Max flows allowed (`-1` = unlimited)
`data_retention_days`	How long event data is retained
`monthly_emails_sent`	Emails queued this calendar month (live count)
`contacts_count`	Total contacts in the workspace (live count)
`monthly_events_used`	Events ingested this calendar month (live count)
`events_today`	Events ingested today (live count)
`active_flows_count`	Number of flows with `active` status (live count)

Get Session Info

Returns the current user's workspace context, role, and permissions. Useful for the dashboard to determine what UI elements to show based on the user's role.

bash

curl "https://synapse-api.pyrx.tech/v1/workspace/me" \

-H "Authorization: Bearer <jwt>"

Auth: JWT (dashboard). Any authenticated member.

Response

json

{

"workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",

"workspace_name": "PYRX Insurance",

"role": "admin",

"permissions": [

"analytics:read",

"contacts:read",

"contacts:write",

"flows:read",

"flows:write",

"logs:read",

"segments:read",

"segments:write",

"settings:read",

"settings:write",

"templates:read",

"templates:write",

"users:read",

"users:write"

"default_from_email": "[email protected]",

"default_sender_name": "PYRX Insurance",

"email_verified": true

}

Field	Description
`role`	One of `owner`, `admin`, `developer`, `marketing`, `operations`, `viewer`
`permissions`	Full list of granted permissions for this role
`default_from_email`	Workspace's default sender email address
`default_sender_name`	Workspace's default sender display name
`email_verified`	Whether the user's email is verified (fetched from pyrx.auth)

Transfers workspace ownership from the current owner to another member. The target member must already be an admin in the workspace. After transfer, the previous owner is demoted to admin and the new owner receives the owner role.

bash

curl -X POST https://synapse-api.pyrx.tech/v1/workspace/transfer-ownership \

-H "Authorization: Bearer <jwt>" \

-H "Content-Type: application/json" \

-d '{

"new_owner_member_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"

Auth: JWT (dashboard). Requires ownership:transfer permission (owner only).

Request Body

Field	Type	Required	Description
`new_owner_member_id`	UUID	Yes	The member ID of the new owner (must be an active admin)

Response (200)

json

{

"status": "transferred",

"new_owner": "b2c3d4e5-f6a7-8901-bcde-f12345678901"

}

Error Responses

400 -- Invalid transfer target:

json

{

"detail": "Target member must be an active admin"

}

403 -- Not the owner:

json

{

"detail": "Only the owner can transfer ownership"

}

Warning

Ownership transfer is immediate and cannot be undone without the new owner transferring it back. Each workspace has exactly one owner, enforced by a database unique constraint.

Delete Workspace

Schedules the workspace for deletion with a 30-day grace period. During the grace period, the workspace can be recovered by contacting support.

bash

curl -X POST https://synapse-api.pyrx.tech/v1/workspace/delete \

-H "Authorization: Bearer <jwt>" \

-H "Content-Type: application/json" \

-d '{

"confirm_workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Auth: JWT (dashboard). Requires workspace:delete permission (owner only).

Request Body

Field	Type	Required	Description
`confirm_workspace_id`	string	Yes	Must match the current workspace ID (safety confirmation)

Response (200)

json

{

"status": "deletion_scheduled",

"deletion_date": "2026-05-25T00:00:00",

"message": "Workspace will be permanently deleted in 30 days."

}

Error Responses

400 -- Confirmation mismatch:

json

{

"detail": "Workspace ID confirmation does not match"

}

403 -- Not the owner:

json

{

"detail": "Only the owner can delete the workspace"

}

Warning

Workspace deletion is irreversible after the 30-day grace period. All contacts, events, flows, templates, and email logs will be permanently deleted. Cancel any active subscriptions before deleting the workspace.

RBAC Reference

Role	Workspace Info	Session Info	Transfer Ownership	Delete Workspace
Owner	Yes	Yes	Yes	Yes
Admin	Yes	Yes	No	No
Developer	Yes	Yes	No	No
Marketing	Yes	Yes	No	No
Operations	Yes	Yes	No	No
Viewer	Yes	Yes	No	No