---
canonical: "https://agi-labo.com/en/tools/wings/docs/api-triggers"
title: "API Triggers"
description: "Expose a Handler over HTTP with explicit authentication and approval."
section: "Core features"
order: 6
pageType: "how-to"
lastVerifiedVersion: "1.4.16"
lastVerifiedAt: "2026-10-15"
draft: false
surfaces: ["cli", "console", "api"]
plans: ["free", "member"]
---

An API Trigger lets you call a Handler over HTTP.
Deploy a Handler first, then add its Trigger:

```sh
wings trigger add-api <handler-id> --slug webhook --auth bearer
wings trigger list <handler-id>
wings trigger url <handler-id> <trigger-id>
```

Use the invocation URL shown by the CLI.
Public Triggers use `wings.agi-labo.com`.
The management API uses `api.wings.agi-labo.com`.

## Approve in the Console

The creation command opens a Console confirmation page.
The Trigger is created when its owner selects Create.
Bearer authentication is the default.
The Console shows the secret once and does not pass it to the CLI.
Using `rotate-secret` also requires confirmation.

With `--auth public`, callers do not need a bearer secret.
For a webhook, check the sender's signature in your Handler before taking any action.
Use `--method` and `--allow-origin` to allow only the methods and origins you need.

## Read a request

Triggers accept JSON and multipart.
`event.body` contains the parsed values.
Keys in `event.headers` are lowercase.

Verify signatures against `event.rawBodyBase64`, which preserves the original bytes.
`event.rawBody` is the body decoded as UTF-8 text.

## Return a response

Returning JSON produces HTTP 200 containing the Wings execution result.
Throwing an error also returns HTTP 200, with a failed execution result in the body.
Return a `Response` to choose the HTTP status and body:

```js
export default async function (event) {
  return Response.json({ received: true }, { status: 202 })
}
```

Same-origin redirects are returned to the caller.
Wings does not follow them.
Redirects to another origin return 502 `redirect_not_allowed`.
`Refresh` headers are removed.

## Stop or change a Trigger

Disabling, deleting, changing settings, or rotating a secret stops requests that have not passed the last check before execution.
Work already accepted is not cancelled.

For integrations that need a quick acknowledgement, measure both first-use and repeat response times.
`X-AGI-Wings-Platform-Latency-Ms` and `Server-Timing` report the time before execution starts.
They do not guarantee a response time.

## Request limits

| Item | Limit |
| --- | --- |
| Request body | 256 KiB |
| Requests per IP | 30 per minute |
| Requests per Trigger | 120 per minute |
| Requests per account | 300 per minute |
| Concurrent Runs per Trigger | 5 |
| Concurrent Runs per account | 20 |

Ordinary Run limits also apply.
Use [Handler streaming](/en/tools/wings/docs/handlers-runs) for large files instead of sending them to this endpoint.