# Custom Scripts

Generate, edit, secure, test, and approve a Custom Script automation action -- an AI-written (or hand-written) JavaScript module that runs on its own automation as the final action.

**Base URL:** `https://api.trustpager.com/functions/v1/api/v1`

## Endpoints

### POST /automations/:automation_id/actions/:action_id/custom-script/approve-code

Approve a Custom Script's current generated code for live execution (Gate B — separate from saving the action itself).

**Scopes:** `automations:write` — [full detail](./custom-scripts/post-automations-automation-id-actions-action-id-custom-script-approve-code.md)

### PUT /custom-scripts/:script_id/tp-key

Attach a TrustPager API key (tp_live_…) to a Custom Script so its code can call the TrustPager API via tp.*. The key's own scopes decide what the script may do - mint it in Settings → API with exactly the scopes needed. Write-only; the value is never returned. Redeploy (Test) the script to apply.

**Scopes:** `custom-scripts:write` — [full detail](./custom-scripts/put-custom-scripts-script-id-tp-key.md)

### DELETE /automations/:automation_id/actions/:action_id/custom-script/secrets/:secret_name

Remove a third-party secret from a Custom Script.

**Scopes:** `automations:write` — [full detail](./custom-scripts/delete-automations-automation-id-actions-action-id-custom-script-secrets-secret-name.md)

### DELETE /custom-scripts/:script_id/tp-key

Remove the TrustPager API key from a Custom Script - tp.* becomes unavailable to it on the next deploy.

**Scopes:** `custom-scripts:write` — [full detail](./custom-scripts/delete-custom-scripts-script-id-tp-key.md)

### POST /automations/:automation_id/actions/:action_id/custom-script/generate

Generate (or regenerate) a Custom Script action's code from a plain-English description.

**Scopes:** `automations:write` — [full detail](./custom-scripts/post-automations-automation-id-actions-action-id-custom-script-generate.md)

### GET /automations/:automation_id/actions/:action_id/custom-script

Get a Custom Script action's current state — description, generated code, approval/deploy status, secret names, last test result.

**Scopes:** `automations:read` — [full detail](./custom-scripts/get-automations-automation-id-actions-action-id-custom-script.md)

### GET /custom-scripts/:script_id

Get one Custom Script by its id — description, generated code, approval/deploy status, secret names, last test result.

**Scopes:** `custom-scripts:read` — [full detail](./custom-scripts/get-custom-scripts-script-id.md)

### GET /custom-scripts/:script_id/invocations

List recent runs of a Custom Script — status (dispatched/completed/failed/timed_out), result, error, who invoked it, and timing.

**Scopes:** `custom-scripts:read` — [full detail](./custom-scripts/get-custom-scripts-script-id-invocations.md)

### GET /custom-scripts

List all Custom Scripts in the workspace — id, description, approval/deploy status, secret names, and the owning automation (if any).

**Scopes:** `custom-scripts:read` — [full detail](./custom-scripts/get-custom-scripts.md)

### POST /custom-scripts/:script_id/run

Run an approved Custom Script by its id right now (a live run — enforces the code-approval gate). Optionally pass contact_id/deal_id/trigger so the script can resolve a real record. Async: poll get_custom_script_invocations for the result.

**Scopes:** `custom-scripts:write` — [full detail](./custom-scripts/post-custom-scripts-script-id-run.md)

### PATCH /automations/:automation_id/actions/:action_id/custom-script/code

Save hand-edited Custom Script code verbatim (marks it manually_edited so future regenerations never silently overwrite it).

**Scopes:** `automations:write` — [full detail](./custom-scripts/patch-automations-automation-id-actions-action-id-custom-script-code.md)

### PUT /automations/:automation_id/actions/:action_id/custom-script/secrets/:secret_name

Add or replace a third-party secret a Custom Script needs (write-only — the value is never returned).

**Scopes:** `automations:write` — [full detail](./custom-scripts/put-automations-automation-id-actions-action-id-custom-script-secrets-secret-name.md)

### POST /automations/:automation_id/actions/:action_id/custom-script/test

Deploy and dry-run a Custom Script against sample trigger data. Bypasses both approval gates; never touches automation run history. Optionally pass contact_id/deal_id so tp.contact()/tp.deal()/tp.context() have a real record to resolve.

**Scopes:** `automations:write` — [full detail](./custom-scripts/post-automations-automation-id-actions-action-id-custom-script-test.md)