# POST /v1/agents/{agent_id}/triggers

Source: <https://everruns.com/docs/api/operations/create_agent_trigger/>

POST

/v1/agents/{agent\_id}/triggers

Select code samplecURL (shell:curl)

```js
const url = 'https://app.everruns.com/api/v1/agents/example/triggers';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"auth":"example","cron_expression":"0 9 * * *","enabled":true,"event_id_template":"{{webhook.headers.x-github-delivery}}","filter":{"changes_only":{"path":"example"},"conditions":[{"any_of":[{}],"path":"example"}]},"github_events":["pull_request.opened"],"mcp_event":"issue.created","mcp_event_arguments":"example","mcp_server":"tracker","message":"Run the daily digest","rate_limit_per_minute":60,"repositories":["everruns/everruns"],"script":{"input":"example","script":"example","wake_agent_on_failure":true},"session_mode":"per_thread","subject_template":"{{webhook.json.action}}","timezone":"UTC","token":"example","trigger_type":"schedule"}'
};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```sh
curl --request POST \
  --url https://app.everruns.com/api/v1/agents/example/triggers \
  --header 'Content-Type: application/json' \
  --data '{ "auth": "example", "cron_expression": "0 9 * * *", "enabled": true, "event_id_template": "{{webhook.headers.x-github-delivery}}", "filter": { "changes_only": { "path": "example" }, "conditions": [ { "any_of": [ {} ], "path": "example" } ] }, "github_events": [ "pull_request.opened" ], "mcp_event": "issue.created", "mcp_event_arguments": "example", "mcp_server": "tracker", "message": "Run the daily digest", "rate_limit_per_minute": 60, "repositories": [ "everruns/everruns" ], "script": { "input": "example", "script": "example", "wake_agent_on_failure": true }, "session_mode": "per_thread", "subject_template": "{{webhook.json.action}}", "timezone": "UTC", "token": "example", "trigger_type": "schedule" }'
```

* Production APIapp.everruns.com/api/v1/agents/{agent\_id}/triggers

## Parameters

### Path Parameters

**agent\_id**

required

string

Agent ID (prefixed)

## Request Bodyrequired

Media typeapplication/json

Request to create a trigger on an agent.

object

**auth**

Shared endpoint auth is not supported by webhook triggers.

**cron\_expression**

Cron expression that drives the durable schedule. Accepts 5-field (min hour day month weekday) or 7-field (sec … year) form.

string | null

##### Example

```plaintext
0 9 * * *
```

**enabled**

Whether the trigger is active on creation (default `true`).

boolean

##### Example

```json
true
```

**event\_id\_template**

Webhook only: template for the delivery idempotency key.

string | null

##### Example

```plaintext
{{webhook.headers.x-github-delivery}}
```

**filter**

One of:

* object

  Webhook, GitHub and MCP event: conditions an event must meet to start a run.

  object

  **changes\_only**

  One of:

  * object

    Pass only events whose value at a path differs from the last one seen for the same subject, such as a CI outcome flipping between `success` and `failure`.

    object

    **path**

    required

    Dotted path into the event context, e.g. `github.ci.outcome`.

    string

  * null

    null

  **conditions**

  Conditions that must all hold.

  Array\<object>

  One filter condition: the value at `path` must equal one of `any_of`.

  object

  **any\_of**

  required

  Accepted values. Strings compare exactly; other JSON values compare by equality.

  Array\<object>

  object

  **path**

  required

  Dotted path into the event context, e.g. `payload.action`.

  string

* null

  Pass only events whose value at a path differs from the last one seen for the same subject, such as a CI outcome flipping between `success` and `failure`.

  object

  **path**

  required

  Dotted path into the event context, e.g. `github.ci.outcome`.

  string

* object

  null

* null

  null

**github\_events**

GitHub only: subscribed events (`pull_request` or `pull_request.opened`). Defaults to pull request open/update events.

Array\<string> | null

##### Example

```json
[
  "pull_request.opened"
]
```

**mcp\_event**

MCP event only: event name from the server’s `events/list`.

string | null

##### Example

```plaintext
issue.created
```

**mcp\_event\_arguments**

MCP event only: subscription arguments object (the event’s `inputSchema`).

object | null

**mcp\_server**

MCP event only: name of the agent’s MCP server attachment to subscribe to.

string | null

##### Example

```plaintext
tracker
```

**message**

required

Message content or `{{template}}` sent when the trigger fires.

string

##### Example

```plaintext
Run the daily digest
```

**rate\_limit\_per\_minute**

Optional per-ingress, per-IP webhook request limit.

integer | null format: int32

##### Example

```json
60
```

**repositories**

GitHub only: repositories (`owner/name`) to accept; empty accepts all.

Array\<string> | null

##### Example

```json
[
  "everruns/everruns"
]
```

**script**

One of:

* object

  Schedule and webhook only: a saved script the trigger runs instead of asking the model. The run is recorded under `message`.

  object

  **input**

  The script’s input object, passed on its stdin.

  object | null

  **script**

  required

  The saved script’s name.

  string

  **wake\_agent\_on\_failure**

  When the run fails or stops, hand the result to the agent’s model, which then answers in the same turn. Off: the run only records it.

  boolean

* null

  null

**session\_mode**

Whether invocations reuse a stable session or create a new one.

string

Allowed values: per\_thread per\_channel per\_user shared\_session session\_per\_invocation

##### Example

```plaintext
per_thread
```

**subject\_template**

Webhook and MCP event: template for the event subject. Required for `session_mode: per_thread`, which keeps one session per subject.

string | null

##### Example

```plaintext
{{webhook.json.action}}
```

**timezone**

IANA timezone identifier for cron evaluation (default `UTC`).

string

##### Example

```plaintext
UTC
```

**token**

Shared secret for webhook triggers.

string | null

**trigger\_type**

Trigger kind. Omitted values retain the schedule API default.

string

Allowed values: schedule webhook github mcp\_event

## Responses

### 201

Trigger created

Media typeapplication/json

AgentTrigger is a durable, agent-owned invocation trigger.

object

**agent\_id**

required

Agent that owns this trigger.

string

**archived\_at**

Archive timestamp.

string | null format: date-time

**config**

required

Type-specific configuration (parsed via typed accessors).

**created\_at**

required

Creation timestamp.

string format: date-time

**deleted\_at**

Delete timestamp.

string | null format: date-time

**enabled**

required

Whether the trigger is currently active.

boolean

**id**

required

External identifier (trg\_<32-hex>). Shown as `id` in API.

string

**ingress\_id**

Stable HTTP ingress identifier for trigger types that accept requests.

string | null

**trigger\_type**

required

The kind of event that fires this trigger.

string

Allowed values: schedule webhook github mcp\_event

**updated\_at**

required

Last update timestamp.

string format: date-time

##### Example

```json
{
  "agent_id": "agent_01933b5a000070008000000000000001",
  "id": "trg_01933b5a000070008000000000000001",
  "trigger_type": "schedule"
}
```

### 400

Invalid request

Media typeapplication/json

Standard error response.

Wire shape is [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457): every error response includes `title` and `status`, and may include `detail`, `code`, `allowed_actions`, `retry_after_seconds`, `instance`, and `type`. The content type is rewritten to `application/problem+json` with the `application/problem+json` content type.

object

**allowed\_actions**

Recovery actions the caller can take next.

Array\<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

* **Error recovery** — `ErrorResponse.allowed_actions` carries `rel`s like `retry`, `retry-later`, `unarchive`, `get-existing` so the agent knows the right next call after a 4xx/429.
* **Entity hypermedia** — `WithUrls<T>.allowed_actions` carries state-aware `rel`s like `cancel`, `events`, `self`, `update` on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed `rel` vocabulary distinguishes them.

object

**hint**

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

**href**

Absolute (preferred) or relative URL the caller may invoke directly. **Always present on entity hypermedia actions** (`WithUrls<T>.allowed_actions`); **optional on error-recovery actions** (`ErrorResponse.allowed_actions`) where the matching `operation_id` is enough and the URI is implicit from the failed call.

string | null

**method**

HTTP method to use against `href`. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null

**operation\_id**

OpenAPI `operationId` the caller should invoke. Lets an MCP client resolve the call without parsing `href`.

string | null

**rel**

required

Link relation describing the action. Examples: `self`, `cancel`, `pause`, `resume`, `events`, `retry`, `retry-later`, `unarchive`, `get-existing`, `delete`, `update`.

string

**schema\_ref**

OpenAPI `$ref` to the request-body schema, when the action takes one (e.g. `#/components/schemas/UpdateSessionRequest`). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null

