Python SDK

Official Python SDK for the Weavz API.

Python SDK

The official Python SDK provides a clean, Pythonic interface for the Weavz API.

Installation

bash
pip install weavz-sdk

Quick Start

python
from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
# Execute an action
result = client.actions.execute(
    "slack",
    "send_channel_message",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    integration_alias="slack_bot",
    input={"channel": "#general", "text": "Hello from Weavz!"},
)
 
print("Message sent:", result["output"])

Configuration

python
client = WeavzClient(
    api_key="wvz_your_api_key",
    base_url="https://api.weavz.io",  # Default
    timeout=30.0,                      # Request timeout in seconds
    max_retries=2,                     # Retry count for transient failures
)
OptionRequiredDefaultDescription
api_keyYes—Your API key (wvz_... prefix)
base_urlNohttps://api.weavz.ioAPI base URL
timeoutNo30.0Request timeout in seconds
max_retriesNo2Number of retries for transient failures

Context Manager

The client supports Python's context manager protocol to automatically close the HTTP connection:

python
with WeavzClient(api_key="wvz_your_key") as client:
    result = client.actions.execute(
        "slack",
        "send_channel_message",
        workspace_id="550e8400-e29b-41d4-a716-446655440000",
        input={
            "channel": "#general",
            "text": "Hello!",
        },
    )
# Connection automatically closed

You can also close manually:

python
client = WeavzClient(api_key="wvz_your_key")
try:
    # ... use client ...
    pass
finally:
    client.close()

Resources

The client exposes namespaced resources for each API area:

ResourceMethodsDescription
client.workspaceslist, create, get, update, delete, list_integrations, add_integration, update_integration, remove_integrationWorkspace management
client.connectionslist, get, create, delete, resolveConnection management
client.actionsexecuteExecute integration actions
client.triggerslist, enable, disable, testTrigger management
client.mcp_serverslist, create, get, update, delete, regenerate_token, create_bearer_token, create_access_token, create_end_user_token, create_oauth_token, add_tool, update_tool, delete_tool, execute_code, get_declarationsMCP server management
client.api_keyslist, create, deleteAPI key management
client.integrationslist, list_summary, get, resolve_options, resolve_property, oauth_statusIntegration metadata
client.connectcreate_token, poll, wait, get_sessionHosted connect flow
client.end_userscreate, list, get, update, delete, create_connect_token, inviteEnd-user identity and connect portal management
client.partialslist, get, create, update, delete, set_defaultInput partial presets
client.approval_policieslist, create, get, update, delete, testHuman Gates policy management
client.approvalslist, get, approve, reject, cancel, waitApproval request inbox and decisions

Common Operations

Managing Workspaces

python
# List workspaces
result = client.workspaces.list()
for ws in result["workspaces"]:
    print(ws["name"])
 
# Create a workspace
result = client.workspaces.create(name="My Workspace", slug="my-workspace")
workspace_id = result["workspace"]["id"]
 
# Delete a workspace
client.workspaces.delete(workspace_id)

Tenant Configuration APIs

Use org-wide API keys for control-plane setup when you are building your own SaaS on top of Weavz.

python
workspace = client.workspaces.create(name="Production", slug="production")["workspace"]
 
client.workspaces.add_integration(
    workspace["id"],
    integration_name="slack",
    integration_alias="customer_slack",
    connection_strategy="per_user",
)

Managing Connections

python
# Create an API key connection
result = client.connections.create(
    type="SECRET_TEXT",
    integration_name="openai",
    external_id="tenant_123_openai",
    display_name="OpenAI Key",
    secret_text="sk-...",
)
 
# Resolve a connection
resolved = client.connections.resolve(
    integration_name="openai",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    external_id="tenant_123_openai",
)
 
# Delete a connection
client.connections.delete(result["connection"]["id"])

Executing Actions

python
result = client.actions.execute(
    "github",
    "create_issue",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    integration_alias="github_prod",
    input={
        "repository": "my-org/my-repo",
        "title": "Bug Report",
        "body": "Something went wrong",
        "labels": "bug",
    },
)
 
print("Issue created:", result["output"])

Managing MCP Servers

python
workspace_id = "550e8400-e29b-41d4-a716-446655440000"
 
