Workspaces API Guide
Learn how to manage workspaces using the Wacht Rust SDK.
Prerequisites
Before using any API methods, you must initialize the SDK:
use wacht :: WachtClient ;
#[tokio :: main]
async fn main () -> Result <(), Box < dyn std :: error :: Error >> {
// Initialize the client with an API key
let client = WachtClient :: new ( "wk_live_..." );
// Now you can use the API
Ok (())
}
List Workspaces
Retrieve a paginated list of workspaces from your deployment.
Basic List
use wacht :: WachtClient ;
let client = WachtClient :: new ( "wk_live_..." );
// Fetch all workspaces (default pagination)
let workspaces = client . workspaces () . fetch_workspaces ()
. send ()
. await ? ;
println! ( "Total workspaces: {}" , workspaces . data . len ());
for ws in workspaces . data {
println! ( "{} in {}" , ws . name, ws . organization_name);
}
With Pagination and Filters
use wacht :: WachtClient ;
let client = WachtClient :: new ( "wk_live_..." );
// Fetch workspaces with builder options
let workspaces = client . workspaces () . fetch_workspaces ()
. limit ( 50 )
. offset ( 0 )
. search ( "engineering" )
. sort_key ( "created_at" )
. sort_order ( "desc" )
. send ()
. await ? ;
println! ( "Has more: {}" , workspaces . has_more);
Builder Methods
Number of results to return (max 100).
Number of results to skip.
Search query to filter results.
Sort order (“asc” or “desc”).
Get Workspace Details
Retrieve complete information about a workspace.
use wacht :: WachtClient ;
let client = WachtClient :: new ( "wk_live_..." );
let details = client . workspaces () . fetch_workspace ( "workspace_123" )
. send ()
. await ? ;
println! ( "Workspace: {}" , details . name);
println! ( "Organization: {}" , details . organization_name);
println! ( "Description: {:?}" , details . description);
println! ( "Members: {}" , details . members_count);
Create Workspace
Create a new workspace in your deployment.
Basic Workspace Creation
use wacht :: WachtClient ;
use wacht :: models :: CreateWorkspaceRequest ;
let client = WachtClient :: new ( "wk_live_..." );
let workspace = client . workspaces () . create_workspace (
CreateWorkspaceRequest :: new ( "Engineering" . to_string ())
)
. send ()
. await ? ;
println! ( "Created workspace: {}" , workspace . id);
With Optional Fields
use wacht :: WachtClient ;
use wacht :: models :: CreateWorkspaceRequest ;
let client = WachtClient :: new ( "wk_live_..." );
let request = CreateWorkspaceRequest {
name : "Engineering" . to_string (),
description : Some ( "Engineering team workspace" . to_string ()),
public_metadata : Some ( serde_json :: json! ({
"department" : "Engineering" ,
"cost_center" : "ENG-001"
})),
private_metadata : Some ( serde_json :: json! ({
"internal_notes" : "Priority workspace"
})),
workspace_image : None ,
};
let workspace = client . workspaces () . create_workspace ( request )
. send ()
. await ? ;
request
CreateWorkspaceRequest
required
public_metadata
Option<serde_json::Value>
Public metadata.
private_metadata
Option<serde_json::Value>
Private metadata.
Update Workspace
Update an existing workspace’s information. Only provided fields will be updated.
use wacht :: WachtClient ;
use wacht :: models :: UpdateWorkspaceRequest ;
let client = WachtClient :: new ( "wk_live_..." );
let updated = client . workspaces () . update_workspace (
"workspace_123" ,
UpdateWorkspaceRequest {
name : Some ( "Engineering Team" . to_string ()),
description : Some ( "Updated description" . to_string ()),
public_metadata : Some ( serde_json :: json! ({ "updated" : true })),
.. Default :: default ()
}
)
. send ()
. await ? ;
Available Update Fields
request
UpdateWorkspaceRequest
required
Updated workspace description.
public_metadata
Option<serde_json::Value>
Public metadata.
private_metadata
Option<serde_json::Value>
Private metadata.
Delete Workspace
Permanently delete a workspace. This action cannot be undone.
use wacht :: WachtClient ;
let client = WachtClient :: new ( "wk_live_..." );
client . workspaces () . delete_workspace ( "workspace_123" )
. send ()
. await ? ;
Manage Workspace Members
List Members
use wacht :: WachtClient ;
let client = WachtClient :: new ( "wk_live_..." );
let members = client . workspaces () . members () . fetch_members ( "workspace_123" )
. limit ( 50 )
. send ()
. await ? ;
for member in members . data {
println! ( "{} - {}" , member . role . name, member . user . first_name);
}
Add Member
use wacht :: WachtClient ;
let client = WachtClient :: new ( "wk_live_..." );
// First get available roles to find the role ID
let roles = client . workspaces () . roles () . fetch_roles ( "workspace_123" )
. send ()
. await ? ;
let member = client . workspaces () . members () . add_member (
"workspace_123" ,
"user_456" ,
vec! [ roles . data[ 0 ] . id . clone ()]
)
. send ()
. await ? ;
println! ( "Added member: {}" , member . user . first_name);
Update Member
use wacht :: WachtClient ;
let client = WachtClient :: new ( "wk_live_..." );
let updated = client . workspaces () . members () . update_member ( "workspace_123" , "member_789" )
. role_ids ( vec! [ "new_role_id" . to_string ()])
. public_metadata ( serde_json :: json! ({ "updated" : true }))
. send ()
. await ? ;
Remove Member
use wacht :: WachtClient ;
let client = WachtClient :: new ( "wk_live_..." );
client . workspaces () . members () . remove_member ( "workspace_123" , "member_789" )
. send ()
. await ? ;
Manage Workspace Roles
List Roles
use wacht :: WachtClient ;
let client = WachtClient :: new ( "wk_live_..." );
let roles = client . workspaces () . roles () . fetch_roles ( "workspace_123" )
. send ()
. await ? ;
for role in roles . data {
println! ( "{} ({} permissions)" , role . name, role . permissions . len ());
}
Create Role
use wacht :: WachtClient ;
use wacht :: models :: CreateRoleRequest ;
let client = WachtClient :: new ( "wk_live_..." );
let role = client . workspaces () . roles () . create_role (
"workspace_123" ,
CreateRoleRequest {
name : "Editor" . to_string (),
description : Some ( "Can edit content" . to_string ()),
permissions : vec! [
"workspace:read" . to_string (),
"workspace:write" . to_string (),
],
}
)
. send ()
. await ? ;
println! ( "Created role: {}" , role . name);
Update Role
use wacht :: WachtClient ;
use wacht :: models :: UpdateRoleRequest ;
let client = WachtClient :: new ( "wk_live_..." );
let updated = client . workspaces () . roles () . update_role (
"workspace_123" ,
"role_456" ,
UpdateRoleRequest {
name : Some ( "Senior Editor" . to_string ()),
description : Some ( "Advanced editing permissions" . to_string ()),
permissions : Some ( vec! [
"workspace:read" . to_string (),
"workspace:write" . to_string (),
"workspace:delete" . to_string (),
]),
}
)
. send ()
. await ? ;
Delete Role
use wacht :: WachtClient ;
let client = WachtClient :: new ( "wk_live_..." );
client . workspaces () . roles () . delete_role ( "workspace_123" , "role_456" )
. send ()
. await ? ;
Error Handling
All SDK methods return a Result<T, Error>:
use wacht :: { Error , WachtClient };
let client = WachtClient :: new ( "wk_live_..." );
match client . workspaces () . fetch_workspace ( "invalid_id" ) . send () . await {
Ok ( details ) => println! ( "Workspace: {}" , details . name),
Err ( Error :: Api { status , message , .. }) => {
eprintln! ( "API Error {}: {}" , status , message );
}
Err ( Error :: Request ( e )) => {
eprintln! ( "Network error: {}" , e );
}
Err ( e ) => {
eprintln! ( "Other error: {}" , e );
}
}