PermuteDocs
Go to Permute

Actions · actionsInvoke

Invoke a published action

Requires the action’s declared permission. Runs one immutable revision with its declared source capabilities. When the action has a managed database write target, its mutations and receipt commit in that database; actions without one, such as actions which only call the AI model, need no database. Reads are outside the write transaction. Reuse requestId with identical input after an uncertain response. Expected handler rejections use reject(code, message, details) and return a structured error; record conflicts return 409, input validation returns 400, and unexpected execution failures return a safe 500. Check error.code rather than matching message text. See the business-actions guide for codes and recovery.

POST/v1/actions/{actionId}/invoke
betaauthenticatedworkspace

When to use

Run a published business action with its declared source capabilities.

For agents

Requires business_action.invoke, or an existing level-based grant satisfying both current and selected revision thresholds. Reuse requestId and input when retrying. The first invocation pins its revision. Managed database writes and their receipt are atomic; reads and external connector effects are outside that transaction. Completed connector steps replay their saved response, while uncertain steps block automatic resend. Changing a published database write target requires a new action.

Example

typescript
import { PermuteClient } from '@permute/sdk';

const orgClient = new PermuteClient({
  apiKey: process.env.PERMUTE_API_KEY!,
});

const client = orgClient.withWorkspace(process.env.PERMUTE_WORKSPACE_ID!);

const result = await client.actions.invoke('actn_abcdefghijklmnopqrstuvwx', {
  "requestId": "create-contact-1",
  "input": {
    "id": "contact_1",
    "name": "Alex"
  }
});

Request body

json
{
  "requestId": "create-contact-1",
  "input": {
    "id": "contact_1",
    "name": "Alex"
  }
}

Response

json
{
  "data": {
    "requestId": "create-contact-1",
    "actionId": "actn_abcdefghijklmnopqrstuvwx",
    "revisionId": "rvsn_action123",
    "versions": [],
    "output": {
      "id": "contact_1"
    }
  }
}