A portal or AI-agent session

POST

/v1/session

curl --request POST \
  --url https://stitch-collector-dev.magic-blocks.workers.dev/v1/session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "session_type": "ai_agent", "external_session_ref": "mb-sess-77120", "octopus_id": "88213", "anon_id": "3f1a8c2e-9b4d-4a71-8e2f-0c5d6a7b8e91", "started_at": 1772539200000, "ended_at": 1772539980000, "ai_channel": "web_chat", "ai_direction": "inbound", "ai_agent_id": "agent-dscr-qualifier", "ai_agent_version": "v3.2" }'

• Development. Production puts the collector on a first-party host per brand (t.makeabeeline.com, t.beelineequitynow.com); nothing in these contracts changes, only the hostname.

Sessions that do not happen in a browser we track: an authenticated portal, an AI agent’s conversation. Sent by whichever system runs the session, or a middleware in front of it. Unlike /v1/collect, a malformed payload is a loud 400: a silent success would hide a broken integration for weeks.

Authorizations

• webhookKey

Request Body ^required

Media type application/json

object

session_type

required

string

Allowed values: portal ai_agent

external_session_ref

required

Your id for the session. The idempotency key: re-sending returns the existing session_id.

string

octopus_id

The contact, when known.

string

anon_id

The page’s anonymous id when the session began on one of our pages, so the chat carries the visitor’s referral history.

string

started_at

required

Epoch milliseconds.

integer format: int64

ended_at

integer format: int64

brand_id

string

Allowed values: bll ben

ai_channel

web_chat, voice, sms, …

string

ai_direction

string

Allowed values: inbound outbound

ai_agent_id

string

ai_agent_version

string

Responses

202

Recorded (or found, when external_session_ref was seen before).

Media type application/json

object

session_id

required

string

Example ^generated

{
  "session_id": "example"
}

400

Malformed JSON or a payload missing what the endpoint needs. The body says which.

Media type application/json

object

error

required

What was wrong, in a sentence. A 401 carries unauthorized and nothing more.

string

Example ^generated

{
  "error": "example"
}

401

No key, or a key the collector does not know. Nothing was written.

Media type application/json

object

error

required

What was wrong, in a sentence. A 401 carries unauthorized and nothing more.

string

Example

{
  "error": "unauthorized"
}

405

Only the method shown is served.