Error

A valid request URL is required to generate request examples

{
  "contractVersion": 2,
  "batchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "recorded": 250,
  "rejected": [
    {
      "index": 123,
      "reason": "<string>"
    }
  ]
}

{
  "error": {
    "code": "invalid_argument",
    "message": "<string>"
  },
  "contractVersion": 2,
  "recorded": 0,
  "rejected": [
    {
      "index": 249,
      "reason": "<string>"
    }
  ],
  "batchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "error": {
    "code": "unauthorized",
    "reason": "missing_credentials",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "backend_resolution_failed",
    "message": "<string>",
    "retryable": true
  }
}

{
  "error": {
    "code": "batch_id_reused",
    "message": "<string>"
  },
  "contractVersion": 2,
  "batchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "recorded": 0,
  "rejected": [
    {
      "index": 123,
      "reason": "<string>"
    }
  ]
}

{
  "error": {
    "code": "payload_too_large",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "backend_resolution_failed",
    "message": "<string>",
    "retryable": true
  }
}

{
  "error": {
    "code": "backend_resolution_failed",
    "message": "<string>",
    "retryable": true
  }
}

Usage

Console behavior events

Contract version 2. Send a client-generated batch UUID with immutable request contents on retries. Within your organization and signed-in person, the first successful response is replayed for 24 hours without writing more events or extending the window. After expiration, the UUID can identify a new batch. A different projected batch (events and dropped count) under a live UUID returns 409 batch_id_reused with no writes. Authentication, rate limits and complete batch validation apply before replay.

Any invalid event refuses the whole batch with indexed HTTP 400 and zero event or batch-receipt writes. Only successful responses are cached. Unknown kinds are refused; unknown detail fields are discarded. Device identifiers, idempotency keys and fields containing serial, udid, imei or email are never stored. An API key cannot report browser events.

Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404.

POST

console

events

Error

A valid request URL is required to generate request examples

{
  "contractVersion": 2,
  "batchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "recorded": 250,
  "rejected": [
    {
      "index": 123,
      "reason": "<string>"
    }
  ]
}

{
  "error": {
    "code": "invalid_argument",
    "message": "<string>"
  },
  "contractVersion": 2,
  "recorded": 0,
  "rejected": [
    {
      "index": 249,
      "reason": "<string>"
    }
  ],
  "batchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "error": {
    "code": "unauthorized",
    "reason": "missing_credentials",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "backend_resolution_failed",
    "message": "<string>",
    "retryable": true
  }
}

{
  "error": {
    "code": "batch_id_reused",
    "message": "<string>"
  },
  "contractVersion": 2,
  "batchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "recorded": 0,
  "rejected": [
    {
      "index": 123,
      "reason": "<string>"
    }
  ]
}

{
  "error": {
    "code": "payload_too_large",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "backend_resolution_failed",
    "message": "<string>",
    "retryable": true
  }
}

{
  "error": {
    "code": "backend_resolution_failed",
    "message": "<string>",
    "retryable": true
  }
}

Authorizations

Authorization

string

header

required

The control surface credential. Send Authorization: Bearer <token>.

Two kinds of token are accepted and they are told apart by shape, not by a separate header. A token beginning pbk_ is an org scoped API key, whose public half and secret half are generated together and of which only a hash of the secret is ever stored; anything else is treated as an OAuth 2.1 access token and verified against the authorization server's keys.

Both resolve to the same context: an org, a principal and a set of scopes. Nothing downstream branches on which channel you used, with one deliberate exception, key management, which requires a signed-in person so that a key can never mint another key.

Scopes are enforced when MCP tools are REGISTERED rather than when they are called, so a tool your credential cannot use is absent from tools/list rather than refused mid gesture.

Body

application/json

At most 500 events and 262144 UTF-8 bytes, before field filtering.

batchId

string<uuid>

required

Client UUID, retained unchanged across retries of the same request.

Required string length: 36

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

events

object[]

required

Required array length: 1 - 500 elements

Show child attributes

dropped

integer

default:0

How many events the queue dropped before this batch.

Required range: 0 <= x <= 1000000000

Response

The complete batch committed, or its original success body was replayed. No partial acceptance.

contractVersion

integer

required

batchId

string<uuid>

required

Required string length: 36

recorded

integer

required

Required range: 1 <= x <= 500

rejected

object[]

required

Show child attributes

Overview

Endpoints

Console behavior events

Authorizations

Body

Response