Workspaces API¶

Workspaces are the top-level organizational unit in Totis. Each workspace can contain multiple projects and team members.

Endpoints¶

Create Workspace¶

POST /api/v1/workspace

Create a new workspace. The authenticated user becomes the owner.

Request Body

{
  "workspaceName": "My Company",
  "image": "base64-encoded-image (optional)",
  "storageConfig": {
    "storageType": "CUSTOM",
    "accessKey": "your-access-key",
    "secretKey": "your-secret-key",
    "bucket": "your-bucket",
    "endpoint": "https://s3.example.com",
    "region": "us-east-1"
  }
}

Field	Type	Required	Description
`workspaceName`	string	Yes	Display name for the workspace
`image`	string	No	Base64-encoded workspace image
`storageConfig`	object	No	Custom S3 storage configuration
`storageConfig.storageType`	string	No	`DEFAULT` or `CUSTOM`

Response

{
  "workspaceId": "abc123xyz",
  "name": "My Company",
  "slug": "my-company",
  "maxUsers": 5,
  "maxProjects": 1,
  "maxStorage": 5368709120,
  "storageUsed": 0,
  "pictureUrl": null,
  "createdAt": "2024-01-15T10:30:00Z"
}

Get Workspace¶

GET /api/v1/workspace/{workspaceSlug}

Retrieve workspace details.

Path Parameters

Parameter	Type	Description
`workspaceSlug`	string	URL-safe workspace identifier

Response

{
  "workspaceId": "abc123xyz",
  "name": "My Company",
  "slug": "my-company",
  "maxUsers": 5,
  "maxProjects": 10,
  "maxStorage": 10737418240,
  "storageUsed": 1073741824,
  "pictureUrl": "https://cdn.usetotis.com/images/abc123.png",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-02-01T14:20:00Z"
}

Required Permission: WORKSPACE_READ

Update Workspace¶

POST /api/v1/workspace/{workspaceSlug}

Update workspace settings.

Path Parameters

Parameter	Type	Description
`workspaceSlug`	string	URL-safe workspace identifier

Request Body

{
  "workspaceName": "Updated Company Name",
  "image": "base64-encoded-image (optional)",
  "removeImage": false
}

Field	Type	Required	Description
`workspaceName`	string	Yes	New display name
`image`	string	No	New base64-encoded image
`removeImage`	boolean	No	Set to `true` to remove the image

Required Permission: WORKSPACE_EDIT

Delete Workspace¶

DELETE /api/v1/workspace/{workspaceSlug}

Delete a workspace. The workspace must have no projects.

Path Parameters

Parameter	Type	Description
`workspaceSlug`	string	URL-safe workspace identifier

Required Permission: WORKSPACE_DELETE

Cannot Be Undone

Workspace deletion is permanent. Ensure all projects are deleted first.

Error Responses

Status	Error	Description
400	`WORKSPACE_HAS_PROJECTS`	Delete all projects first

Get Workspace Project¶

GET /api/v1/workspace/{workspaceSlug}/project/{projectSlug}

Get a specific project within a workspace.

Path Parameters

Parameter	Type	Description
`workspaceSlug`	string	Workspace identifier
`projectSlug`	string	Project identifier

Required Permission: PROJECT_READ

List Workspace Members¶

GET /api/v1/workspace/{workspaceSlug}/members

List all members of a workspace.

Response

[
  {
    "userId": "user123",
    "email": "[email protected]",
    "displayName": "John Doe",
    "role": "OWNER",
    "invitationStatus": "ACCEPTED"
  },
  {
    "userId": "user456",
    "email": "[email protected]",
    "displayName": "Jane Smith",
    "role": "DEVELOPER",
    "invitationStatus": "ACCEPTED"
  }
]

Required Permission: WORKSPACE_READ

Invite User to Workspace¶

POST /api/v1/workspace/{workspaceSlug}/invite

Invite a user to join the workspace.

Request Body

{
  "email": "[email protected]",
  "role": "DEVELOPER"
}

Field	Type	Required	Description
`email`	string	Yes	Email of user to invite
`role`	string	Yes	Role to assign: `ADMIN`, `DEVELOPER`, or `VIEWER`

Required Permission: WORKSPACE_EDIT

User Must Exist

The invited user must already have a Totis account.

Update Member Role¶

PUT /api/v1/workspace/{workspaceSlug}/member/{userId}

Update a member's role within the workspace.

Request Body

{
  "workspaceRole": "ADMIN"
}

Available Roles

Role	Description
`OWNER`	Full control, can delete workspace
`ADMIN`	Manage members and settings
`DEVELOPER`	Create and manage builds
`VIEWER`	Read-only access

Required Permission: WORKSPACE_EDIT

Remove Member¶

DELETE /api/v1/workspace/{workspaceSlug}/member/{userId}

Remove a member from the workspace.

Path Parameters

Parameter	Type	Description
`workspaceSlug`	string	Workspace identifier
`userId`	string	ID of user to remove

Required Permission: WORKSPACE_EDIT

Error Responses

Status	Error	Description
400	`CANNOT_REMOVE_OWNER`	Owners cannot be removed
400	`CANNOT_REMOVE_SELF`	Use leave workspace instead