Site Search

GET /search runs one full-text query across several content types and returns a flat list of hits. Use it for "find anything about X" features and for agents that need to locate a record before reading it through its own endpoint. Auth and the error envelope are covered in the API overview and Authentication.

curl "https://api.nimbu.io/search?q=summer%20sale&types=page,entry" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Nimbu-Site: $SITE_ID"

{
  "query": "summer sale",
  "types": ["page", "entry"],
  "degraded": false,
  "results": [
    {
      "id": "page:66f0a1b2c3d4e5f60718293a",
      "type": "page",
      "title": "Summer sale",
      "url": "https://www.example.com/summer-sale",
      "snippet": null
    },
    {
      "id": "entry:news:66f0a1b2c3d4e5f607182940",
      "type": "entry",
      "title": "Summer sale starts Monday",
      "url": "https://www.example.com/news/summer-sale-starts-monday",
      "snippet": null
    }
  ]
}

Parameters

customer and order are opt-in. They carry personal data, so they are only searched when you name them in types. Leaving types out never returns customers or orders. Blog articles are not part of site search.

Results are grouped by type in the order page, product, entry, collection, customer, order.

Scopes and access

Each type is checked against the same read access as its own list endpoint:

Requested types the token cannot read are dropped without an error. The types array in the response echoes what was actually searched, so compare it with what you asked for. When none of the requested types is readable the request fails: 401 for a caller without credentials, 403 with an "Insufficient scope" message for an authenticated one.

Result visibility follows the show endpoints:

• Channel entries are filtered by entry ACLs exactly like GET /channels/{channel_id}/entries/{id}. With use_acl and a customer session, only entries that customer may read are returned. See Channel access control.
• Only channels with search enabled are searched.
• Entries from sensitive channels are only included when the token may also read sensitive channels (read_sensitive_channels or write_sensitive_channels).
• Customers and orders are filtered by the same rules as their own show endpoints.

Result shape

To read the full record, split the id and call the resource endpoint, for example entry:news:66f0… becomes GET /channels/news/entries/66f0….

Degraded results

Each type is searched independently. When one type fails (for example its search index is unavailable), it contributes no results and the response sets "degraded": true. The request still returns 200 with whatever the other types found. Treat degraded: true as "results may be incomplete" and retry later or fall back to the per-type list endpoints.