Subscriptions and waits

Create a subscription

POST/v1/agent/subscriptions

Subscribes an inbox to events from a source, matched when the event arrives.

Parameters

Body parameters9

sourcestringRequired

Source ID or name.

inboxstringRequired

Inbox ID or name.

ttlintegerRequired

Seconds until it expires. At most 30 days.

filter?object

Conditions an event must match.

correlation?string

Match only events carrying this value.

once?boolean

Stop after the first match.

max_events?integer

Stop after this many matches.

transform?string

A transform for the view.

label?string

Your own task ID.

Returns

201The sample response is on the right.Errors return error and message; see Errors and limits.

curl -X POST "https://api.getensue.com/v1/agent/subscriptions" \ -H "authorization: Bearer $ENSUE_API_KEY" \ -H "content-type: application/json" \ -d '{"source":"stripe-prod","inbox":"billing-agent","correlation":"t_42","once":true,"ttl":3600}'

const res = await fetch("https://api.getensue.com/v1/agent/subscriptions", { method: "POST", headers: { authorization: `Bearer ${process.env.ENSUE_API_KEY}`, "content-type": "application/json", }, body: JSON.stringify({ "source": "stripe-prod", "inbox": "billing-agent", "correlation": "t_42", "once": true, "ttl": 3600 }), }); console.log(await res.json());

import os, requests res = requests.post( "https://api.getensue.com/v1/agent/subscriptions", headers={"authorization": f"Bearer {os.environ['ENSUE_API_KEY']}"}, json={ "source": "stripe-prod", "inbox": "billing-agent", "correlation": "t_42", "once": True, "ttl": 3600 }, ) print(res.json())

{ "id": "sub_9c4t…", "status": "active", "label": "t_42", "source": { "id": "src_8f2k…", "name": "stripe-prod" }, "destination": { "id": "dst_7q1c…", "name": "billing-agent", "type": "inbox" }, "correlation": "t_42", "max_events": 1, "matched": 0, "expires_at": "2026-11-11T10:00:00.000Z", "kind": "subscription" }

{"id":"sub_9c4t…","status":"active","label":"t_42","source":{"id":"src_8f2k…","name":"stripe-prod"},"destination":{"id":"dst_7q1c…","name":"billing-agent","type":"inbox"},"correlation":"t_42","max_events":1,"matched":0,"expires_at":"2026-11-11T10:00:00.000Z","kind":"subscription"}