Workspace Integrations

Configure integrations within workspaces, including connection strategies and action subsets.

Workspace Integrations

Workspace integrations define how an integration is configured within a workspace. Each workspace integration specifies which integration to use, how connections are resolved (the connection strategy), which actions are available, and an optional alias for disambiguation.

Built-in workspace integrations such as storage, kv-store, http, data-transformer, code, and advanced-code use the same API. Most do not require connectionId; configure their aliases, enabled actions, persistence, or execution policy here. See Built-In Workspace Integrations for the catalog.

List Workspace Integrations

GET/api/v1/workspaces/{workspaceId}/integrations

List all integrations configured for a workspace.

Path Parameters

Field	Type	Description
`workspaceId`	string (uuid)	Workspace ID

Response

json

{
  "integrations": [
    {
      "id": "7df5c03e-4df5-4b5f-95a7-5277d8f972db",
      "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "orgId": "550e8400-e29b-41d4-a716-446655440000",
      "integrationName": "slack",
      "alias": "slack",
      "displayName": "Team Slack",
      "connectionStrategy": "fixed",
      "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
      "enabledActions": null,
      "settings": {},
      "sortOrder": 0,
      "connectionStatus": "ACTIVE",
      "connectionDisplayName": "Slack Bot",
      "connectionExternalId": "slack_bot",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "total": 1
}

Example

bash

curl https://api.weavz.io/api/v1/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/integrations \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { integrations } = await client.workspaces.listIntegrations('a1b2c3d4-e5f6-7890-abcd-ef1234567890')

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.workspaces.list_integrations("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
integrations = result["integrations"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/integrations', {
  headers: { 'Authorization': 'Bearer wvz_your_api_key' },
})
const data = await res.json()

python

import httpx
 
res = httpx.get(
    "https://api.weavz.io/api/v1/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/integrations",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
data = res.json()

Create Workspace Integration

POST/api/v1/workspaces/{workspaceId}/integrations

Add an integration to a workspace with a connection strategy.

Path Parameters

Field	Type	Description
`workspaceId`	string (uuid)	Workspace ID

Request Body

Field	Type	Required	Description
`integrationName`	string	Yes	Catalog integration name (e.g., `slack`, `github`)
`alias`	string	No	Alias for this integration instance (defaults to `integrationName`). Useful when the same integration is configured multiple times with different connections.
`connectionStrategy`	string	No	One of: `fixed`, `per_user`, `per_user_with_fallback`. Defaults to `fixed`
`connectionId`	string (uuid)	No	Connection ID. Required for `fixed` and `per_user_with_fallback` strategies.
`displayName`	string	No	Friendly label shown in the dashboard and connect surfaces
`enabledActions`	string[]	No	Restrict to specific actions. `null` or omitted means all actions are available.
`settings`	object	No	Owner-controlled integration settings. For `advanced-code`, use `settings.advancedCode` to configure execution policy.
`sortOrder`	number	No	Optional ordering hint for dashboard and generated surfaces

Response (201)

json

{
  "integration": {
    "id": "7df5c03e-4df5-4b5f-95a7-5277d8f972db",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "integrationName": "slack",
    "alias": "slack",
    "displayName": "Team Slack",
    "connectionStrategy": "fixed",
    "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    "enabledActions": null,
    "settings": {},
    "sortOrder": 0,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

Example

bash

curl -X POST https://api.weavz.io/api/v1/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "alias": "team_slack",
    "displayName": "Team Slack",
    "connectionStrategy": "fixed",
    "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    "enabledActions": ["send_channel_message", "list_channels"]
  }'

typescript

const { integration } = await client.workspaces.addIntegration('a1b2c3d4-e5f6-7890-abcd-ef1234567890', {
  integrationName: 'slack',
  alias: 'team_slack',
  displayName: 'Team Slack',
  connectionStrategy: 'fixed',
  connectionId: 'c1d2e3f4-5678-90ab-cdef-1234567890ab',
  enabledActions: ['send_channel_message', 'list_channels'],
})

python

result = client.workspaces.add_integration(
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    integration_name="slack",
    integration_alias="team_slack",
    display_name="Team Slack",
    connection_strategy="fixed",
    connection_id="c1d2e3f4-5678-90ab-cdef-1234567890ab",
    enabled_actions=["send_channel_message", "list_channels"],
)

typescript

const res = await fetch('https://api.weavz.io/api/v1/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/integrations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'slack',
    alias: 'team_slack',
    displayName: 'Team Slack',
    connectionStrategy: 'fixed',
    connectionId: 'c1d2e3f4-5678-90ab-cdef-1234567890ab',
    enabledActions: ['send_channel_message', 'list_channels'],
  }),
})
const data = await res.json()

python

res = httpx.post(
    "https://api.weavz.io/api/v1/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/integrations",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "slack",
        "alias": "team_slack",
        "displayName": "Team Slack",
        "connectionStrategy": "fixed",
        "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
        "enabledActions": ["send_channel_message", "list_channels"],
    },
)
data = res.json()