# Add built-ins to the workspace once. MCP servers sync workspace integrations automatically.
client.workspaces.add_integration(
    workspace_id,
    integration_name="datetime",
    integration_alias="datetime",
)
client.workspaces.add_integration(
    workspace_id,
    integration_name="hash-encode",
    integration_alias="hash",
)
 
# Create a Code Mode MCP server for broad agent workspaces
result = client.mcp_servers.create(
    name="AI Agent Workspace",
    mode="CODE",
    workspace_id=workspace_id,
    auth_mode="oauth_and_bearer",
    end_user_access="restricted",
    settings={"codeMode": {"approvalWaitSeconds": 30}},
)
server_id = result["server"]["id"]
endpoint = result["mcpEndpoint"]
 
# Give a known end user programmatic bearer MCP access
token_result = client.mcp_servers.create_bearer_token(
    server_id,
    end_user_id="user_123",
    scopes=["mcp:tools", "mcp:code"],
    expires_in=60 * 60 * 24 * 30,
)
bearer_token = token_result["bearerToken"]
user_endpoint = token_result["mcpEndpoint"]
 
# Run Code Mode from your own harness
run = client.mcp_servers.execute_code(
    server_id,
    """
const parsed = await weavz.datetime.parse_date({ dateString: "2026-05-18" })
const digest = await weavz.hash.hash({ text: parsed.iso, algorithm: "sha256", encoding: "hex" })
return { parsed, digest }
""",
)
 
# If Human Gates pauses the run, approve it and fetch the stored result.
approved_run = client.mcp_servers.execute_code(
    server_id,
    approval_id="apr_9b36d3f761d84bb2b6f9a0c4b9d1f7e0",
    wait_for_approval_seconds=30,
)
 
# Use Tool Mode when you want a small explicit surface instead of Code Mode.
client.workspaces.add_integration(
    workspace_id,
    integration_name="slack",
    integration_alias="slack_bot",
    enabled_actions=["send_channel_message"],
)
tool_server = client.mcp_servers.create(
    name="Focused Slack Tools",
    mode="TOOLS",
    workspace_id=workspace_id,
    auth_mode="oauth",
)["server"]

New MCP servers use OAuth by default. Bearer-enabled servers can issue API-created mcp_ tokens scoped to one end user through create_bearer_token(). Shared static bearer tokens are returned only when auth_mode is bearer or oauth_and_bearer and the workspace can safely use service-style access.

Code Mode is the default recommendation for broad agent workspaces. It exposes weavz_search, weavz_read_api, and weavz_execute, while get_declarations() returns full TypeScript declarations with JSDoc and return types. If code passes the wrong input shape, execute_code() returns a tool error with validation details instead of a generic failure. Use Tool Mode for small explicit tool surfaces.

Managing Triggers

python
# Enable a trigger
result = client.triggers.enable(
    integration_name="github",
    trigger_name="new_push",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    callback_url="https://yourapp.com/webhooks/github",
    integration_alias="github_prod",
)
trigger_id = result["triggerSource"]["id"]
 
# List active triggers
result = client.triggers.list()
for trigger in result["triggers"]:
    print(f"{trigger['integrationName']}.{trigger['triggerName']}")
 
# Disable a trigger
client.triggers.disable(trigger_id)

Managing Input Partials

python
# Create a partial (saved parameter preset)
result = client.partials.create(
    name="Default Slack Channel",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    integration_name="slack",
    integration_alias="slack_bot",
    action_name="send_channel_message",
    values={"channel": "#general"},
    enforced_keys=["channel"],
)
partial = result["partial"]
 
# List partials for a workspace
result = client.partials.list(workspace_id="550e8400-e29b-41d4-a716-446655440000")
 
# Set as default for this action scope
client.partials.set_default(partial["id"], is_default=True)
 
# Use partial with action execution
result = client.actions.execute(
    "slack",
    "send_channel_message",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    integration_alias="slack_bot",
    partial_ids=[partial["id"]],
    input={"text": "Hello!"},  # channel comes from the partial
)
 
# Delete a partial
client.partials.delete(partial["id"])

Hosted Connect Flow

Use the hosted connect page to create OAuth2 connections. Create a token, open the connect page, and poll for the result:

