> ## Documentation Index
> Fetch the complete documentation index at: https://docs.puntego.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Verified Actions

> Customer-approved tools that read or change a narrow business object after policy checks, with curated templates, identity rules, and a Beta custom-write path.

Verified Actions are customer-approved tools that let the guide read or change a narrow business object after policy checks. They are not a generic API agent: every action targets one fixed operation, runs server-side, and passes a policy gate before it executes.

Every action starts disabled. An owner enables a specific action instance in the dashboard before it can run, and server-side policy still checks the workspace flag, identity requirement, connector state, confirmation, and rate limit on every request.

## How a request is gated

Each call walks the same gate. If any check fails, the action does not run and the result is surfaced for owner review.

```mermaid theme={null}
flowchart TD
  A[Action request] --> B{Workspace flag enabled?}
  B -- no --> X[Refuse: not enabled]
  B -- yes --> C{Identity requirement met?}
  C -- no --> Y[Refuse: identity required]
  C -- yes --> D{Write action?}
  D -- yes --> E{Visitor confirmation?}
  E -- declined --> Z[Refuse: not confirmed]
  E -- confirmed --> F[Call connector]
  D -- no --> F[Call connector]
  F --> G[Normalize and redact output]
  G --> H[Return result + audit log]
```

Connector output is untrusted. The guide normalizes and redacts every result before it is reused in chat or replay, and writes are recorded with idempotency keys and audit logging.

## Curated templates

The catalog ships exactly seven curated templates. Each one has a fixed schema, risk class, identity requirement, and confirmation requirement. Six of the seven ship a managed adapter you can connect from the dashboard; Account entitlement lookup has no managed adapter and runs only when you supply a custom connector for it.

| Template                                                 | What it does                                                        | Managed adapter                 |
| -------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------- |
| CRM lead lookup                                          | Reads a CRM lead record for the current visitor.                    | Yes (HubSpot)                   |
| Account entitlement lookup                               | Reads a visitor's plan or entitlement state.                        | No — connect a custom connector |
| Order status lookup                                      | Reads the status of an order.                                       | Yes (generic REST, Shopify)     |
| Inventory lookup                                         | Reads stock or availability for an item.                            | Yes (generic REST)              |
| Support ticket creation                                  | Creates a support ticket.                                           | Yes (Zendesk, Intercom)         |
| Support ticket creation with transcript and page context | Creates a ticket and attaches the chat transcript and page context. | Yes (Zendesk, Intercom)         |
| Meeting booking                                          | Books a meeting on a sales calendar.                                | Yes                             |

<Note>
  Connector credentials live in an encrypted vault and only the last four characters are ever shown back, so you can confirm which secret is stored without exposing it.
</Note>

Support ticket creation connects to either Zendesk or Intercom. Connect Zendesk with an API token (Basic auth — also supply the agent email the token belongs to and the account subdomain) or an OAuth access token (Bearer); connect Intercom with an access token.

## Identity and confirmation

All curated read templates require a `visitor_session` before the connector runs. Identity `none` is available only for custom read-only actions. Writes always require visitor confirmation in the same request.

| Action type                                                  | Identity required                                              | Confirmation required |
| ------------------------------------------------------------ | -------------------------------------------------------------- | --------------------- |
| Curated read templates (lead, entitlement, order, inventory) | `visitor_session`                                              | None                  |
| Curated write templates (ticket creation, meeting booking)   | `visitor_session`                                              | Visitor confirmation  |
| Custom read-only actions                                     | Configurable: `none`, `visitor_session`, or `account_identity` | None                  |
| Custom Beta writes                                           | `visitor_session` (or stricter)                                | Visitor confirmation  |

Writes also carry idempotency, audit logging, and redacted request and result storage, so a confirmed write is never replayed and is always reviewable.

## Custom read-only actions

You can add a manually scoped read-only action when no curated template fits. A custom read-only action calls one fixed operation against one host, so it stays as narrow as a curated template.

A custom read-only action requires:

<ParamField path="action_key" type="string" required>
  Stable key that identifies the action instance.
