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

# Automations API

> Create automations that start a chat task, a test plan run, or a pull request review on a schedule, from an API call, or from a GitHub pull request event

An automation is a "when X, do Y" rule in a project. The trigger decides when it fires, and the action decides what QA.tech does. Automations you create through the API appear in the dashboard under **Settings → Automations**, and the dashboard's automations appear in the API.

## Endpoints

For full request, response, and error details, see the generated reference pages:

* [List Automations](https://docs.qa.tech/api-reference/automations/list-automations.md) – every automation in the project with its trigger, action, enabled state, last fire time, and next scheduled run
* [Create Automation](https://docs.qa.tech/api-reference/automations/create-automation.md) – create an automation from a trigger and an action
* [Update Automation](https://docs.qa.tech/api-reference/automations/update-automation.md) – change the name, description, enabled state, trigger, or action. Only the fields you pass change, but `trigger` and `action` each replace the stored value as a whole
* [Delete Automation](https://docs.qa.tech/api-reference/automations/delete-automation.md) – delete an automation and its automation history. Chat conversations and runs it started stay in the project. To pause an automation instead, update it with `isEnabled: false`
* [Trigger Automation](https://docs.qa.tech/api-reference/automations/trigger-automation.md) – fire a `schedule` or `api_webhook` automation now

All write endpoints need a key with `write` scope. See the [API Introduction](https://docs.qa.tech/api-reference/introduction.md#authentication) for authentication, including how organization-scoped keys pass `projectShortId`.

## Triggers

| `trigger.type` | Fires | Fields |
| - | - | - |
| `schedule` | On a cron schedule | `cron` (5 fields, for example `0 9 * * 1` for Mondays at 09:00), `timezone` (IANA name, default `UTC`), `once` (default `false`) |
| `api_webhook` | Only when you call [Trigger Automation](https://docs.qa.tech/api-reference/automations/trigger-automation.md) | None |
| `github_event` | On pull request events in repositories connected to the project | `events`, plus optional `labels`, `baseBranches`, `repositories`, `includeDrafts` |

With `once: true`, the automation fires a single time and then disables itself. Pin the minute, hour, day, and month in `cron` so it fires at the time you intend.

### GitHub pull request events

A `github_event` trigger needs at least one event:

| Event | When it fires |
| - | - |
| `pull_request.opened` | A pull request is opened |
| `pull_request.ready_for_review` | A draft pull request is marked ready |
| `pull_request.synchronize` | New commits are pushed to the pull request |
| `pull_request.labeled` | A label is added |
| `pull_request.merged` | The pull request is merged |
| `pull_request.closed` | The pull request is closed without merging |

The optional filters narrow which pull requests fire it. An empty or omitted filter matches everything.

* `labels`: only pull requests with one of these labels (case-insensitive). For `pull_request.labeled`, the label that was just added must be one of them.
* `baseBranches`: only pull requests into these base branches. `*` matches any characters, for example `release/*`.
* `repositories`: only these repositories, as `owner/name`. Defaults to every repository connected to the project.
* `includeDrafts`: also fire for draft pull requests. Defaults to `false`.

The project needs a repository connected through the [QA.tech GitHub App](https://docs.qa.tech/configuration/github-app.md). Creating or updating an automation with a `github_event` trigger fails when none is connected.

## Actions

| `action.type` | What QA.tech does | Fields |
| - | - | - |
| `chat` | Starts an [AI chat](https://docs.qa.tech/core-concepts/ai-chat-assistant.md) conversation that works through `prompt` without a user present | `prompt` |
| `run_test_plan` | Runs every test case in a [test plan](https://docs.qa.tech/core-concepts/test-plans.md) | `testPlanShortId` |
| `review_pull_request` | Runs the full QA.tech pull request review on the pull request that fired the automation, as if QA.tech was mentioned on it | None |

The `chat` prompt runs unattended, so describe the whole task and the outcome you expect. When a GitHub event fires a `chat` automation, the conversation receives the pull request details.

`review_pull_request` needs a `github_event` trigger whose events are all open pull request events. It cannot use `pull_request.merged` or `pull_request.closed`.

If you delete the test plan that a `run_test_plan` automation uses, the automation fails until you point it at another plan.

## Examples

Review every pull request into `main` that gets the `qa` label:

```bash theme={null}
curl -X POST https://api.qa.tech/v1/automations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Review labeled PRs",
    "trigger": {
      "type": "github_event",
      "events": ["pull_request.labeled"],
      "labels": ["qa"],
      "baseBranches": ["main"]
    },
    "action": { "type": "review_pull_request" }
  }'
```

Run a test plan every weekday at 07:00 Stockholm time:

```bash theme={null}
curl -X POST https://api.qa.tech/v1/automations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Morning regression",
    "trigger": {
      "type": "schedule",
      "cron": "0 7 * * 1-5",
      "timezone": "Europe/Stockholm"
    },
    "action": { "type": "run_test_plan", "testPlanShortId": "pln_abc123" }
  }'
```

## Trigger an automation from CI

Create an automation with an `api_webhook` trigger, then call [Trigger Automation](https://docs.qa.tech/api-reference/automations/trigger-automation.md) from a deploy hook, CI job, or monitoring alert. The optional `context` object is passed to the agent as-is, so include details such as the deployed version or environment name:

```bash theme={null}
curl -X POST https://api.qa.tech/v1/automations/AUTOMATION_ID/trigger \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "context": { "version": "2026.11.12", "environment": "staging" } }'
```

The request returns `202` right away and the automation runs in the background. It returns `409` when the automation is disabled or has a `github_event` trigger, which fires only from its own events. A `schedule` automation can also be fired this way, outside its schedule.

## Related documentation

* [Test Plans](https://docs.qa.tech/core-concepts/test-plans.md) – Group test cases to run together
* [GitHub App](https://docs.qa.tech/configuration/github-app.md) – Connect the repositories that GitHub triggers listen to
* [MCP Server](https://docs.qa.tech/integrations/mcp.md) – Manage automations from an AI assistant with the automation tools
* [API Introduction](https://docs.qa.tech/api-reference/introduction.md) – Authentication and ID reference


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.