Unified Search

Search messages, users and channels with one free-text query in a single call. Use it to power a global search bar that shows results across all three entity types in one round trip, instead of calling message search, query users and query channels separately.

The dedicated endpoints are not deprecated. Use them when you need filters, sort overrides or larger pages than this endpoint exposes.

Searching everything at once

Send the search text, and optionally which entities to search and how many results to return per entity. How each entity is matched and sorted is fixed by the endpoint, see Search behavior and sorting.

curl -X POST "https://chat.stream-io-api.com/search/all?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "alice",
    "entities": ["messages", "users", "channels"],
    "limit": 10
  }'

The endpoint is POST /search/all. It accepts a client-side user token or server-side API key authentication. Examples are shown for the REST API and the server-side SDKs that already expose this endpoint.

Request

Field Type Required Default Description
query string yes The free-text search string, 1 to 80 characters after trimming whitespace.
entities string[] no ["messages", "users", "channels"] Which entities to search: any non-empty subset of the three. Duplicates are tolerated. Sections are always returned in the order messages, users, channels.
limit integer no 10 Maximum results per entity, 1 to 30. The same limit applies to every requested entity.
next object no {} Pagination cursors from a previous response, keyed by entity name. Include only the entities you want to continue paging. See Pagination.

A request fails with 400 when query is empty or longer than 80 characters, entities is empty or contains an unknown value, limit is outside 1 to 30, or next has a key other than the three entity names.

Response

Each requested entity gets its own section. A section is either a success, with an array of results and an optional next cursor, or an error object. Sections for entities you did not request are omitted.

{
  "messages": { "results": [...], "next": "<opaque>" },
  "users": { "users": [...], "next": "<opaque>" },
  "channels": { "channels": [...] },
  "duration": "42ms"
}

The objects inside each section are the same shapes the dedicated endpoints return, so your existing types apply:

Section Array key Element
messages results Message search hits, identical to GET /search.
users users User objects, identical to GET /users.
channels channels Channel objects, identical to POST /channels.

Channel results never include message previews or expanded member lists: message_limit and member_limit are always 0. Fetch the channel with POST /channels once the user picks a result.

The messages section carries results_warning in the same cases as GET /search, when the search covered only part of the channels the user can read.

Search as you type

When you call this endpoint from a search box, do not send a request on every keystroke. Each call searches up to three entities and costs one rate-limit request per entity (see Rate limits), so a user typing a 10-character name without debouncing can spend 30 requests in a few seconds.

  • Debounce input: wait until the user has paused typing (about 300 ms is a common choice) before calling.
  • Cancel or ignore stale requests: when a newer query is sent, abort the previous HTTP request, or discard its response if it arrives after a newer one, so older results never overwrite newer ones.
  • Search only what you display: pass entities to skip sections your UI does not show, which also lowers the cost per call.

Pagination

Each section returns its own next cursor when it has a further page. To fetch the next page of one entity, pass the cursor back under that entity's key in next, with the same query. Entities without a cursor in next start again at page 1, so you can page one entity while the others stay fresh.

curl -X POST "https://chat.stream-io-api.com/search/all?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "alice",
    "entities": ["messages"],
    "next": { "messages": "<next cursor from the messages section>" }
  }'

Rules for cursors:

  • Cursors are forward-only: each section returns a next cursor but no previous one, which fits a results list that loads more as the user scrolls. To go back, keep the pages you already fetched.

  • Cursors are opaque. Their format differs per entity and can change without notice, so store and send them back as-is rather than parsing or building them.

  • A cursor is valid only for the query it was issued with and only under the entity key it came from. A cursor that is invalid, that belongs to another entity or that was issued for a different query is rejected: that section restarts from page 1 and carries "warning": {"code": "cursor_rejected"}, and the response stays 200. For example, a valid messages cursor sent with a stale users cursor returns page 2 of messages and page 1 of users:

    {
      "messages": { "results": [...], "next": "..." },
      "users": {
        "users": [...],
        "next": "...",
        "warning": { "code": "cursor_rejected" }
      },
      "duration": "35ms"
    }
  • The whole request fails with 400 only when every cursor you supplied for a requested entity was rejected. One valid cursor is enough for the request to proceed.

  • A cursor for an entity you did not request is ignored, so you do not have to prune the next map between calls.

  • When a section omits next, you have reached its last page. The channels section cannot look ahead, so when the number of matching channels is an exact multiple of limit its final page is an empty array with no next.

