Search API

This page specifies a proposed cross-object search contract. No public v1.0 search endpoint or universal-history query exists today; the grammar, limits, and responses below are target examples.

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 v1.0; 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 target index follows the deployment’s agreed retention window. No general lifetime-retention promise is made.
• Free-text matching is case-insensitive on whole words; there is no fuzzy matching in v1.0.
• 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.