Beacon: a search result was observed (cache-hit telemetry)

POST

/api/v2/search-events/observed

const url = 'https://crate.0xhoneyjar.xyz/api/v2/search-events/observed';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"search_event_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","source":"swr-cache-hit","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/observed \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "search_event_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "source": "swr-cache-hit", "timestamp": "2026-04-15T12:00:00Z" }'

Client beacon reporting a search result was observed from cache. Authenticated with the per-search beacon JWT (Authorization: Bearer), NOT the X-API-Key (the token is version-agnostic). Body ≤512 bytes; idempotent.

Authorizations

BeaconBearerAuth

Request Body

application/json

object

search_event_id

required

string format: uuid

source

required

string

Allowed values: swr-cache-hit client-cache-hit

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"
}