Workspaces API

Workspaces are the primary multi-tenant isolation boundary in SignalSmith. Each workspace contains its own sources, models, destinations, syncs, audiences, and other resources. Users can belong to multiple workspaces.

Endpoints

List Workspaces

GET /api/v1/workspaces

Returns all workspaces the authenticated user is a member of. This endpoint does not require the X-Workspace-ID header.

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production",
    "slug": "production",
    "avatar_url": "",
    "default_role": "member",
    "settings": {},
    "organization_id": "660e8400-e29b-41d4-a716-446655440000",
    "member_count": 12,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "name": "Staging",
    "slug": "staging",
    "avatar_url": "",
    "default_role": "member",
    "settings": {},
    "organization_id": "660e8400-e29b-41d4-a716-446655440000",
    "member_count": 5,
    "created_at": "2024-01-05T00:00:00Z",
    "updated_at": "2024-01-10T09:30:00Z"
  }
]

Example

curl -X GET https://your-instance.signalsmith.io/api/v1/workspaces \
  -H "Authorization: Bearer <token>"

Create Workspace

POST /api/v1/workspaces

Creates a new workspace. The authenticated user becomes the workspace owner. This endpoint does not require the X-Workspace-ID header.

Request Body

{
  "name": "Production",
  "slug": "production"
}

Response

Returns the created workspace with status 201 Created.

Example

curl -X POST https://your-instance.signalsmith.io/api/v1/workspaces \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "slug": "production"
  }'

Get Workspace

GET /api/v1/workspaces/{id}

Returns a single workspace by ID. The authenticated user must be a member of the workspace.

Example

curl -X GET https://your-instance.signalsmith.io/api/v1/workspaces/{id} \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>"

Update Workspace

PUT /api/v1/workspaces/{id}

Updates workspace details. Requires owner or admin role.

Request Body

Delete Workspace

DELETE /api/v1/workspaces/{id}

Deletes a workspace and all of its resources. Requires owner role. This action is irreversible.

Response

{
  "status": "deleted"
}

List Members

GET /api/v1/workspaces/{id}/members

Returns all members of the workspace with their roles and account details.

Response

[
  {
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
    "account_id": "660e8400-e29b-41d4-a716-446655440000",
    "role": "owner",
    "role_id": "00000000-0000-0000-0000-000000000001",
    "email": "alice@example.com",
    "name": "Alice Smith",
    "avatar_url": "https://...",
    "created_at": "2024-01-01T00:00:00Z"
  },
  {
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
    "account_id": "770e8400-e29b-41d4-a716-446655440000",
    "role": "member",
    "role_id": "00000000-0000-0000-0000-000000000003",
    "email": "bob@example.com",
    "name": "Bob Jones",
    "avatar_url": "https://...",
    "created_at": "2024-01-05T00:00:00Z"
  }
]

Example

curl -X GET https://your-instance.signalsmith.io/api/v1/workspaces/{id}/members \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>"

Add Member

POST /api/v1/workspaces/{id}/members

Adds an existing account as a member of the workspace. Requires owner or admin role.

Request Body

Update Member Role

PUT /api/v1/workspaces/{id}/members/{accountId}

Changes a member’s role within the workspace.

Request Body

Remove Member

DELETE /api/v1/workspaces/{id}/members/{accountId}

Removes a member from the workspace. Owners cannot be removed unless ownership is transferred first.

Response

{
  "status": "deleted"
}

Workspace Settings

Get Settings

GET /api/v1/workspaces/{id}/settings

Returns workspace-level configuration settings.

Update Settings

PUT /api/v1/workspaces/{id}/settings

Updates workspace settings. Requires owner or admin role.

Invitations

Send Invitation

POST /api/v1/workspaces/{id}/invitations

Sends an email invitation to join the workspace.

Request Body

{
  "email": "newuser@example.com",
  "role": "member"
}

List Invitations

GET /api/v1/workspaces/{id}/invitations

Returns all pending invitations for the workspace.

Cancel Invitation

DELETE /api/v1/workspaces/{id}/invitations/{inviteId}

Cancels a pending invitation.

Workspace Object

Workspace Member Object