Faultsense Agent Payload Specification

Reference for building a collector backend that receives data from the faultsense browser agent.

Endpoint

The agent sends individual assertion results via navigator.sendBeacon to the configured collector URL. Each assertion is sent as a separate request with Content-Type: application/json.

Falls back to fetch POST in environments without sendBeacon.

Authentication

The api_key field in the POST body is the authentication mechanism. The agent will not send requests if apiKey is missing or empty.

Payload Schema

Each POST body is a single JSON object:

{
  "api_key": "your-api-key",
  "assertion_key": "checkout/submit-order",
  "assertion_trigger": "click",
  "assertion_type": "added",
  "assertion_type_value": ".success-message",
  "assertion_type_modifiers": {
    "text-matches": "Order confirmed"
  },
  "attempts": [],
  "condition_key": "success",
  "element_snapshot": "<button fs-assert=\"checkout/submit-order\" fs-trigger=\"click\" fs-assert-added-success=\".success-message\">Submit</button>",
  "release_label": "v2.4.1",
  "status": "passed",
  "timestamp": "2026-03-24T14:30:00.000Z",
  "user_context": { "userId": "u_123", "plan": "pro" },
  "user_cohorts": { "plan": "pro", "region": "us-east" },
  "agent_version": "0.5.4"
}

Field Reference

Modifiers

The assertion_type_modifiers object may contain any combination of these keys:

Additional keys may appear as attribute checks — any CSS bracket modifier that isn't a named modifier above becomes a generic attribute match with full match semantics (auto-anchored ^(?:value)$).

Behavioral Notes

Status Values

The agent resolves assertions to three statuses internally: passed, failed, and dismissed. Only passed and failed are sent to the collector. Dismissed assertions (e.g., losing conditional siblings) are silently dropped.

Error Context

JS errors do not instantly fail assertions. When an uncaught exception occurs, all pending assertions are tagged with error_context (first error wins). The assertion continues resolving normally. If it passes with error_context, the feature worked but a JS error occurred in the session. If it fails with error_context, the error is the likely cause. The agent does not generate failure reason strings — the collector derives human-readable failure messages from assertion metadata (type, selector, modifiers, timeout).

Status Transitions

The agent only sends an assertion when its status changes. An assertion that was already reported as passed won't be re-sent. The collector receives at most one request per assertion resolution.

No Batching

Assertions are sent individually, one POST per assertion. A single user interaction may produce multiple assertions, resulting in multiple concurrent requests.

Timing

• timestamp reflects when the user action occurred (trigger time), not resolution time.
• The request is sent at resolution time, which is timestamp + up to the assertion timeout.

MPA (Multi-Page App) Support

Assertions marked with mpa: "true" survive page navigations via localStorage. They are created on one page and resolved on the next. The collector sees no difference — these arrive as normal payloads.

Conditional Assertions

Multiple condition keys on the same element and type form a sibling group. The first conditional whose selector matches resolves the group — others are dismissed and not sent. The condition_key field identifies which condition was met. Unconditional assertions have an empty string "" for condition_key.

Suggested Collector Implementation

Minimum Viable Endpoint

POST /collector/
Content-Type: application/json

→ 200 OK (agent ignores response body)

The agent fire-and-forgets — it does not retry, read response bodies, or handle non-2xx responses beyond logging errors to the browser console. The collector should:

1. Validate api_key from the POST body
2. Parse and validate the JSON body against the schema above
3. Store the assertion result
4. Return 200

Storage Considerations

Key dimensions for querying assertion data:

• assertion_key — the primary grouping axis. Track pass/fail rates per key.
• release_label — compare assertion health across releases.
• status — aggregate pass/fail counts.
• condition_key — understand which outcomes are occurring.
• assertion_type + assertion_type_value — understand what was being checked.
• timestamp — time-series analysis.
• user_context — segment by user attributes (plan, role, etc.).
• user_cohorts — segment assertion health by low-cardinality cohort dimensions (plan tier, region, experiment group).
• error_context — correlate JS errors with assertion outcomes.

CORS

The agent uses sendBeacon (no custom headers) with fetch fallback. If the collector is on a different origin, standard CORS headers are required:

Access-Control-Allow-Origin: *  (or specific origins)
Access-Control-Allow-Headers: Content-Type
Access-Control-Allow-Methods: POST, OPTIONS