Arcanflows — AI Automation Platform for Business

Overview

The Notifications API provides multi-channel notification delivery (email, Slack, webhook, SMS, in-app) with per-user preferences, delivery tracking, and provider management. Notifications can be sent manually, triggered by events, or fired from workflow nodes.

Channel Types

Type	Description	Providers
`email`	Email delivery	SMTP, SendGrid, Mailgun, AWS SES
`slack`	Slack messages	Slack Incoming Webhooks, Slack Bot
`webhook`	HTTP POST to a URL	Any HTTP endpoint
`sms`	SMS text messages	Twilio, Vonage
`in_app`	In-platform notifications	Built-in (no external provider)

Notification Channels

Notification channels define how and where notifications are delivered. Each channel has a type, provider configuration, and can be enabled/disabled independently.

List Channels

GET /api/v1/notification-channels

Query Parameters:

Parameter	Type	Description
`type`	string	Filter by channel type (`email`, `slack`, `webhook`, `sms`, `in_app`)
`active`	boolean	Filter by active status

Response:

json
{
  "data": [
    {
      "id": "nc_abc123",
      "name": "Production Slack",
      "type": "slack",
      "provider": "slack_webhook",
      "active": true,
      "created_at": "2026-01-10T08:00:00Z"
    },
    {
      "id": "nc_def456",
      "name": "Alert Emails",
      "type": "email",
      "provider": "sendgrid",
      "active": true,
      "created_at": "2026-01-10T08:30:00Z"
    }
  ],
  "total": 2
}

Create Channel

POST /api/v1/notification-channels

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Display name
`type`	string	Yes	Channel type (`email`, `slack`, `webhook`, `sms`, `in_app`)
`provider`	string	Yes	Provider identifier
`config`	object	Yes	Provider-specific configuration
`active`	boolean	No	Enable immediately (default: true)

Example -- Slack channel:

bash
curl -X POST /api/v1/notification-channels \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Alerts",
    "type": "slack",
    "provider": "slack_webhook",
    "config": {
      "webhook_url": "https://hooks.slack.com/services/T00/B00/xxxx",
      "channel": "#alerts",
      "username": "Arcanflows Bot"
    }
  }'

Example -- Email channel (SendGrid):

bash
curl -X POST /api/v1/notification-channels \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Transactional Emails",
    "type": "email",
    "provider": "sendgrid",
    "config": {
      "api_key": "SG.xxxx",
      "from_email": "[email protected]",
      "from_name": "Arcanflows"
    }
  }'

Get Channel

GET /api/v1/notification-channels/:id

Update Channel

PUT /api/v1/notification-channels/:id

Delete Channel

DELETE /api/v1/notification-channels/:id

Test Channel

Send a test notification through the channel to verify it is configured correctly.

POST /api/v1/notification-channels/:id/test

bash
curl -X POST /api/v1/notification-channels/nc_abc123/test \
  -H "Authorization: Bearer your_api_key"

Response:

json
{
  "success": true,
  "message": "Test notification delivered successfully",
  "delivery_time_ms": 230
}

Reveal Channel Secrets

Returns the full configuration including sensitive fields (API keys, tokens). Requires admin permissions.

GET /api/v1/notification-channels/:id/reveal

Delivery Logs

GET /api/v1/notification-channels/:id/logs

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number
`per_page`	integer	Items per page
`status`	string	Filter: `delivered`, `failed`, `pending`

Response:

json
{
  "data": [
    {
      "id": "log_abc123",
      "channel_id": "nc_abc123",
      "status": "delivered",
      "subject": "Workflow completed",
      "recipient": "#alerts",
      "delivery_time_ms": 180,
      "created_at": "2026-01-15T14:00:00Z"
    }
  ],
  "total": 85,
  "page": 1,
  "per_page": 20
}

Channel Stats

GET /api/v1/notification-channels/:id/stats

Returns delivery statistics for a specific channel (total sent, success rate, average delivery time).

Provider and Stats Endpoints

Available Providers

GET /api/v1/notification-channels/providers

Lists all supported notification providers with their required configuration fields.

Response:

json
{
  "providers": [
    {
      "id": "sendgrid",
      "type": "email",
      "name": "SendGrid",
      "config_schema": {
        "api_key": { "type": "string", "required": true, "secret": true },
        "from_email": { "type": "string", "required": true },
        "from_name": { "type": "string", "required": false }
      }
    },
    {
      "id": "slack_webhook",
      "type": "slack",
      "name": "Slack Incoming Webhook",
      "config_schema": {
        "webhook_url": { "type": "string", "required": true, "secret": true },
        "channel": { "type": "string", "required": false },
        "username": { "type": "string", "required": false }
      }
    }
  ]
}

Active Channels by Type

GET /api/v1/notification-channels/active/:type

Returns all active channels of a given type. Useful when you need to know which channels are available for a specific delivery method.

Global Stats

GET /api/v1/notification-channels/stats

Returns aggregate notification statistics across all channels.

Stats Breakdown

GET /api/v1/notification-channels/stats/breakdown

Returns statistics broken down by channel type, provider, and time period.

User Notifications

User-facing notifications appear in the platform's notification center and can optionally be forwarded to external channels based on user preferences.

List My Notifications

GET /api/v1/notifications

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number
`per_page`	integer	Items per page
`read`	boolean	Filter by read status
`type`	string	Filter by notification type

Response:

json
{
  "data": [
    {
      "id": "notif_abc123",
      "type": "workflow_completed",
      "title": "Workflow Finished",
      "message": "Lead Processing workflow completed successfully.",
      "read": false,
      "data": {
        "workflow_id": "wf_abc123",
        "execution_id": "exec_def456"
      },
      "created_at": "2026-01-15T14:30:00Z"
    }
  ],
  "total": 12,
  "unread": 3,
  "page": 1,
  "per_page": 20
}

Unread Count

GET /api/v1/notifications/unread/count

Response:

json
{
  "count": 3
}

Mark as Read

POST /api/v1/notifications/:id/read

Mark All as Read

POST /api/v1/notifications/read-all

Get Notification Preferences

GET /api/v1/notifications/preferences

Response:

json
{
  "preferences": {
    "workflow_completed": {
      "in_app": true,
      "email": true,
      "slack": false
    },
    "workflow_failed": {
      "in_app": true,
      "email": true,
      "slack": true
    },
    "form_submission": {
      "in_app": true,
      "email": false,
      "slack": false
    },
    "approval_requested": {
      "in_app": true,
      "email": true,
      "slack": true
    }
  }
}

Update Notification Preferences

PUT /api/v1/notifications/preferences

bash
curl -X PUT /api/v1/notifications/preferences \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": {
      "workflow_completed": {
        "in_app": true,
        "email": false,
        "slack": true
      }
    }
  }'

Send Test Notification

POST /api/v1/notifications/test

Sends a test notification to your own account across all enabled channels.

bash
curl -X POST /api/v1/notifications/test \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_type": "slack",
    "message": "This is a test notification from Arcanflows."
  }'

Error Codes

Code	Description
`channel_not_found`	Notification channel does not exist
`channel_inactive`	Channel exists but is disabled
`provider_error`	External provider returned an error
`invalid_config`	Channel configuration is invalid or incomplete
`delivery_failed`	Notification could not be delivered after retries
`rate_limited`	Too many notifications sent in a short period