Report what a browser saw

client_events.post

POST/api/v1/households/{household_id}/client-events

Route

The web app reports its own errors, its device database and sync, how long loading took, and screens that got stuck, up to 50 events at a time. No household data or names belong in them. They're kept 7 days.

Parameters#

Report what a browser saw: parameters
Field	Description
`household_id`pathstringrequired	The household's ID, hh_….

Request body#

JSON, as application/json.

Report what a browser saw: request body fields
Field	Description
`events`array of objectsrequired	1 to 50 items
`events[].kind`stringrequired	What happened, such as error, unhandled_rejection, host, first_data, read_failed, sync_error or stall. pattern ^[a-z][a-z0-9_.]{0,59}$
`events[].message`stringrequired	A short line about it, such as an error's message. at most 2,000 characters
`events[].detail`objectoptional	More about it, as a JSON object (sizes, timings, states).
`events[].at`integerrequired	When it happened, by the browser's clock, UTC milliseconds.
`events[].source`one of: page, workerrequired	page for the tab, worker for its device database worker.
`events[].tab_id`stringrequired	A random ID for the page load. 1 to 64 characters
`events[].client_id`string or nulloptional	The device's client ID, cli_…, once it has one. at most 64 characters
`events[].build`stringrequired	Which build of the web app. 1 to 64 characters
`events[].path`stringrequired	The page's path. at most 500 characters

Response#

204 Stored. No body.

Errors#

Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.

Report what a browser saw: errors
Status	Code	When
`400`	`validation_failed`	A field is missing, misspelled or out of range. details.fields lists each problem.
`401`	`unauthenticated`	The request has no valid session.
`403`	Read error.code	Described above.
`404`	`not_found`	The household doesn't exist, or you aren't a member of it.

Examples#

No call has been recorded for this operation yet, so this example is built from its schema. The values are placeholders.

Built from the schema

Not recorded from a real call: the fields are filled in from the schema, so the values are placeholders.

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/client-events' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -d '{
  "events": [
    {
      "kind": "error",
      "message": "an",
      "detail": {},
      "at": 1,
      "source": "page",
      "tab_id": "example",
      "client_id": "cli_01K9BKNGK0ENW3AHRZ6DMV29GQ",
      "build": "example",
      "path": "example"
    }
  ]
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/client-events", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    events: [
      {
        kind: "error",
        message: "an",
        detail: {},
        at: 1,
        source: "page",
        tab_id: "example",
        client_id: "cli_01K9BKNGK0ENW3AHRZ6DMV29GQ",
        build: "example",
        path: "example",
      },
    ],
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/client-events HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json

{
  "events": [
    {
      "kind": "error",
      "message": "an",
      "detail": {},
      "at": 1,
      "source": "page",
      "tab_id": "example",
      "client_id": "cli_01K9BKNGK0ENW3AHRZ6DMV29GQ",
      "build": "example",
      "path": "example"
    }
  ]
}

Response, 204

HTTP/1.1 204 No Content
X-Request-Id: req_01K9BKNGK0ENW3AHRZ6DMV29GQ