Developer: Cli sessions

Base URL: $BUSINESS_API

List the CLI sessions listening now

Logs

GET /developer/cli-sessions

Returns the tenant's live CLI sessions, newest first, with cursor pagination, so the dashboard can show who is listening and to which events. Secrets are never returned here. Requires developer:read.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Live sessions

Show attributes
dataarray of DeveloperCliSession · optional
Show child attributes
idstring · required

Session identifier, starting with cls_.

tenant_idstring · required

Tenant the session listens to.

eventsarray of string · required

Event types the session receives; empty means every type.

created_bystring · required

User who opened the session; only they can poll or end it.

created_atstring (date-time) · required

When the session was opened.

expires_atstring (date-time) · required

When the session ends unless polled again.

secretstring · optional

The whsec_ signing secret, present only in the response that opens the session.

has_moreboolean · optional
next_cursorstring · optional

Errors 401 · 403

Permissions developer:read · Roles: admin, owner

curl -X GET "$BUSINESS_API/developer/cli-sessions" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "dev_20UrPQc1lwaN5oeD7Q8xFo2l3KG",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "events": [
        "event"
      ],
      "created_by": "created by",
      "created_at": "2026-11-19T09:30:00Z",
      "expires_at": "2026-11-19T09:30:00Z",
      "secret": "secret"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Open a temporary webhook endpoint for the CLI

Logs

POST /developer/cli-sessions

Opens a session for the CLI's webhooks listen command: a temporary endpoint that receives the tenant's new events, signed with its own whsec_ secret, returned once in this response. events limits the session to some event types; empty means every type. The session lives while the CLI polls it and expires about 90 seconds after the last poll. Requires developer:write.

Body application/json

eventsarray of string · optional

Event types to receive; empty or absent means every type.

Returns

201 Session, with its secret shown once

Show attributes
idstring · required

Session identifier, starting with cls_.

tenant_idstring · required

Tenant the session listens to.

eventsarray of string · required

Event types the session receives; empty means every type.

created_bystring · required

User who opened the session; only they can poll or end it.

created_atstring (date-time) · required

When the session was opened.

expires_atstring (date-time) · required

When the session ends unless polled again.

secretstring · optional

The whsec_ signing secret, present only in the response that opens the session.

Errors 400 · 401 · 403

Permissions developer:write · Roles: admin, owner

curl -X POST "$BUSINESS_API/developer/cli-sessions" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "events": [
    "event"
  ]
}'
Response 201
{
  "id": "dev_20UrPQc1lwaN5oeD7Q8xFo2l3KG",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "events": [
    "event"
  ],
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "expires_at": "2026-11-19T09:30:00Z",
  "secret": "secret"
}

Wait for the next events of a CLI session

Logs

GET /developer/cli-sessions/{id}/events

Long-polls a CLI session: returns the events published since the previous poll, oldest first and at most 50, each with its genuine payload and the Standard Webhooks headers signed with the session secret. When none is ready the request is held for up to wait seconds. Each poll extends the session. Only the user who opened the session can poll it; an expired or unknown session returns 404. Requires developer:read.

Parameters

idstring · path · required

Identifier of the CLI session, as returned when it was opened.

waitinteger · query · optional

Seconds to hold the request while no event is ready, from 0 (answer at once) to 25.

Returns

200 Events since the previous poll

Show attributes
dataarray of DeveloperCliSessionEvent · required

Events since the previous poll, oldest first.

Show child attributes
idstring · required

Event identifier.

typestring · required

Event type, for example invoice.paid.

created_atstring (date-time) · required

When the event was published.

payloadobject · required

The event body exactly as webhook endpoints receive it.

webhook_idstring · required

Value for the webhook-id header.

webhook_timestampinteger (int64) · required

Value for the webhook-timestamp header (Unix seconds).

webhook_signaturestring · required

Value for the webhook-signature header (v1,<base64 HMAC-SHA256>).

expires_atstring (date-time) · required

When the session ends unless polled again.

Errors 400 · 401 · 403 · 404

Permissions developer:read · Roles: admin, owner

curl -X GET "$BUSINESS_API/developer/cli-sessions/{id}/events" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "dev_2v3q459KmXHCUJVGQHR8WdLsQNb",
      "type": "active",
      "created_at": "2026-11-19T09:30:00Z",
      "payload": {},
      "webhook_id": "whk_2Fhestrmgp5E6phyoldkw1BQmj3",
      "webhook_timestamp": 1,
      "webhook_signature": "webhook signature"
    }
  ],
  "expires_at": "2026-11-19T09:30:00Z"
}

End a CLI session

Logs

DELETE /developer/cli-sessions/{id}

Ends a CLI session at once; the CLI calls this when it exits. Only the user who opened the session can end it. Requires developer:write.

Parameters

idstring · path · required

Identifier of the CLI session to end.

Returns

204 Session ended

Errors 401 · 403 · 404

Permissions developer:write · Roles: admin, owner

curl -X DELETE "$BUSINESS_API/developer/cli-sessions/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 204

Session ended