Connectors

Subscribe to a connector event source

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" } }.

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

Path parameters

agent_idstring uuid required

Request body

binding_idstring uuid required
event_typestring required
interval_secsinteger

Poll interval, at least the source's min_interval_secs and at most 86400. Defaults to the minimum.

Example request

{
  "event_type": "gmail.message.received"
}

Response

Subscribed

idstring uuid required
agent_idstring uuid required
binding_idstring uuid required
event_typestring required
interval_secsinteger required
is_activeboolean required
primedboolean required

False until the first poll has recorded what already exists. That poll emits nothing.

next_poll_atstring date-time required
last_polled_atstring date-time nullable
last_errorstring nullable
consecutive_errorsinteger required
events_emittedinteger required
created_atstring date-time required

Example response

{
  "event_type": "gmail.message.received"
}

Changes

No recorded changes to this operation across all 1 revision of this API.