python
# Step 1: Create a connect token
result = client.connect.create_token(
    integration_name="google-sheets",
    connection_name="Google Sheets",
    external_id="tenant_123_gsheets",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
)
token = result["token"]
connect_url = result["connectUrl"]
# result also contains: expiresAt
 
# Step 2: Open connect_url in a browser popup to complete authorization
status = client.connect.wait(token)
if status["status"] == "COMPLETED":
    print("Connection created:", status["connectionId"])

Error Handling

All API errors raise WeavzError with structured error information:

python
from weavz_sdk import WeavzClient, WeavzError
 
client = WeavzClient(api_key="wvz_your_key")
 
try:
    client.actions.execute(
        "slack", "send_channel_message",
        workspace_id="550e8400-e29b-41d4-a716-446655440000",
        input={"channel": "invalid", "text": "Hello!"},
    )
except WeavzError as e:
    print(f"Message: {e}")         # Human-readable error message
    print(f"Code: {e.code}")       # Machine-readable code (e.g., "ACTION_FAILED")
    print(f"Status: {e.status}")   # HTTP status code (e.g., 400)
    print(f"Details: {e.details}") # Additional details (if available)

Common Error Codes

CodeDescription
VALIDATION_ERRORInvalid request parameters
ACTION_FAILEDAction execution failed
CONNECTION_REQUIREDAction needs a connection
CONNECTION_NOT_FOUNDConnection doesn't exist
INTEGRATION_NOT_FOUNDInvalid integration name
QUOTA_EXCEEDEDMonthly usage limit reached
RATE_LIMITEDToo many requests

Type Hints

The Python SDK includes type hints for all resource methods and typed models for shared objects. You get IDE autocomplete for method parameters and common response shapes.

Key Types

python
from weavz_sdk import WeavzClient, WeavzError
from weavz_sdk.models import (
    InputPartial,
    WorkspaceIntegration,
)
TypeDescription
WeavzClientMain client class with all resource methods
WeavzErrorException class with message, code, status, details
InputPartialPartial preset with values, enforced_keys, is_default
WorkspaceIntegrationIntegration instance on a workspace with alias and connection strategy

Integration Input Types

The SDK ships with generated Pydantic models for all 500+ integration action inputs:

python
from weavz_sdk.integrations import (
    # Slack
    SlackSendChannelMessageInput,
    SlackSendDirectMessageInput,
    # GitHub
    GithubCreateIssueInput,
    GithubCreatePullRequestInput,
    # Google Sheets
    GoogleSheetsInsertRowInput,
    GoogleSheetsReadRowsInput,
    # ... all integrations follow the same pattern
)
 
# Validated input with autocomplete
input_data = SlackSendChannelMessageInput(
    channel="#general",
    text="Typed input!",
)
 
client.actions.execute(
    "slack",
    "send_channel_message",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    input=input_data,
)

The naming pattern is {IntegrationName}{ActionName}Input in PascalCase.

AI Framework Adapters

MCP is the primary hosted surface for giving agents access to Weavz. Framework adapters are a compatibility layer for teams that are embedding Weavz into their own agent runtime and need the same configured workspace actions in a framework-native tool format.

The adapters do not expose dashboard administration or platform internals. They transform customer-facing workspace action schemas into the shape each framework expects, then execute through client.actions.execute() with your API key. Framework packages stay optional.

python
import os
from weavz_sdk import (
    WeavzClient,
    create_mcp_server_action_tools,
    to_openai_responses_tool,
    to_anthropic_tool,
    to_google_function_declaration,
    to_google_adk_tool,
)
 
client = WeavzClient(api_key=os.environ["WEAVZ_API_KEY"])
tools = create_mcp_server_action_tools(client, "660e8400-e29b-41d4-a716-446655440000")
 
openai_tools = [to_openai_responses_tool(tool) for tool in tools]
anthropic_tools = [to_anthropic_tool(tool) for tool in tools]
google_functions = [to_google_function_declaration(tool) for tool in tools]
google_adk_tools = [to_google_adk_tool(tool) for tool in tools]  # Requires google-adk

For LangChain, install langchain-core and call to_langchain_tool(tool). For Google ADK, install google-adk and call to_google_adk_tool(tool). For manual loops, use create_tool_executor() to route model tool calls back through client.actions.execute().

Python Version

The SDK requires Python 3.10 or later and depends on: