API Reference · Endpoints

Remote actions

Register actions on your platform that Inboxi users and AI agents can run, and learn the exact request Inboxi sends to your callback URL.

A remote action is a button that calls into your platform: "Activate subscription", "Resend invoice", "Book a slot". Your platform registers the action with a callback URL and its input fields; Inboxi lists it in Settings › Developer Hub › Remote Actions, and calls your URL when someone runs it. Concepts and examples: Remote actions guide.

Your platform

POST /api/v1/actions registers the action

Inboxi

An agent or AI agent runs it with parameters

HTTP request

Your callback URL

Does the work and answers within 15s

Endpoint	Permission
`POST /api/v1/actions`	`write`
`GET /api/v1/actions`	`read`
`PUT /api/v1/actions/:id`	`write`
`DELETE /api/v1/actions/:id`	`write`

Register an action

POST/api/v1/actionsCreate or update an action by name

Registration is idempotent: posting an action whose name already exists updates it and reactivates it. Call it on every deploy of your platform.

Parameter	Type	Required	Description
`name`	string	required	Machine name, unique in your workspace, for example `activate_subscription`.
`callbackUrl`	string	required	URL Inboxi calls. May contain `{param}` placeholders filled from the parameters, for example `https://your-platform.com/students/{phone}/activate`.
`label`	string	optional	Display name. Defaults to `name`.
`description`	string	optional	What the action does.
`method`	string	optional	`POST` (default), `GET`, `PUT`, `PATCH` or `DELETE`.
`category`	string	optional	Grouping, for example `subscriptions`. Default `general`.
`headers`	object	optional	Extra headers sent with every callback, for example your own auth token.
`parameterSchema`	array	optional	Input fields: `[{ name, type, label, required }]`.
`requiresConfirmation`	boolean	optional	Ask for confirmation before running. Default `true`.

curl -X POST "https://inboxi.app/api/v1/actions" \
  -H "X-API-Key: inx_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "activate_subscription",
    "label": "Activate Subscription",
    "description": "Activate a student subscription on the platform",
    "callbackUrl": "https://your-platform.com/api/subscriptions/activate",
    "category": "subscriptions",
    "headers": {
      "Authorization": "Bearer YOUR_PLATFORM_TOKEN"
    },
    "parameterSchema": [
      {
        "name": "studentId",
        "type": "string",
        "label": "Student ID",
        "required": true
      },
      {
        "name": "plan",
        "type": "string",
        "label": "Plan name",
        "required": false
      }
    ]
  }'

Returns 201 with the action:

json

{
  "success": true,
  "data": {
    "id": 12,
    "name": "activate_subscription",
    "label": "Activate Subscription",
    "description": "Activate a student subscription on the platform",
    "callbackUrl": "https://your-platform.com/api/subscriptions/activate",
    "method": "POST",
    "headers": { "Authorization": "Bearer YOUR_PLATFORM_TOKEN" },
    "category": "subscriptions",
    "parameterSchema": [
      { "name": "studentId", "type": "string", "label": "Student ID", "required": true },
      { "name": "plan", "type": "string", "label": "Plan name", "required": false }
    ],
    "requiresConfirmation": true,
    "isActive": true
  }
}

An invalid callbackUrl returns 500 with "error": "Invalid callback URL".

List actions

GET/api/v1/actionsAll actions, grouped by category then label

curl "https://inboxi.app/api/v1/actions" \
  -H "X-API-Key: inx_live_your_api_key"

Returns the action objects in data; each includes apiKey.name, the key that registered it.

Update an action

PUT/api/v1/actions/:idChange any field

Send only the fields to change (same names as registration). Set isActive: false to hide an action without deleting it.

curl -X PUT "https://inboxi.app/api/v1/actions/12" \
  -H "X-API-Key: inx_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Activate plan",
    "requiresConfirmation": false
  }'

Returns the updated action, or 404 "Action not found".

Delete an action

DELETE/api/v1/actions/:idRemove an action

curl -X DELETE "https://inboxi.app/api/v1/actions/12" \
  -H "X-API-Key: inx_live_your_api_key"

json

{ "success": true }

Callback request format

When the action runs, Inboxi calls your callbackUrl like this:

http

POST https://your-platform.com/api/subscriptions/activate
Content-Type: application/json
X-Inboxi-Action: activate_subscription
X-Inboxi-Organization: <your workspace id>
Authorization: Bearer YOUR_PLATFORM_TOKEN      (from "headers")

{
  "studentId": "STU-001",
  "plan": "premium"
}

The body is the parameters as a JSON object, for POST, PUT and PATCH.
For GET, parameters go in the query string. DELETE sends no body.
Parameters used by a {placeholder} in the URL are inserted (URL-encoded) and not repeated in the query string.
Your headers are added after the Inboxi headers and can override them.

What your endpoint should do

Return 2xx on success, optionally with a JSON body. Inboxi logs the status and body and shows the result.
Return 4xx/5xx on failure. The run is marked failed with HTTP <status>.
Respond within 15 seconds; slower calls are aborted and marked failed.
Authenticate the call, for example with a secret header you registered in headers.