Integrations API

All integration endpoints use API key authentication. The workspace is resolved automatically from the key.

Endpoints

`GET /api/integrations`

List all integrations in the workspace.

Auth: API Key | Min Role: VIEWER | MCP: integrations:read

Query parameters:

Parameter	Type	Description
`search`	string	Full-text search on name, description, code
`triggerType`	string	`webhook \| schedule \| manual`
`isActive`	boolean	Filter by active status
`label`	string	Exact label match
`includeArchived`	boolean	When `true`, returns only archived integrations. Archived integrations are hidden by default.
`sortBy`	string	`createdAt` (default) \| `updatedAt` \| `name`
`sortOrder`	string	`desc` (default) \| `asc`
`page`	number	1-based page number (default: 1)
`limit`	number	Items per page, max 100 (default: 20)

Response: { data: Integration[], total, page, limit }

`POST /api/integrations`

Create a new integration.

Auth: API Key | Min Role: DEVELOPER

Body: { "name": "my-automation", "description": "Optional" }

Response: 201 integration object

`GET /api/integrations/:name`

Get a single integration by name.

Auth: API Key | Min Role: VIEWER | MCP: integrations:read

`PUT /api/integrations/:name`

Update an integration's settings.

Auth: API Key | Min Role: DEVELOPER | MCP: integrations:write

Body (all fields optional):

{
  "name": "new-name",
  "description": "Updated description",
  "triggerType": "schedule",
  "cronExpression": "0 9 * * 1-5",
  "timeoutSeconds": 60,
  "retryEnabled": true,
  "retryMaxAttempts": 3,
  "webhookMethod": "POST",
  "webhookAuthHeader": "x-api-key",
  "webhookAuthCredentialName": "MY_WEBHOOK_KEY"
}

`DELETE /api/integrations/:name`

Delete an integration permanently.

Auth: API Key | Min Role: ADMIN

The integration must be archived first. Calling this on an integration that is not archived returns 400 Bad Request with the message "Integration must be archived before deletion". Archive it via POST /:name/archive, then delete it.

Response: 204 No Content

`POST /api/integrations/:name/archive`

Archive an integration. Archived integrations are hidden from the default list view and cannot be triggered, but remain visible when includeArchived=true is passed. Archiving is a required first step before an integration can be permanently deleted.

Auth: API Key | Min Role: DEVELOPER

Response: Integration object with archivedAt set

`POST /api/integrations/:name/unarchive`

Restore an archived integration back to normal (active/inactive, non-archived) status.

Auth: API Key | Min Role: DEVELOPER

Response: Integration object with archivedAt: null

`POST /api/integrations/bulk-archive`

Archive or unarchive multiple integrations in a single call.

Auth: API Key | Min Role: DEVELOPER

Body:

{ "names": ["integration-a", "integration-b"], "archived": true }

archived defaults to true. Set it to false to bulk-unarchive.

`POST /api/integrations/bulk-delete`

Permanently delete multiple integrations in a single call. Each integration must already be archived, same as the single-item DELETE endpoint.

Auth: API Key | Min Role: ADMIN

Body:

{ "names": ["integration-a", "integration-b"] }

`PATCH /api/integrations/:name/labels`

Replace the full labels array on an integration.

Auth: API Key | Min Role: DEVELOPER | MCP: integrations:write

Body: { "labels": ["crm", "billing"] } (max 20 labels, each max 50 chars)

Response: { id, labels }

`POST /api/integrations/:name/activate`

Activate an integration.

Auth: API Key | Min Role: DEVELOPER

Response: Integration object with isActive: true

`POST /api/integrations/:name/deactivate`

Deactivate an integration.

Auth: API Key | Min Role: DEVELOPER

Response: Integration object with isActive: false

`POST /api/integrations/:name/clone`

Clone an integration (creates a copy with a -copy name suffix).

Auth: API Key | Min Role: DEVELOPER

Response: 201 cloned integration object

Integrations API

On this page