PermuteDocs
Go to Permute

Actions · actionDefinitionSave

Save an action draft

Requires Edit draft on the action and Read on each selected source. Saving validates contracts and bindings without executing code, granting capabilities, or changing the published version. Optional tool metadata is authored by the coding agent or developer: classify all branches and connector/SDK effects, and reassess descriptions and hints whenever behavior changes. Validation checks metadata shape and consistency; it does not derive or verify risk labels from code. Publishing separately requires Publish on the action and source Admin/delegation authority. Sources can bind published managed database schemas or queryable warehouse sources, including processed files, synced connectors, Data Flow outputs and completed entity outputs. Database schema revisions are dependency revisions; warehouse reads use current available output. Named connector bindings authorize provider calls separately. Optional platform methods pass through the SDK with declared resource permissions; drafting requires resource Read (resource-type Read for wildcards); publication requires resource Admin delegation authority. Callers need only action invocation access. History, restore, and publish use the shared resource versioning endpoints.

PUT/v1/actions/{actionId}/definition
betaapiKeyworkspace

When to use

Save action code, contracts, permissions, and source bindings together.

For agents

Requires business_action.update_draft plus Read on each selected database, warehouse source, connector, and declared SDK resource. Saving does not execute or delegate capabilities. Publishing through client.revisions requires Publish and source Admin. Database bindings pin published schema revisions and declared readTables/writeTables; db.read supports equality-filtered server-side reads. Optional connectors maps names to connector IDs; handlers use connectors.<name>.request, query, or putObject according to the provider. Each external call needs a stable stepId. Handlers can also call llm({ prompt, system?, outputSchema? }) at most 10 times per run when the definition sets llm: true; without it, calls fail.

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.saveDefinition('actn_abcdefghijklmnopqrstuvwx', {
  "expectedDraft": null,
  "definition": {
    "source": "exports.handler = ({ input, db }) => { db.insert('contacts', input); return input; };",
    "inputSchema": {
      "type": "object"
    },
    "outputSchema": {
      "type": "object"
    },
    "invokePermission": "write",
    "sources": [
      {
        "sourceId": "dbas_crm123",
        "revisionId": "rvsn_schema123",
        "readTables": [],
        "writeTables": [
          "contacts"
        ]
      }
    ]
  }
});

Request body

json
{
  "expectedDraft": null,
  "definition": {
    "source": "exports.handler = ({ input, db }) => { db.insert('contacts', input); return input; };",
    "inputSchema": {
      "type": "object"
    },
    "outputSchema": {
      "type": "object"
    },
    "invokePermission": "write",
    "sources": [
      {
        "sourceId": "dbas_crm123",
        "revisionId": "rvsn_schema123",
        "readTables": [],
        "writeTables": [
          "contacts"
        ]
      }
    ]
  }
}

Response

json
{
  "data": {
    "revisionId": "rvsn_action123"
  }
}