Skip to main content

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

limit
i32
Number of results to return (max 100).
offset
i32
Number of results to skip.
Search query to filter results.
sort_key
&str
Field to sort by.
sort_order
&str
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

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

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);
    }
}