Advanced Code settings

advanced-code workspace integrations support settings.advancedCode. These settings control execution environment lifecycle, timeout, and persistent storage access for every API, SDK, Playground, and MCP call that targets the workspace integration. They are not action input, so callers cannot override them at runtime.

json

{
  "integrationName": "advanced-code",
  "alias": "advanced_code",
  "settings": {
    "advancedCode": {
      "timeoutSeconds": 45,
      "sandboxPersistence": "persistent",
      "storageMountScope": "workspace"
    }
  }
}

Field	Type	Description
`timeoutSeconds`	number	Execution timeout, from 1 to 60 seconds. Defaults to `30`.
`sandboxPersistence`	string	`ephemeral` creates a fresh execution environment for each run. `persistent` reuses the execution environment between runs.
`storageMountScope`	string	One of `none`, `end_user`, `workspace`, or `external`.
`storageExternalId`	string	External namespace key required when `storageMountScope` is `external`.

Stateful tool settings

Storage, KV Store, Agent Memory, Agent Scratchpad, and Sequential Thinking workspace integrations support settings.persistence. These settings control where tool state is stored for every API, SDK, Playground, and MCP call that targets the workspace integration. They are not action input, so callers cannot override them at runtime.

json

{
  "integrationName": "kv-store",
  "alias": "workspace_kv",
  "settings": {
    "persistence": {
      "scope": "workspace"
    }
  }
}

Field	Type	Description
`scope`	string	One of `end_user`, `workspace`, or `external`. Defaults to `end_user`.
`externalId`	string	External namespace key required when `scope` is `external`.

Errors

Status	Code	Description
`400`	`VALIDATION_ERROR`	Missing required fields or invalid strategy
`409`	`DUPLICATE`	Integration with this alias already exists in the workspace
`409`	`MCP_BEARER_BLOCKS_PER_USER`	The workspace has a static bearer MCP server and the integration would require strict per-user credentials. Switch static bearer off first, or use `per_user_with_fallback`.

Update Workspace Integration

PATCH/api/v1/workspaces/{workspaceId}/integrations/{id}

Update a workspace integration's alias, connection strategy, connection, action subset, display name, or ordering.

Path Parameters

Field	Type	Description
`workspaceId`	string (uuid)	Workspace ID
`id`	string (uuid)	Workspace integration ID

Request Body

Field	Type	Required	Description
`alias`	string	No	Updated workspace integration alias
`connectionStrategy`	string	No	New connection strategy
`connectionId`	string (uuid)	No	New connection ID
`displayName`	string \| null	No	Updated friendly label, or `null` to clear
`enabledActions`	string[] \| null	No	Updated action list, or `null` for all
`settings`	object \| null	No	Updated owner-controlled integration settings, or `null` to reset to defaults for supported integrations.
`sortOrder`	number	No	Updated ordering hint

Response

json

{
  "integration": {
    "id": "7df5c03e-4df5-4b5f-95a7-5277d8f972db",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "integrationName": "slack",
    "alias": "team_slack",
    "displayName": "Team Slack",
    "connectionStrategy": "per_user_with_fallback",
    "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    "enabledActions": ["send_channel_message", "list_channels"],
    "sortOrder": 0,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-16T14:00:00.000Z"
  }
}

Example

bash

curl -X PATCH https://api.weavz.io/api/v1/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/integrations/7df5c03e-4df5-4b5f-95a7-5277d8f972db \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionStrategy": "per_user_with_fallback",
    "enabledActions": ["send_channel_message", "list_channels"]
  }'

typescript

const { integration } = await client.workspaces.updateIntegration(
  'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  '7df5c03e-4df5-4b5f-95a7-5277d8f972db',
  {
    connectionStrategy: 'per_user_with_fallback',
    enabledActions: ['send_channel_message', 'list_channels'],
  },
)

python

result = client.workspaces.update_integration(
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "7df5c03e-4df5-4b5f-95a7-5277d8f972db",
    connection_strategy="per_user_with_fallback",
    enabled_actions=["send_channel_message", "list_channels"],
)

typescript

const res = await fetch('https://api.weavz.io/api/v1/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/integrations/7df5c03e-4df5-4b5f-95a7-5277d8f972db', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    connectionStrategy: 'per_user_with_fallback',
    enabledActions: ['send_channel_message', 'list_channels'],
  }),
})
const data = await res.json()

