Approval Connectors API¶

Manage approval delivery connectors, workspace defaults, and connector activity.

Approval connectors let RunAgents route approval-required events into external systems such as Slack, Microsoft Teams, Jira, PagerDuty, or custom webhooks while still falling back to the console when needed.

List Approval Connectors¶

GET /api/settings/approval-connectors

Returns approval connectors configured in the current workspace.

curl https://api.runagents.io/api/settings/approval-connectors \
  -H "Authorization: Bearer $RUNAGENTS_API_KEY" \
  -H "X-Workspace-Namespace: default"

Response (200 OK)¶

[
  {
    "id": "ac_01hxyz...",
    "name": "secops-slack",
    "type": "slack",
    "endpoint": "C0123456789",
    "headers": {
      "X-Slack-Bot-Token": "xoxb-..."
    },
    "enabled": true,
    "timeout_seconds": 15,
    "slack_security_mode": "compat",
    "created_at": "2026-04-09T15:10:00Z",
    "updated_at": "2026-04-09T15:10:00Z"
  }
]

Create Approval Connector¶

POST /api/settings/approval-connectors

Create a workspace-scoped approval connector.

Request Body¶

curl -X POST https://api.runagents.io/api/settings/approval-connectors \
  -H "Authorization: Bearer $RUNAGENTS_API_KEY" \
  -H "X-Workspace-Namespace: default" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "secops-slack",
    "type": "slack",
    "endpoint": "C0123456789",
    "headers": {
      "X-Slack-Bot-Token": "xoxb-..."
    },
    "timeout_seconds": 15,
    "slack_security_mode": "compat"
  }'

Response (201 Created)¶

Returns the created connector.

Get Approval Connector¶

GET /api/settings/approval-connectors/:id

Returns a single connector.

Update Approval Connector¶

PATCH /api/settings/approval-connectors/:id

Update one or more mutable connector fields.

Request Body¶

All fields are optional. Include only the fields you want to change.

{
  "enabled": false,
  "timeout_seconds": 20
}

Response (200 OK)¶

Returns the updated connector.

Delete Approval Connector¶

DELETE /api/settings/approval-connectors/:id

Deletes the named connector.

Response (200 OK)¶

{
  "status": "deleted"
}

Test Approval Connector¶

POST /api/settings/approval-connectors/test

Validates connector configuration and attempts a live delivery test when possible.

Request Body¶

Response (200 OK)¶

{
  "status": "healthy",
  "connector_type": "webhook",
  "endpoint": "https://approvals.example.com/hook",
  "checks": [
    {
      "id": "config",
      "label": "Configuration",
      "status": "passed",
      "message": "Connector configuration is valid"
    },
    {
      "id": "credentials",
      "label": "Credentials",
      "status": "passed",
      "message": "Required credentials are present"
    },
    {
      "id": "connectivity",
      "label": "Connectivity",
      "status": "passed",
      "message": "Connector endpoint accepted the test request",
      "duration_ms": 148
    }
  ]
}

A response can still be 200 OK with status: "unhealthy" when the test ran successfully but one or more checks failed.

Get Connector Defaults¶

GET /api/settings/approval-connectors/defaults

Returns workspace defaults used when an approval policy omits explicit connector delivery settings.

Response (200 OK)¶

{
  "default_delivery_mode": "first_success",
  "default_fallback_to_ui": true,
  "default_timeout_seconds": 10,
  "min_timeout_seconds": 1,
  "max_timeout_seconds": 120
}

Update Connector Defaults¶

PUT /api/settings/approval-connectors/defaults

Update one or more workspace defaults.

Request Body¶

{
  "default_delivery_mode": "all",
  "default_fallback_to_ui": true,
  "default_timeout_seconds": 20
}

Response (200 OK)¶

Returns the updated defaults.

Get Connector Activity¶

GET /api/settings/approval-connectors/activity

Returns recent approval connector activity for the current workspace.

Query Parameters¶

Response (200 OK)¶

[
  {
    "id": "aca_01hxyz...",
    "timestamp": "2026-04-09T15:18:31Z",
    "event": "dispatch_succeeded",
    "connector_id": "ac_01hxyz...",
    "connector_name": "secops-slack",
    "request_id": "req_123",
    "decision": "approved",
    "status_code": 200,
    "duration_ms": 148,
    "message": "Connector delivery succeeded"
  }
]

Supported Connector Types¶

RunAgents currently supports these connector types:

• webhook
• slack
• teams
• jira
• pagerduty

Connector-specific validation applies. For example:

• Slack strict mode requires an X-Slack-Signing-Secret header
• PagerDuty requires a routing key header
• Webhook connectors expect an HTTPS endpoint

Errors¶

Related¶

• Approvals API
• Policies API
• Platform Approvals Guide