Beacon: a search was refined (facet-change telemetry)

POST

/api/v2/search-events/refined

const url = 'https://crate.0xhoneyjar.xyz/api/v2/search-events/refined';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"search_event_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","changed_facets":[{"name":"genre","from":["example"],"to":["example"]}],"timestamp":"2026-04-15T12:00:00Z"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://crate.0xhoneyjar.xyz/api/v2/search-events/refined \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "search_event_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "changed_facets": [ { "name": "genre", "from": [ "example" ], "to": [ "example" ] } ], "timestamp": "2026-04-15T12:00:00Z" }'

Client beacon reporting facet changes that refined a prior search (≤10 changed facets). Authenticated with the per-search beacon JWT (Authorization: Bearer), NOT the X-API-Key. Body ≤512 bytes; idempotent.

Authorizations

BeaconBearerAuth

Request Body

application/json

object

search_event_id

required

string format: uuid

changed_facets

required

Array<object>

<= 10 items

object

name

required

string

Allowed values: genre style year_from year_to country format label q

from

Any of:

string

Any of:

string

timestamp

required

string format: date-time

Responses

204

Beacon accepted (idempotent no-op on duplicate)

Headers

X-RateLimit-Limit

integer

Requests allowed in the current window.

X-RateLimit-Remaining

integer

Requests remaining in the current window.

X-RateLimit-Reset

integer

Unix epoch (seconds) when the current window resets.

400

Validation failure — invalid_json, invalid_payload (with details = Zod flattened error object), or timestamp_skew (with skew_ms)

application/json

object

error

required

string

details

skew_ms

number

Example

{
  "error": "invalid_payload"
}

401

Beacon-token failure — missing_token, invalid_token, or token_search_event_mismatch

application/json

object

error

required

string

details

skew_ms

number

Example

{
  "error": "invalid_payload"
}

413

Payload too large (>512 bytes)

application/json

object

error

required

string

details

skew_ms

number

Example

{
  "error": "invalid_payload"
}