zapier

## Troubleshooting

If requests fail, run `zero doctor check-connector --env-name ZAPIER_TOKEN` or `zero doctor check-connector --url https://actions.zapier.com/api/v2/check/ --method GET`

## How to Use

All examples below assume you have `ZAPIER_TOKEN` set. Authentication uses the `x-api-key` header.

### 1. Check API Key

Verify that your API key is valid.

```bash
curl -s "https://actions.zapier.com/api/v2/check/" --header "x-api-key: $ZAPIER_TOKEN" | jq .
```

### 2. List Exposed Actions

Retrieve all actions you have configured and exposed in your Zapier AI Actions dashboard.

```bash
curl -s "https://actions.zapier.com/api/v1/exposed/" --header "x-api-key: $ZAPIER_TOKEN" | jq '.results[] | {id, description, params}'
```

### 3. Execute an AI Action

Execute a configured action using natural language instructions. Replace `ACTION_ID` with the action ID from the list above.

```bash
curl -s -X POST "https://actions.zapier.com/api/v2/ai-actions/ACTION_ID/execute/" --header "Content-Type: application/json" --header "x-api-key: $ZAPIER_TOKEN" -d '{"instructions": "Send a message saying hello to the #general channel"}' | jq .
```

### 4. Execute with Parameter Hints

Supply parameter hints to guide the AI in filling action fields. Supported modes: `locked` (use exact value), `guess` (AI matches text), `choose_from` (AI selects from list), `ignored` (skip parameter).

Write to `/tmp/zapier_request.json`:

```json
{
  "instructions": "Send an email about the weekly report",
  "params": {
    "to": {
      "mode": "locked",
      "value": "team@example.com"
    },
    "subject": {
      "mode": "locked",
      "value": "Weekly Report"
    }
  }
}
```

Then run:

```bash
curl -s -X POST "https://actions.zapier.com/api/v2/ai-actions/ACTION_ID/execute/" --header "Content-Type: application/json" --header "x-api-key: $ZAPIER_TOKEN" -d @/tmp/zapier_request.json | jq .
```

### 5. Preview an Action (Dry Run)

Preview what the action would do without actually executing it. Add `preview_only=true` as a query parameter.

```bash
curl -s -X POST "https://actions.zapier.com/api/v2/ai-actions/ACTION_ID/execute/?preview_only=true" --header "Content-Type: application/json" --header "x-api-key: $ZAPIER_TOKEN" -d '{"instructions": "Create a new row in the Sales spreadsheet with name John and amount 500"}' | jq .
```

### 6. Execute a V1 Exposed Action

Execute an action using the V1 endpoint. Replace `ACTION_ID` with the exposed action ID.

```bash
curl -s -X POST "https://actions.zapier.com/api/v1/dynamic/exposed/ACTION_ID/execute/" --header "Content-Type: application/json" --header "x-api-key: $ZAPIER_TOKEN" -d '{"instructions": "Send a Slack message to #dev saying deployment complete"}' | jq .
```

## Guidelines

1. **Configure actions first**: Before using the API, you must configure and enable actions in the [Zapier AI Actions dashboard](https://actions.zapier.com/). The API can only execute actions you have set up
2. **Use natural language**: The `instructions` field accepts plain English descriptions of what you want to do. The AI interprets and maps instructions to the correct action parameters
3. **Parameter modes**: Use `locked` mode when you know the exact value, `guess` when the AI should match text to available options, and `choose_from` to provide a list of valid IDs
4. **Preview before executing**: Use `preview_only=true` to verify the AI correctly interprets your instructions before running the action
5. **Response statuses**: Check the `status` field in responses - values are `success`, `error`, `empty`, or `preview`
6. **Rate limits**: Zapier enforces rate limits on API calls. Implement backoff if you receive HTTP 429 responses
7. **Action IDs**: Each configured action has a unique ID. Use the list endpoint to discover available action IDs