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.

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": "pi_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "orgId": "550e8400-e29b-41d4-a716-446655440000",
      "integrationName": "slack",
      "integrationAlias": "slack",
      "connectionStrategy": "fixed",
      "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
      "allowedActions": null,
      "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	Integration identifier (e.g., `slack`, `github`)
`integrationAlias`	string	No	Alias for this integration instance (defaults to `integrationName`). Useful when the same integration is configured multiple times with different connections.
`connectionStrategy`	string	Yes	One of: `fixed`, `per_user`, `per_user_with_fallback`
`connectionId`	string (uuid)	No	Connection ID. Required for `fixed` and `per_user_with_fallback` strategies.
`allowedActions`	string[]	No	Restrict to specific actions. `null` or omitted means all actions are available.

Response (201)

json

{
  "integration": {
    "id": "pi_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "integrationName": "slack",
    "integrationAlias": "slack",
    "connectionStrategy": "fixed",
    "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    "allowedActions": null,
    "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",
    "connectionStrategy": "fixed",
    "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab"
  }'

typescript

const { integration } = await client.workspaces.addIntegration('a1b2c3d4-e5f6-7890-abcd-ef1234567890', {
  integrationName: 'slack',
  connectionStrategy: 'fixed',
  connectionId: 'c1d2e3f4-5678-90ab-cdef-1234567890ab',
})

python

result = client.workspaces.add_integration(
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    integration_name="slack",
    connection_strategy="fixed",
    connection_id="c1d2e3f4-5678-90ab-cdef-1234567890ab",
)

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',
    connectionStrategy: 'fixed',
    connectionId: 'c1d2e3f4-5678-90ab-cdef-1234567890ab',
  }),
})
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",
        "connectionStrategy": "fixed",
        "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    },
)
data = res.json()

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`	`ALIAS_CONFLICT`	Alias is already associated with a different integration in this workspace

Update Workspace Integration

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

Update a workspace integration's connection strategy, connection, or allowed actions.

Path Parameters

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

Request Body

Field	Type	Required	Description
`connectionStrategy`	string	No	New connection strategy
`connectionId`	string (uuid)	No	New connection ID
`allowedActions`	string[] \| null	No	Updated action list, or `null` for all

Response

json

{
  "integration": {
    "id": "pi_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "integrationName": "slack",
    "integrationAlias": "slack",
    "connectionStrategy": "per_user_with_fallback",
    "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    "allowedActions": ["send_channel_message", "list_channels"],
    "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/pi_a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionStrategy": "per_user_with_fallback",
    "allowedActions": ["send_channel_message", "list_channels"]
  }'

typescript

const { integration } = await client.workspaces.updateIntegration(
  'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  'pi_a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  {
    connectionStrategy: 'per_user_with_fallback',
    enabledActions: ['send_channel_message', 'list_channels'],
  },
)

python

result = client.workspaces.update_integration(
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "pi_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    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/pi_a1b2c3d4-e5f6-7890-abcd-ef1234567890', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    connectionStrategy: 'per_user_with_fallback',
    allowedActions: ['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/pi_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "connectionStrategy": "per_user_with_fallback",
        "allowedActions": ["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

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": "pi_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Example

bash

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

typescript

await client.workspaces.removeIntegration(
  'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  'pi_a1b2c3d4-e5f6-7890-abcd-ef1234567890',
)

python

client.workspaces.remove_integration(
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "pi_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
)

typescript

const res = await fetch('https://api.weavz.io/api/v1/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/integrations/pi_a1b2c3d4-e5f6-7890-abcd-ef1234567890', {
  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/pi_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    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 (e.g., two Slack connections for different workspaces), use integrationAlias to disambiguate:

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",
    "integrationAlias": "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",
    "integrationAlias": "slack_user",
    "connectionStrategy": "per_user"
  }'

When executing actions, specify the 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.