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

# Automations

> Schedule recurring AI coding tasks in Capy — daily cleanups, weekly dependency updates, nightly builds, or anything you want an agent to do on repeat.

## Overview

Automations run tasks on a schedule - daily cleanups, weekly reports, nightly builds, or anything else you'd want an agent to do on repeat.

## Creating an automation

1. Open a project and go to the **Automations** tab
2. Click **New automation**
3. Configure the automation:

| Field           | Description                                                                                  |
| --------------- | -------------------------------------------------------------------------------------------- |
| **Name**        | A descriptive name (e.g., "Weekly dependency updates")                                       |
| **Prompt**      | What the agent should do - same as a task prompt                                             |
| **Trigger**     | Schedule (cron), GitHub webhook (PR/review events), or Incoming webhook (external HTTP POST) |
| **Schedule**    | Pick a preset (daily, weekly, custom) or write a cron expression                             |
| **Timezone**    | Which timezone the schedule runs in                                                          |
| **Agent type**  | Build (for coding) or Captain (for planning and delegation)                                  |
| **Model**       | Which AI model to use                                                                        |
| **Base branch** | The branch to work from                                                                      |

## Schedule options

You can use presets or write a custom cron expression:

| Preset | Schedule                                                             |
| ------ | -------------------------------------------------------------------- |
| Daily  | Every day at a set time                                              |
| Weekly | A specific day and time each week                                    |
| Custom | Any valid cron expression (e.g., `0 9 * * 1-5` for weekdays at 9 AM) |

All schedules respect the timezone you set.

## How runs work

When a schedule triggers:

1. Capy creates a new task in the project
2. The agent runs with your prompt, on the base branch you configured
3. The run appears in the automation's **Run history**

Each run is a normal task - you can review the diff, create a PR, or send feedback just like any other task.

## Incoming webhooks

Every automation has a unique webhook URL. Use it to trigger the automation from any external service - CI/CD pipelines, monitoring alerts, Zapier, custom scripts, or anything that can make an HTTP POST.

### Triggering an automation

```bash theme={null}
curl -X POST https://capy.ai/api/webhooks/automations/trigger/{token} \
  -H "Content-Type: application/json" \
  -d '{"deployment_id": "abc123", "environment": "staging", "status": "failed"}'
```

The response includes the automation ID and run status:

```json theme={null}
{ "ok": true, "automationId": "...", "runStatus": "running" }
```

### Passing context

Any JSON fields in the request body are available as template variables in your automation prompt:

| Variable                   | Value                         |
| -------------------------- | ----------------------------- |
| `{{payload}}`              | Full JSON body as a string    |
| `{{payload.field}}`        | Top-level field value         |
| `{{payload.nested.field}}` | Nested field via dot notation |
| `{{trigger.timestamp}}`    | ISO 8601 trigger time         |

Example prompt:

```
A deployment to {{payload.environment}} just failed (ID: {{payload.deployment_id}}).
Check the logs and open a fix PR.
```

### HMAC signature verification

For additional security, configure a webhook secret on the automation. Sign your requests using HMAC-SHA256 and include the signature in the `X-Capy-Signature` header:

```bash theme={null}
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')
curl -X POST https://capy.ai/api/webhooks/automations/trigger/{token} \
  -H "X-Capy-Signature: sha256=$SIGNATURE" \
  -H "Content-Type: application/json" \
  -d "$BODY"
```

Compatible with GitHub's webhook signature format (`X-Hub-Signature-256`).

### Rate limits

60 requests per minute per webhook URL. Requests over the limit receive a `429` response with a `Retry-After` header.

## Managing automations

* **Enable/disable** - toggle an automation without deleting it
* **Edit** - update the prompt, schedule, model, or branch
* **Webhook URL** - copy or rotate the webhook URL for any automation
* **Webhook secret** - configure optional HMAC signature verification
* **Run history** - view past runs with status and timestamps
* **Delete** - remove the automation entirely

## Example automations

**Daily lint fix**

```
Run `pnpm lint --fix` and commit any auto-fixable issues.
```

**Weekly dependency updates**

```
Check for outdated dependencies with `pnpm outdated`. Update patch and minor
versions, run tests, and summarize what changed.
```

**Nightly test suite**

```
Run the full test suite with `pnpm test`. If any tests fail, investigate the
failures and fix them. If all tests pass, report the results.
```