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. Currently commits mutations and a receipt in one selected managed database. Reads are outside the write transaction. Reuse requestId with identical input after an uncertain response.

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

When to use

Run a published business action with its declared source capabilities.

For agents

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"
    }
  }
}