Skip to content
INSIDEINSIDEINSIDE Gateway
Console

Create a subscription

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

Required scopes: website_read, event_read
Data access: –
MCP tool: subscription_create
Note: Write
Note: optional Idempotency-Key

Create a thin pull subscription; maximum 20 per installation. This does not start webhooks or socket connections. An authenticated app socket can separately attach a reader to this same thin pull subscription. 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

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
>= 1 characters <= 128 characters /^[\x21-\x7e]{1,128}$/

Request Bodyrequired

Section titled “Request Bodyrequired”
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

Section titled “Responses”

200

Section titled “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"
    }
  }
}

201

Section titled “201”

Subscription, revision 1 and HMAC-authenticated initial cursor.

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

Section titled “400”

Malformed, duplicate, unsupported input or invalid cursor signature.

401

Section titled “401”

Expired, revoked or changed credential authority.

404

Section titled “404”

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

409

Section titled “409”

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

422

Section titled “422”

Full payloads or other delivery modes are unavailable.

429

Section titled “429”

Application request quota exceeded.

503

Section titled “503”

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

INSIDE by PowerfrontChangelogOpenAPI documentllms.txt