Skip to main content
Every action in your application is automatically exposed as an API endpoint. The same authorization, validation, and business logic that runs in the web UI runs through the API — no additional controller code needed.

​
Authentication

All action endpoints live under /api/v1/. The API accepts both authentication methods on the same routes — the middleware detects the token type automatically:
Token typeGrantIdentity
Client credentialsclient_credentialsApp client permissions
User access tokenauthorization_codeAuthenticated user permissions
See Client Credentials or User Authentication for setup.

​
Execute an Action

There are two URL forms depending on whether the action operates on a specific resource.

​
Without a subject

Use this for actions that don’t target a specific model (e.g. create actions, report triggers): 
POST /api/v1/actions/{action}/execute

curl -X POST https://yourapp.test/api/v1/actions/orders/create-order/execute \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"customer": 12, "ordered_at": "2026-03-13"}'

​
With a subject

Use this for actions that operate on a specific resource. Place the subject’s ID in the URL — integers, UUIDs, and any other ID format are supported: 
POST /api/v1/actions/{action}/execute/{id}
​
id
string
required
The subject’s primary key. The server automatically resolves which parameter the ID maps to based on the action’s declared subject class.
curl -X POST https://yourapp.test/api/v1/actions/orders/approve-order/execute/42 \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"reason": "Verified by finance"}'
Not sure what {id} maps to internally, or what additional parameters the action accepts? Call the schema endpoint first — it tells you the subject’s parameter name and a ready-to-use url_pattern.

​
Response

{
  "success": true,
  "message": "Order approved.",
  "data": {
    "id": 42,
    "title": "Order #42",
    "url": "/orders/42"
  }
}

​
Response mapping

The API controller maps the action’s return value to JSON:
handle() returnsHTTP statusResponse body
string (message)200{ success: true, message }
ObjectContract200{ success: true, message, data: {object} }
StoredWorkflow200{ success: true, workflow_id }
void / null200{ success: true }
CoreActionException422{ success: false, message }
redirectTo() hints are ignored by the API — they only affect web responses. The API always returns JSON.

​
Action Schema Discovery

Retrieve an action’s parameter schema and subject metadata. Use this to understand the expected URL pattern and required parameters before executing: 
GET /api/v1/actions/{action}/schema

curl https://yourapp.test/api/v1/actions/orders/approve-order/schema \
  -H 'Authorization: Bearer YOUR_TOKEN'

{
  "name": "Approve order",
  "description": null,
  "lookup_key": "orders/approve-order",
  "subject": {
    "required": true,
    "param": "order",
    "class": "App\\Models\\Order",
    "url_pattern": "https://yourapp.test/api/v1/actions/orders/approve-order/execute/{id}"
  },
  "rules": {
    "reason": ["required", "string", "max:255"]
  }
}

​
Subject block

When an action has a declared $subjectClass, the response includes a subject object:
FieldDescription
requiredAlways true — subject-scoped actions require a subject ID in the URL
paramThe internal parameter name the ID is bound to
classThe fully-qualified model class the subject must be an instance of
url_patternReady-to-use URL — replace {id} with the actual subject ID

​
Bulk Execute

Execute an action on multiple items. The subject ID is resolved per item from the ids array: 
POST /api/v1/actions/{action}/bulk
​
ids
array
required
Array of subject IDs to process.
​
params
object
Additional parameters applied to every execution (e.g. a shared reason string).
curl -X POST https://yourapp.test/api/v1/actions/orders/approve-order/bulk \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"ids": [1, 2, 3, 4, 5], "params": {"reason": "Batch approval"}}'

{
  "success": true,
  "summary": {
    "total": 5,
    "succeeded": 5,
    "failed": 0
  },
  "results": [
    { "id": 1, "success": true, "message": "Order approved." },
    { "id": 2, "success": true, "message": "Order approved." }
  ]
}

​
Error Handling

StatusMeaningWhen
200SuccessAction completed
403Forbiddenauthorize() returned false
404Not FoundUnknown action key
422UnprocessableValidation failed or CoreActionException thrown
500Server ErrorUnhandled exception

​
Next Steps

Client Credentials

Set up app-to-app authentication for your API integration.

User Authentication

OAuth authorization code flow for user-scoped API access.