Search¶

Message search matches indexed messages against a text query and a set of filters. TEBHOS indexes messages in Elasticsearch. Guild member search covers member search, and Discovery covers guild search.

There are two routes. Search messages (POST /search/messages) accepts user sessions and bot tokens and can search one channel, one guild, or every guild and direct message of the caller. Search messages (query string) (GET /messages/search) is an older, user-only TEBHOS form.

Every result is limited to channels the caller can read: in a guild channel the caller needs VIEW_CHANNEL and READ_MESSAGE_HISTORY, and in a private channel the caller must be a recipient. Messages in hidden channels never appear in results.

Search messages¶

POST /search/messages

Searches indexed messages and returns a global search result object. Accepts user sessions and bot tokens; a bot may only use the current scope.

Every hit is re-read from the message store before it is returned. A hit whose message no longer exists is dropped from the page and removed from the index, so a page can hold fewer entries than hits_per_page.

JSON body¶

Snowflakes may be sent as strings or numbers. Filters on the same list must all match (mentions, has, embed_type, link_hostname, attachment_filename, attachment_extension), except author_id and author_type, which match any listed value.

Response¶

Rate limit¶

20 requests per 10 seconds per account, on the search:messages bucket (shared with the query-string route).

Example¶

curl -X POST https://tebhos.com/api/v1/search/messages \
  -H "Authorization: Bot $TEBHOS_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"context_guild_id": "1489002177550843904", "content": "release notes", "has": ["link"], "hits_per_page": 10}'

Global search scopes¶

Global search result object¶

Global search content types¶

Search messages (query string)¶

GET /messages/search

The older TEBHOS search route. User-only: a bot token is rejected with 403 ACCESS_DENIED.

Searches indexed messages and returns a message search result object.

Every hit is re-read from the message store before it is returned. A hit whose message no longer exists is dropped from the page and removed from the index, so a page can hold fewer entries than limit.

Query parameters¶

An invalid date in before, after or during returns 400 BAD_REQUEST.

Response¶

Rate limit¶

20 requests per 10 seconds per user, on the search:messages bucket.

Example¶

curl -G "https://tebhos.com/api/v1/messages/search" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "q=release notes" \
  --data-urlencode "channel_id=1489002177550843905" \
  --data-urlencode "has=link,image" \
  --data-urlencode "sort=newest"

Search scopes¶

Direct message and group direct message channels are searched with channel_id; the caller must be a recipient.

Message search result object¶

Structure¶

total comes from the search index and is reduced by the number of stale hits dropped on the current page, so it is an estimate. Page through results by incrementing page until next_cursor is null.

The server_id-only form returns {"items": [...]} without the paging fields.

Example¶

{
  "items": [],
  "total": 0,
  "page": 1,
  "total_pages": 0,
  "next_cursor": null
}

Search content types¶

Values accepted by has and exclude_has. Unknown values are ignored.

Search sort modes¶