---
title: Subscriptions
path: reference/subscriptions
status: published
---

# Subscriptions Reference

Endpoint reference for path-scoped event subscriptions. For the concept, see [Events and Webhooks](../core-concepts/events-and-webhooks).

Subscriptions differ from webhooks: they scope to specific paths, and they support **polling** as a delivery mechanism (useful when your service can't receive inbound HTTP).

**Base path:** `/v1/subscriptions/`

## GET /v1/subscriptions

List subscriptions.

**Scope:** `subscriptions:read`.

## POST /v1/subscriptions

Create.

Body:

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | |
| `paths` | Yes | Array of globs |
| `events` | Yes | Event types |
| `delivery.type` | Yes | `webhook` or `polling` |
| `delivery.url` | For webhook | |
| `delivery.secret` | For webhook | Signing secret |
| `delivery.buffer_size` | For polling | Max queued events (default 1000) |
| `filters` | No | Extra filters |

Response `201 Created`: `id`, `name`, `status`, `identity_id` (the caller — subscriptions are owned).

**Scope:** `subscriptions:write`.

## GET /v1/subscriptions/{id}

## PATCH /v1/subscriptions/{id}

Update paths, events, delivery.

## DELETE /v1/subscriptions/{id}

## GET /v1/subscriptions/{id}/poll

Long-poll for events. Blocks until an event arrives or `timeout` elapses.

Query:

| Name | Type | Description |
|------|------|-------------|
| `timeout` | seconds | Up to 60, default 30 |
| `since_event_id` | string | Deliver events after this ID |
| `max_events` | integer | Default 100 |

Response:

```json
{
  "events": [
    {
      "event_id": "evt_01HK...",
      "event_type": "secret.rotated",
      "timestamp": "...",
      "path": "integrations/salesforce/oauth",
      "data": {"old_version": 3, "new_version": 4}
    }
  ],
  "has_more": false
}
```

On timeout with no events, returns `{"events": [], "has_more": false}`.

**Scope:** subscription owner only.

## POST /v1/subscriptions/{id}/ack

Acknowledge processed events (for polling delivery). Without ack, events re-deliver on reconnect.

Body: `{"event_ids": ["evt_abc", "evt_def"]}`.

## Related

- [Webhooks Reference](./webhooks)
- [Events and Webhooks (Concepts)](../core-concepts/events-and-webhooks)