Partial failures

If one entity's search fails, the response is still 200 and the other sections succeed normally. The failed section is replaced with an error object:

{
  "messages": { "results": [...], "next": "..." },
  "users": { "users": [...] },
  "channels": {
    "error": {
      "code": "backend_timeout",
      "message": "channels search timed out"
    }
  },
  "duration": "2004ms"
}
Code Meaning
backend_timeout This entity's search did not finish within the endpoint's time budget. Safe to retry.
backend_unavailable This entity's search was turned away because of load. Safe to retry with backoff.
unsupported This entity cannot be searched with your app's current configuration, for example when message search is disabled for the app. Retrying will not help; use the dedicated endpoint.
internal_error Unexpected server-side error. Contact support if it persists.

The message is a short fixed description per entity and never contains internal details. Display the successful sections and retry the failed one on the next interaction if appropriate.

A non-200 response is returned only when the request itself cannot be processed:

HTTP When
400 Validation failed, or every cursor supplied for a requested entity was invalid.
401 Missing or invalid authentication.
403 Every requested section failed with unsupported: your app's configuration cannot serve any of the requested entities.
429 Rate limit exceeded. See Rate limits.
503 Every requested section failed and at least one failure is backend_timeout or backend_unavailable. Retry with backoff.
500 Every requested section failed, none is retryable and at least one is internal_error.

The body is the standard error envelope. For 403, 500 and 503 its message summarises the per-section outcomes, for example all sections failed: messages=backend_timeout, users=internal_error.

Search behavior and sorting

Users and channels are matched with $autocomplete on name: the name of the user and the channel name. This is the same operator querying members supports on name, so results narrow with every character typed. Messages use full-text search.

Entity Match Order
messages Full-text match on the message text, with the same tokenization and stemming as GET /search. Most recent first.
users $autocomplete on the user name, so "a" matches "alice". The user id is not matched. Most recently created first, then by id. Not alphabetical.
channels $autocomplete on the channel name, among the channels the user is a member of. Most recently active first.

The match mode and sort cannot be changed per call, and query does not search the custom data on users or channels. Use the dedicated endpoints for filters, sorts, exact or regex matching, user lookup by id, searching channels the user is not a member of, or pages larger than 30.

Permissions

Results reflect what the authenticated principal is allowed to see. A user who may see some entities but not others gets empty arrays for the rest, never a per-section error or a 403.

Entity Filtering applied
messages Client-side requests search only the channels the user is a member of. Server-side requests with no user search all channels. A client-side token whose user has an admin or moderator role is scoped like any other user on this endpoint.
users The SearchUser permission is enforced per result. A user without it receives an empty users array.
channels Only channels the user is a member of are searched. A matching channel the user cannot read is dropped from the page rather than failing the request. A server-side request with no user receives an empty channels array.

In multi-tenant apps, client-side requests are confined to the caller's teams automatically and the team filter cannot be overridden. Server-side requests are not team-scoped; use the dedicated endpoints with an explicit team filter when you need a team-scoped search from the server.

Rate limits

Each call costs as many requests as the number of entities it searches: a default call costs 3, "entities": ["users"] costs 1. The cost is charged to this endpoint's own bucket, so it does not affect the budgets of GET /search, GET /users or POST /channels. The X-RateLimit-* response headers report the count after the full charge. When the bucket is exhausted the call fails with 429 and no section is searched.