Workspaces

A workspace is an isolated environment with its own API keys, bots, recordings, members, webhooks, and billing. This guide covers how to manage your workspace via the API.

Getting your workspace

Every API key is scoped to exactly one workspace. To get your workspace details, use:

bash

curl https://api.serveka.com/api/v1/workspace/me \
  -H "X-API-Key: srvk_your_key_here"

Response 200:

json

{
  "id": "aaaaaaaa-0000-0000-0000-000000000001",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "settings": {},
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-05-12T10:00:00Z"
}

Save your workspace id (UUID) — you'll need it for workspace-scoped operations like managing members and webhooks.

Updating your workspace

Update your workspace name or settings with PATCH /api/v1/workspaces/{workspace_id}:

bash

curl -X PATCH https://api.serveka.com/api/v1/workspaces/aaaaaaaa-0000-0000-0000-000000000001 \
  -H "X-API-Key: srvk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp Global",
    "settings": { "region": "us-east-1" }
  }'

Response 200:

json

{
  "id": "aaaaaaaa-0000-0000-0000-000000000001",
  "name": "Acme Corp Global",
  "slug": "acme-corp",
  "settings": { "region": "us-east-1" },
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-05-12T10:00:00Z"
}

Note: Settings are merged — keys not included in the request are preserved.

Permission required: admin or owner role. member role cannot update workspaces.

Listing workspace members

See all members of your workspace with their roles and join dates:

bash

curl https://api.serveka.com/api/v1/workspaces/aaaaaaaa-0000-0000-0000-000000000001/members \
  -H "X-API-Key: srvk_your_key_here"

Response 200:

json

[
  {
    "user_id": 1,
    "email": "alice@acme.com",
    "name": "Alice",
    "role": "owner",
    "joined_at": "2026-01-01T00:00:00Z"
  },
  {
    "user_id": 2,
    "email": "bob@acme.com",
    "name": "Bob",
    "role": "member",
    "joined_at": "2026-03-15T09:00:00Z"
  }
]

Inviting a member

Invite someone to your workspace by email:

bash

curl -X POST https://api.serveka.com/api/v1/workspaces/aaaaaaaa-0000-0000-0000-000000000001/members \
  -H "X-API-Key: srvk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@acme.com",
    "role": "member"
  }'

Response 201:

json

{
  "id": "bbbbbbbb-0000-0000-0000-000000000002",
  "workspace_id": "aaaaaaaa-0000-0000-0000-000000000001",
  "email": "newuser@acme.com",
  "role": "member",
  "status": "pending",
  "created_at": "2026-05-12T10:00:00Z",
  "expires_at": "2026-05-19T10:00:00Z"
}

The invitee gets a 7-day link to accept. If a pending invitation already exists for that email, the expiry is refreshed and the role updated (upsert behavior).

Permission required: admin or owner role. member role cannot invite members.

Changing a member's role

Update an existing member's role (only workspace owners can do this):

bash

curl -X PATCH https://api.serveka.com/api/v1/workspaces/aaaaaaaa-0000-0000-0000-000000000001/members/2 \
  -H "X-API-Key: srvk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin"
  }'

Response 200:

json

{
  "user_id": 2,
  "email": "bob@acme.com",
  "name": "Bob",
  "role": "admin",
  "joined_at": "2026-03-15T09:00:00Z"
}

Permission required: owner role only. admin role cannot change other members' roles.

Removing a member

Remove a member from your workspace:

bash

curl -X DELETE https://api.serveka.com/api/v1/workspaces/aaaaaaaa-0000-0000-0000-000000000001/members/2 \
  -H "X-API-Key: srvk_your_key_here"

Response 204: No content

Permission required: admin or owner role. You cannot remove yourself. You cannot remove an owner unless you are also an owner.

Listing pending invitations

See all outstanding invitations:

bash

curl https://api.serveka.com/api/v1/workspaces/aaaaaaaa-0000-0000-0000-000000000001/invitations \
  -H "X-API-Key: srvk_your_key_here"

Response 200:

json

[
  {
    "id": "bbbbbbbb-0000-0000-0000-000000000002",
    "workspace_id": "aaaaaaaa-0000-0000-0000-000000000001",
    "email": "newuser@acme.com",
    "role": "member",
    "status": "pending",
    "created_at": "2026-05-12T10:00:00Z",
    "expires_at": "2026-05-19T10:00:00Z"
  }
]

Revoking an invitation

Cancel a pending invitation before it's accepted:

bash

curl -X DELETE https://api.serveka.com/api/v1/workspaces/aaaaaaaa-0000-0000-0000-000000000001/invitations/bbbbbbbb-0000-0000-0000-000000000002 \
  -H "X-API-Key: srvk_your_key_here"

Response 204: No content

Permission required: admin or owner role. You cannot revoke already-accepted or already-revoked invitations.

Workspace roles and permissions

Role	Can do
`member`	Read all resources in the workspace (GET endpoints)
`admin`	Read + create/update/delete bots, meetings, API keys
`owner`	Full access including member management, webhooks, workspace settings

When you create an API key, it inherits the role of the user who created it. A key created by an admin has admin-level access.

Every API key is bound to exactly one workspace. The workspace is resolved automatically from the key — you never pass workspace_id in request bodies for resource operations (the exception is webhook endpoints, which use it as a path parameter for historical reasons).