---
title: "Subscribe to a connector event source"
method: POST
path: "/v1/agents/{agent_id}/event-subscriptions"
tags: ["Connectors"]
---

# Subscribe to a connector event source

`POST /v1/agents/{agent_id}/event-subscriptions`

## Request

- Base URL: `https://api.1claw.co`
- URL: `https://api.1claw.co/v1/agents/{agent_id}/event-subscriptions`
- Auth: HTTP bearer

Pairs an installed connector binding with one of its preset's event
sources (see `event_sources` on `GET /v1/connectors/presets`). 1Claw
then polls the source through the binding — same host and path
allowlists, same credential, same SSRF guard — keeps the item ids it has
seen, and dispatches each new item as an automation event of
`event_type`, so an automation with `trigger_type: event` and
`event_filter: { "event_type": "gmail.message.received" }` reacts within
one poll interval instead of on a cron it has to dedupe itself.

The first poll primes the subscription: it records what already exists
and emits nothing, so a new subscription does not replay the inbox. At
most 25 new items are emitted per poll (oldest first); lists come from
the source's first page only. Failures back off exponentially on the
interval and switch the subscription off after 20 in a row.

Human users only; the agent needs Execution Intents enabled. At most 20
subscriptions per agent. The event payload is
`{ "event_type", "payload": { "subscription_id", "binding_id", "binding", "connector", "item" } }`.

## Path parameters

- `agent_id` string, uuid, required

## Request body

- object
  - `binding_id` string, uuid, required
  - `event_type` string, required
  - `interval_secs` integer: Poll interval, at least the source's `min_interval_secs` and at most 86400. Defaults to the minimum.

## Response `201`

Subscribed

- EventSubscription
  - `id` string, uuid, required
  - `agent_id` string, uuid, required
  - `binding_id` string, uuid, required
  - `event_type` string, required
  - `interval_secs` integer, required
  - `is_active` boolean, required
  - `primed` boolean, required: False until the first poll has recorded what already exists. That poll emits nothing.
  - `next_poll_at` string, date-time, required
  - `last_polled_at` string, date-time, nullable
  - `last_error` string, nullable
  - `consecutive_errors` integer, required
  - `events_emitted` integer, required
  - `created_at` string, date-time, required

## Other responses

- `400`: Invalid request
- `403`: Insufficient permissions
- `404`: Resource not found
- `409`: This binding already subscribes to that event type

---

[API](https://skmtc.dev/1claw/apis/1claw-api.md) · [All operations](https://skmtc.dev/1claw/apis/1claw-api/llms.txt) · [OpenAPI document](https://skmtc.dev/1claw/apis/1claw-api/revisions/ae109b496830?raw)