Workspaces API

Workspaces are the operational containers within an organization. Each workspace contains projects, members, integrations, and budget settings. Workspaces belong to an Organization and inherit its shared configurations.

TIP

For organization-level management (members, invitations, budgets, integrations), see the Organizations API.

Create Workspace

POST /api/v1/workspaces
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "My Team",
  "organization_id": "uuid",
  "description": "Product engineering team",
  "budget_monthly_limit_usd": 500,
  "budget_alert_threshold": 0.8
}

Response 201 Created

{
  "id": "uuid",
  "name": "My Team",
  "workspace_key": "my-team",
  "description": "Product engineering team",
  "owner_id": "uuid",
  "budget_monthly_limit_usd": 500.0,
  "budget_alert_threshold": 0.8,
  "created_at": "2026-01-01T00:00:00Z"
}

List Workspaces

Returns all workspaces the current user is a member of.

GET /api/v1/workspaces
Authorization: Bearer <token>

Get Workspace

GET /api/v1/workspaces/{workspace_id}
Authorization: Bearer <token>

Update Workspace

Requires admin role or higher.

PUT /api/v1/workspaces/{workspace_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Renamed Team",
  "budget_monthly_limit_usd": 1000
}

Members

List Members

GET /api/v1/workspaces/{workspace_id}/members
Authorization: Bearer <token>

Response 200 OK

[
  {
    "user_id": "uuid",
    "user_name": "Alice",
    "user_email": "alice@example.com",
    "role": "admin",
    "joined_at": "2026-01-01T00:00:00Z"
  }
]

Add Member

Requires admin role. Adds an existing user by email.

POST /api/v1/workspaces/{workspace_id}/members
Authorization: Bearer <token>
Content-Type: application/json

{
  "email": "bob@example.com",
  "role": "developer"
}

Change Role

Requires admin role. Only the owner can change admin roles.

PUT /api/v1/workspaces/{workspace_id}/members/{member_user_id}
Authorization: Bearer <token>
Content-Type: application/json

{ "role": "viewer" }

Remove Member

DELETE /api/v1/workspaces/{workspace_id}/members/{member_user_id}
Authorization: Bearer <token>

Transfer Ownership

Only the current owner can transfer ownership.

POST /api/v1/workspaces/{workspace_id}/transfer-ownership
Authorization: Bearer <token>
Content-Type: application/json

{ "new_owner_id": "uuid" }

Audit Logs

Requires admin role. Returns paginated audit log entries.

GET /api/v1/workspaces/{workspace_id}/audit-logs?page=1&page_size=20
Authorization: Bearer <token>

Query Parameters

Parameter	Type	Description
action	string	Filter by action (e.g. project.created)
actor_id	UUID	Filter by actor
resource_type	string	Filter by resource type
start_date	datetime	Start of date range
end_date	datetime	End of date range
page	int	Page number (default 1)
page_size	int	Items per page (default 20)

Response 200 OK

{
  "total": 150,
  "page": 1,
  "page_size": 20,
  "items": [
    {
      "id": "uuid",
      "actor_type": "human",
      "actor_id": "uuid",
      "action": "project.created",
      "resource_type": "project",
      "resource_id": "uuid",
      "detail": "Created project 'My App'",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}