External Actions API

Action Types

Register Action Type

POST /api/external/action-types

Field	Type	Required	Description
`name`	string	Yes	Machine-readable name (snake_case, e.g., `grant_points`)
`description`	string	Yes	Human-readable description for the AI decision engine
`provider`	string	Yes	Your platform identifier
`parameters_schema`	object	Yes	JSON Schema for the action's parameters
`delivery_webhook`	string	Yes	URL where Retivo sends dispatched actions
`domain`	string	No	Category tag (e.g., `loyalty`, `gamification`)
`estimated_cost_usd`	string	No	Cost per execution for budget tracking

Response (201):

{
  "action_type": {
    "id": "at_abc123",
    "name": "grant_points",
    "webhook_secret": "64-char-hex-string"
  }
}

List Action Types

GET /api/external/action-types?provider=smile-io&domain=loyalty&active=true

Update Action Type

PUT /api/external/action-types/{id}

Deactivate Action Type

DELETE /api/external/action-types/{id}

Soft-delete — sets active to false.

Actions (Dispatch Log)

List Actions (Pull Reconciliation)

GET /api/external/actions?status=dispatched&since=2026-04-25T00:00:00Z&limit=50

Param	Type	Description
`status`	string	Filter: `pending`, `dispatched`, `delivered`, `completed`, `failed`, `expired`
`provider`	string	Filter by provider
`user_id`	string	Filter by user
`since`	string	ISO-8601 timestamp — only actions after this time
`limit`	number	Max results (1-100, default 50)

Report Outcome

POST /api/external/actions/{actionId}/outcome

Field	Type	Required	Description
`status`	string	Yes	`completed`, `ignored`, `rejected`, or `partial`
`result`	object	No	Arbitrary result data from your system

Response (200):

{
  "recorded": true,
  "action_id": "ea_xyz789",
  "outcome_status": "completed"
}

Returns 409 if an outcome was already reported for this action.

Custom Events

Push Events (Batch)

POST /api/external/events

Push up to 100 custom events. Events are broadcast to webhook subscribers AND ingested into the data pipeline.

{
  "events": [
    {
      "type": "custom.reward.redeemed",
      "user_id": "user-123",
      "data": { "reward_type": "discount", "value": 20 },
      "timestamp": "2026-04-26T10:30:00Z"
    }
  ]
}

Event types must use the custom. prefix with lowercase dot notation.

Push Single Event

POST /api/external/events/emit

Same fields as a single event in the batch endpoint.

Recommendations

Get Recommendation

POST /api/decisions/recommend

Ask Retivo what your system should do for a specific user.

Field	Type	Required	Description
`user_id`	string	Yes	Target user
`domain`	string	No	Scope to domain (e.g., `loyalty`)
`available_actions`	string[]	Yes	Action types your system can execute
`context`	object	No	Extra context from your system

Response:

{
  "user_id": "user-123",
  "domain": "loyalty",
  "recommendation": {
    "action": "grant_points",
    "parameters": { "amount": 300 },
    "confidence": 0.82,
    "reasoning": "User hasn't redeemed in 14 days..."
  },
  "alternatives": [...],
  "user_context": {
    "lifecycle_stage": "active",
    "activation_score": 72,
    "engagement_score": 45,
    "risk_level": "medium"
  }
}

Pre-Built Platform Connectors

List Platforms

GET /api/external/platforms

Returns all available pre-built connectors and their connection status.

Connect Platform

POST /api/external/platforms/{platformId}/connect

Auto-registers action types from the platform's template.

{
  "credentials": {
    "api_key": "sk_live_..."
  }
}

Disconnect Platform

POST /api/external/platforms/{platformId}/disconnect

Webhook Dispatch Format

When Retivo dispatches an action, your delivery_webhook receives:

{
  "action_id": "ea_xyz789",
  "action_type": "grant_points",
  "user_id": "user-123",
  "parameters": { "amount": 500, "reason": "re-engagement bonus" },
  "reasoning": "User completed onboarding but hasn't engaged since",
  "confidence": "0.82",
  "tenant_id": "tenant-uuid",
  "timestamp": "2026-04-26T10:30:00Z"
}

Header	Description
`X-Retivo-Signature`	HMAC-SHA256 hex digest of the body
`X-Retivo-Timestamp`	ISO-8601 dispatch time
`X-Retivo-Action-Id`	Unique action ID for idempotency

Retry schedule: 30s → 2m → 10m → 30m → 2h (5 retries max).

Permissions

Endpoint	Required Permission
Action type CRUD	`manage` or `full`
Report outcome	`manage` or `full`
Push events	`ingest` or `full`
Get recommendation	`decide` or `full`
List actions	`read` or `full`
Platform connect/disconnect	Admin role

External Actions API

On this page