Replace a subscription

PATCH

/api/v1/subscriptions/{subscription_id}

curl --request PATCH \
  --url https://api.inside.chat/api/v1/subscriptions/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'If-Match: example' \
  --data '{ "website_ids": [ "example" ], "event_types": [ "conversation.changed" ], "payload_mode": "thin", "delivery": { "mode": "pull" }, "start": "beginning" }'

• Hosted Gateway
• Local development

Required scopes: website_read, event_read
Data access: –
MCP tool: subscription_replace
Note: Write
Note: optional Idempotency-Key
Note: If-Match required

Replace the complete website/type definition with a matching If-Match revision and explicit new boundary. Old cursors return subscription_revision_changed. With an Idempotency-Key, the same input and effective authority reuse the original result for 24h. Changed input conflicts; changed/deleted targets and expired access withhold saved results. Without a key each request is a new effect. After 24h a key can start a new effect; reconcile before retrying beyond the window.

Authorizations

• installation_token
• oauth_client_credentials
  website_read event_read

Parameters

Path Parameters

subscription_id

required

string

/^sub_[a-f0-9]{32}$/

Header Parameters

If-Match

required

string

/^"[1-9][0-9]*"$/

Idempotency-Key

string

>= 1 characters <= 128 characters /^[\x21-\x7e]{1,128}$/

Request Body^required

Media typeapplication/json

object

website_ids

required

Array<string>

>= 1 items <= 50 items unique items

event_types

required

Array<string>

>= 1 items <= 35 items unique items

Allowed values: conversation.changed conversation.removed conversation.snapshot conversation.gap conversation.heartbeat visitor.changed visitor.removed visitor.snapshot visitor.gap visitor.heartbeat operator.changed operator.removed operator.snapshot operator.gap operator.heartbeat queue.changed queue.removed queue.snapshot queue.gap queue.heartbeat website.changed website.removed website.snapshot website.gap website.heartbeat privacy.changed privacy.removed privacy.snapshot privacy.gap privacy.heartbeat capture.changed capture.removed capture.snapshot capture.gap capture.heartbeat conversation.* visitor.* operator.* queue.* website.* privacy.* capture.*

payload_mode

required

string

Allowed value: thin

delivery

required

object

mode

required

Allowed value: pull

start

required

Beginning starts at cursor zero and reports any retention gap. retained explicitly starts immediately before the oldest retained receipt; reconcile current REST resources before resetting after an expired cursor.

string

Allowed values: beginning retained

Responses

200

Current installation-authorized thin metadata. Cursors contain independent per-website positions; no total order is promised.

Media typeapplication/json

object

subscription

required

object

subscription_id

required

string

/^sub_[a-f0-9]{32}$/

website_ids

required

Array<string>

>= 1 items <= 50 items unique items

event_types

required

Concrete event types; family wildcards are expanded.

Array<string>

Allowed values: conversation.changed conversation.removed conversation.snapshot conversation.gap conversation.heartbeat visitor.changed visitor.removed visitor.snapshot visitor.gap visitor.heartbeat operator.changed operator.removed operator.snapshot operator.gap operator.heartbeat queue.changed queue.removed queue.snapshot queue.gap queue.heartbeat website.changed website.removed website.snapshot website.gap website.heartbeat privacy.changed privacy.removed privacy.snapshot privacy.gap privacy.heartbeat capture.changed capture.removed capture.snapshot capture.gap capture.heartbeat

revision

required

Send as If-Match: “” to replace or delete.

integer

>= 1

status

required

Allowed value: active

payload_mode

required

Allowed value: thin

delivery

required

object

mode

required

Allowed value: pull

created_at

required

Unix seconds.

integer

updated_at

required

Unix seconds.

integer

cursor

required

Opaque signed cursor. Pass it unchanged as after on the next events request.

string

Example

{
  "subscription": {
    "event_types": [
      "conversation.changed"
    ],
    "status": "active",
    "payload_mode": "thin",
    "delivery": {
      "mode": "pull"
    }
  }
}

400

Malformed, duplicate, unsupported input or invalid cursor signature.

401

Expired, revoked or changed credential authority.

404

Subscription or website not granted; restriction filters and human consent credentials are unavailable for this feed.

409

Changed subscription revision, concurrent mutation, inventory limit, or replay_expired requiring reconciliation.

429

Application request quota exceeded.

503

Event family held, corrupt subscription or unavailable journal/control observations.