Integrations & Capabilities API

The Integrations API provides a unified abstraction layer for extending the DonutWork core platform with third-party application functionalites. By declaring "capabilities," applications can expose their own endpoints as managed actions within the DonutWork ecosystem, allowing for seamless cross-platform orchestration, automated authorization handling (app-to-app), and centralized audit logging.

Lifecycle Management

Audit Active Integrations

Retrieve a paginated directory of all integrations currently authorized for your organization. This includes high-level connectivity status and identification handlers for each service.

{
  "entities": "Integration",
  "count": 1,
  "per_page": 100,
  "pages": {
    "current": 1,
    "max": 1
  },
  "elements": [
    {
      "id": "6908bffd...",
      "handler": "STRIPE_CONNECT",
      "name": "Stripe Global Payments",
      "status": "connected"
    }
  ]
}

Declare Functional Capabilities

Register or update the specific actions (capabilities) that your application exposes. This declaration defines the input requirements and contract for each action, enabling DonutWork to proxy requests to your service securely.

{
  "app_token": "ext_auth_token_9921",
  "capabilities": [
    {
      "action": "SYNC_INVENTORY",
      "method": "POST",
      "endpoint": "https://api.myapp.com/v1/sync",
      "inputs": [
        {
          "name": "sku",
          "type": "string",
          "required": true
        },
        {
          "name": "quantity",
          "type": "number",
          "required": true
        }
      ]
    }
  ]
}

{
  "success": true,
  "message": "Capabilities declared successfully for MY_CUSTOM_APP",
  "app_handler": "MY_CUSTOM_APP",
  "actions_count": 1
}

Resource Discovery

Retrieve Specific Integration

Fetch the full configuration, permission sets, and connectivity health for a specific integration.

{
  "id": "6908...",
  "handler": "SLACK_ENT",
  "status": "connected",
  "actions": [
    {
      "name": "SEND_MESSAGE",
      "method": "POST"
    }
  ],
  "metadata": {
    "workspace": "AcmeHQ"
  }
}

Execution (Capability Proxy)

Dispatch Delegated Action

Execute a capability on a remote integration. DonutWork acts as a secure proxy, handling authorization headers and validating input schemas before relaying the request to the target service.

{
  "success": true,
  "integration": "SLACK_ENT",
  "action": "SEND_MESSAGE",
  "external_status": 200,
  "response": {
    "ok": true,
    "ts": "123456789.0001"
  }
}

The request payload for action dispatch is dynamic. Required body fields are validated at runtime using the integration capability declaration (capabilities[].inputs[] with required: true).

Read Delegated Action

{
  "success": true,
  "integration": "SLACK_ENT",
  "action": "GET_CHANNEL_INFO",
  "external_status": 200,
  "response": {}
}

Update Delegated Action

{
  "success": true,
  "integration": "SLACK_ENT",
  "action": "UPSERT_TEMPLATE",
  "external_status": 200,
  "response": {}
}

Delete Delegated Action

{
  "success": true,
  "integration": "SLACK_ENT",
  "action": "DELETE_MESSAGE",
  "external_status": 200,
  "response": {}
}

Emit Integration Event

Emit an application-scoped event so workflows and event listeners can react to integration activity.

{
  "metadata": {
    "message_id": "msg_001",
    "status": "sent"
  },
  "entity_id": "SLACK_ENT"
}

{
  "success": true,
  "app_handler": "SLACK",
  "event": "Slack.MESSAGE_SENT",
  "queued_workflows": 1
}

Technical Implementation

curl --location --request POST \
'https://api.hub.donutwork.com/2026-02-01/integrations/SLACK/SEND_MSG.json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{"message": "Automated Deployment Completed"}'

const payload = { message: "System Alert: Resource threshold reached." };
try {
  const result = await sdk.integrations.dispatch("SLACK", "SEND_MSG", payload);
  console.log(`Action Result: ${result.success} (Status: ${result.external_status})`);
} catch (error) {
  console.error(`Dispatch Failed: ${error.message}`);
}