</ParamField>

<ParamField path="name" type="string" required>
  Human-readable name shown to owners.
</ParamField>

<ParamField path="method" type="GET | POST" required>
  The single HTTP method the action uses.
</ParamField>

<ParamField path="connector_base_url" type="string" required>
  One fixed base URL. The action cannot call any other host.
</ParamField>

<ParamField path="path" type="string" required>
  One fixed path on that base URL.
</ParamField>

<ParamField path="input_schema" type="JSON Schema" required>
  Schema for the inputs the action accepts.
</ParamField>

<ParamField path="output_schema" type="JSON Schema" required>
  Schema the connector output is validated against.
</ParamField>

<ParamField path="rate_limit_per_minute" type="number" required>
  Per-minute cap on calls to this action.
</ParamField>

<ParamField path="test_input" type="object" required>
  A sample input used to test the action when you create it.
</ParamField>

<ParamField path="redaction_rules" type="array">
  Optional redaction map applied to the connector output. The action works without it, but add it whenever the response can include sensitive fields.
</ParamField>

<Info>
  OpenAPI and Swagger import is not supported. You cannot upload an API document to generate tools; each custom action is scoped by hand to one host and one path.
</Info>

## Beta custom writes

Custom visitor-confirmed writes are Beta and are limited to reversible or low-risk categories: creating a lead, creating a ticket, booking a meeting, adding to cart, applying a coupon, or updating a non-sensitive preference.

Before you can create a custom write, the dashboard requires explicit Beta risk acknowledgment, and you must provide the target system, the visitor confirmation copy, and reversal or handoff instructions. A write that falls outside the allowed Beta categories needs owner or human handoff instead of direct execution.

<Warning>
  These write categories are always forbidden and can never be enabled, even in Beta:

  * Refunds
  * Cancellations
  * Access changes
  * Role changes
  * Password, API-key, or security changes
  * Payment or billing changes
  * Contractual acceptance
  * Broad exports
  * Arbitrary webhooks or emails
  * Regulated decisions
</Warning>

## Rollout checklist

Bring actions online one at a time and verify each gate before you widen traffic.

<Steps>
  <Step title="Enable only the lanes you need">
    Turn on just the action lanes required for the pilot. Leave everything else disabled.
  </Step>

  <Step title="Enable curated templates one at a time">
    Enable a single curated template, connect its managed adapter, and verify connector health before any production traffic.
  </Step>

  <Step title="Review custom read-only actions">
    Add custom read-only actions only after reviewing the fixed base URL, fixed path, input and output schemas, and the redaction map.
  </Step>

  <Step title="Confirm identity sources">
    Confirm every read that exposes personal data has a `visitor_session` (or stricter identity) before launch.
  </Step>

  <Step title="Keep Beta writes off until acknowledged">
    Leave Beta custom writes disabled unless the customer accepts the Beta risk copy and the action is reversible or low-risk.
  </Step>

  <Step title="Run replay QA">
    Replay one allowed action, one declined confirmation, and one blocked forbidden category, plus one stale-credential case, and confirm output redaction in each.
  </Step>

  <Step title="Review before widening">
    Review Needs Attention items and audit logs for correct redaction before enabling the next action.
  </Step>
</Steps>

## Deployment notes

* Keep actions server-side. Never expose connector secrets to the browser, prompts, logs, or model-visible context.
* Keep Beta write copy visible in-product and require acknowledgment for every creation flow.
* Treat stale credentials, schema failures, failed writes, and policy blocks as Needs Attention items.
* Roll back by disabling the action instance or its lane. Do not widen workspace-wide policy to make a single action pass.

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    How visitor sessions are minted and how programmatic API keys are scoped.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference">
    Endpoints, request shapes, and responses for the worker.
  </Card>

  <Card title="Privacy and PII" icon="lock" href="/privacy-and-pii">
    What is redacted before model and connector calls run.
  </Card>

  <Card title="Errors" icon="triangle-alert" href="/errors">
    Error namespaces and status codes you will see when a gate blocks a request.
  </Card>
</CardGroup>