Search API

The list endpoints answer "show me recent X". Search answers investigative questions: everything that ever touched one order, every refusal by one rule, every action a given operator proposed against one asset last week. One endpoint queries across events, plans, actions, and receipts with a compact filter grammar and returns typed hits. Search is part of the v0.9 preview register.

Shared conventions, including authentication, pagination, and the error envelope, are defined in the API overview. Error codes are catalogued in Errors.

Executes one query. Results are ordered newest first by the hit's own timestamp and cursor-paginated with the standard limit and cursor parameters. A hit is only returned if the calling key could read the underlying object directly, so search never widens what a key can see; workspace-pinned keys search their workspace only.

#The filter grammar

A query is a sequence of terms separated by spaces. All terms must match (implicit AND). Three kinds of terms exist:

Free text matches over reasoning strings, payload values, and error messages. Values containing spaces or colons beyond the first are quoted: entity:"room:12 west". Prefix a term with - to negate it: -disposition:DEDUP. OR is not supported in v0.9; run two queries.

Filterable fields, by the object types they apply to:

#The search response

Hits arrive in the standard list envelope. Each hit wraps the matched object with its type and timestamp so mixed-type results sort and render without inspection.

curl -G https://api.fibric.io/v1/search \
  -H "Authorization: Bearer $FIBRIC_KEY" \
  --data-urlencode 'q=entity:order:SO-10884 at>=2026-07-01' \
  --data-urlencode 'limit=50'

{
  "object": "list",
  "data": [
    {
      "object": "search_hit",
      "type": "receipt",
      "at": "2026-07-02T15:04:41Z",
      "hit": {
        "id": "rc_5b21",
        "object": "receipt",
        "tool": "order.hold",
        "entity_key": "order:SO-10884",
        "outcome": "applied"
      }
    },
    {
      "object": "search_hit",
      "type": "plan",
      "at": "2026-07-02T15:02:09Z",
      "hit": {
        "id": "pl_7c1a",
        "object": "execution_plan",
        "operator_id": "op_8f2a1c",
        "status": "executed"
      }
    },
    {
      "object": "search_hit",
      "type": "event",
      "at": "2026-07-02T14:58:01Z",
      "hit": {
        "id": "ev_3a91c7",
        "object": "event",
        "source": "magento",
        "event_type": "order.updated"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Hits carry summary objects; retrieve the id on its own reference endpoint for the full record. The mixed-type, newest-first result reads as a timeline: the example above is the envelope-to-receipt chain for one order, reconstructed in one call.

#Worked examples

curl -G https://api.fibric.io/v1/search \
  -H "Authorization: Bearer $FIBRIC_KEY" \
  --data-urlencode 'q=verdict:BLOCK tool:order.refund at>=2026-06-01' \
  --data-urlencode 'types=receipt'

#Limits and behavior

• Queries are bounded to 512 characters and at most 12 terms; longer queries fail with 400 invalid_parameter.
• Search draws from the read budget of its own route class; see Rate limits & quotas.
• The index covers the same retention window as the underlying objects. Events and receipts are retained for the life of the tenant during early access.
• Free-text matching is case-insensitive on whole words; there is no fuzzy matching in v0.9.
• The grammar is additive within the major version: new filterable fields may appear, existing fields keep their meaning.

#Errors

Malformed-query errors name the offending term in message. As everywhere, branch on code; see Errors.