python

res = httpx.patch(
    "https://api.weavz.io/api/v1/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/integrations/7df5c03e-4df5-4b5f-95a7-5277d8f972db",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "connectionStrategy": "per_user_with_fallback",
        "enabledActions": ["send_channel_message", "list_channels"],
    },
)
data = res.json()

Errors

Status	Code	Description
`400`	`NO_UPDATES`	No fields provided to update
`404`	`NOT_FOUND`	Workspace integration not found
`409`	`MCP_BEARER_BLOCKS_PER_USER`	The update would require strict per-user credentials while a static bearer MCP server exists for the workspace

Delete Workspace Integration

DELETE/api/v1/workspaces/{workspaceId}/integrations/{id}

Remove an integration from a workspace.

Path Parameters

Field	Type	Description
`workspaceId`	string (uuid)	Workspace ID
`id`	string (uuid)	Workspace integration ID

Response

json

{
  "deleted": true,
  "id": "7df5c03e-4df5-4b5f-95a7-5277d8f972db"
}

Example

bash

curl -X DELETE https://api.weavz.io/api/v1/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/integrations/7df5c03e-4df5-4b5f-95a7-5277d8f972db \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

await client.workspaces.removeIntegration(
  'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  '7df5c03e-4df5-4b5f-95a7-5277d8f972db',
)

python

client.workspaces.remove_integration(
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "7df5c03e-4df5-4b5f-95a7-5277d8f972db",
)

typescript

const res = await fetch('https://api.weavz.io/api/v1/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/integrations/7df5c03e-4df5-4b5f-95a7-5277d8f972db', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer wvz_your_api_key' },
})
const data = await res.json()

python

res = httpx.delete(
    "https://api.weavz.io/api/v1/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/integrations/7df5c03e-4df5-4b5f-95a7-5277d8f972db",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
data = res.json()

Errors

Status	Code	Description
`404`	`NOT_FOUND`	Workspace integration not found

Auto-Sync with MCP Servers

When you add, update, or remove workspace integrations, any MCP servers linked to the workspace automatically reflect the changes. MCP server tools are kept in sync with the workspace's integration configuration -- there is no manual sync step required.

Connection Strategies

Connection strategies control how Weavz resolves which connection to use when executing actions for a workspace integration.

fixed

A single connection is always used for this integration in this workspace. Every action execution uses the specified connection regardless of who initiated it.

Best for: Shared service accounts, organization-wide API keys, per-customer connections in multi-tenant setups.

Requires: connectionId

bash

curl -X POST https://api.weavz.io/api/v1/workspaces/{workspaceId}/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "openai",
    "connectionStrategy": "fixed",
    "connectionId": "conn_org_openai"
  }'

per_user

Each user must provide their own connection. If the user has not connected their account, the action fails with a CONNECTION_REQUIRED error.

Best for: Personal integrations where each end-user needs their own OAuth2 authorization (e.g., personal Gmail, calendar access).

bash

curl -X POST https://api.weavz.io/api/v1/workspaces/{workspaceId}/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "gmail",
    "connectionStrategy": "per_user"
  }'

per_user_with_fallback

Users can provide their own connection, but if they have not connected, a default connection is used as a fallback.

Best for: Optional personalization. For example, users can connect their own Slack account, but if they have not, the team's shared Slack bot connection is used.

Requires: connectionId (the fallback connection)

bash

curl -X POST https://api.weavz.io/api/v1/workspaces/{workspaceId}/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "connectionStrategy": "per_user_with_fallback",
    "connectionId": "conn_slack_default"
  }'

Integration Aliases

When configuring the same integration multiple times in a workspace, use alias to disambiguate the configured instances. When executing actions, creating partials, resolving dynamic properties, or managing MCP tools, target the configured instance with workspaceIntegrationId when available, or pass the alias as integrationAlias.

bash

# Bot workspace
curl -X POST https://api.weavz.io/api/v1/workspaces/{workspaceId}/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "alias": "slack_bot",
    "connectionStrategy": "fixed",
    "connectionId": "conn_slack_bot"
  }'
 
# User workspace
curl -X POST https://api.weavz.io/api/v1/workspaces/{workspaceId}/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "alias": "slack_user",
    "connectionStrategy": "per_user"
  }'

When executing actions, specify workspaceIntegrationId or integrationAlias to target the correct workspace integration instance:

bash

curl -X POST https://api.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "actionName": "send_channel_message",
    "integrationAlias": "slack_bot",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "input": {
      "channel": "#alerts",
      "text": "Automated alert!"
    }
  }'

See Integration Aliases for alias naming rules and MCP server behavior.