**code**

Stable, machine-readable error code (snake\_case).

string | null

**detail**

Human-readable explanation specific to this occurrence.

string | null

**instance**

Request URI for this occurrence.

string | null

**retry\_after\_seconds**

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32

**status**

required

HTTP status code; mirrors the response status line.

integer format: int32

**title**

required

Short, human-readable summary of the problem (e.g. “Not Found”).

string

**type**

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

##### Example

```json
{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://everruns.com/docs/errors/session_not_found"
}
```

### 404

Agent not found

Media typeapplication/json

Standard error response.

Wire shape is [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457): every error response includes `title` and `status`, and may include `detail`, `code`, `allowed_actions`, `retry_after_seconds`, `instance`, and `type`. The content type is rewritten to `application/problem+json` with the `application/problem+json` content type.

object

**allowed\_actions**

Recovery actions the caller can take next.

Array\<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

* **Error recovery** — `ErrorResponse.allowed_actions` carries `rel`s like `retry`, `retry-later`, `unarchive`, `get-existing` so the agent knows the right next call after a 4xx/429.
* **Entity hypermedia** — `WithUrls<T>.allowed_actions` carries state-aware `rel`s like `cancel`, `events`, `self`, `update` on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed `rel` vocabulary distinguishes them.

object

**hint**

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

**href**

Absolute (preferred) or relative URL the caller may invoke directly. **Always present on entity hypermedia actions** (`WithUrls<T>.allowed_actions`); **optional on error-recovery actions** (`ErrorResponse.allowed_actions`) where the matching `operation_id` is enough and the URI is implicit from the failed call.

string | null

**method**

HTTP method to use against `href`. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null

**operation\_id**

OpenAPI `operationId` the caller should invoke. Lets an MCP client resolve the call without parsing `href`.

string | null

**rel**

required

Link relation describing the action. Examples: `self`, `cancel`, `pause`, `resume`, `events`, `retry`, `retry-later`, `unarchive`, `get-existing`, `delete`, `update`.

string

**schema\_ref**

OpenAPI `$ref` to the request-body schema, when the action takes one (e.g. `#/components/schemas/UpdateSessionRequest`). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null

**code**

Stable, machine-readable error code (snake\_case).

string | null

**detail**

Human-readable explanation specific to this occurrence.

string | null

**instance**

Request URI for this occurrence.

string | null

**retry\_after\_seconds**

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32

**status**

required

HTTP status code; mirrors the response status line.

integer format: int32

**title**

required

Short, human-readable summary of the problem (e.g. “Not Found”).

string

**type**

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

##### Example

```json
{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://everruns.com/docs/errors/session_not_found"
}
```