​
Thena entity search API

Welcome to the Thena entity search API! This API provides powerful, flexible search capabilities across your core business data—tickets, accounts, and comments—using a unified, Typesense-powered interface.

​
What can you do with Thena search?

  • Full-text search across multiple collections
  • Advanced filtering and faceting using Typesense syntax
  • Customizable field selection for efficient, tailored responses
  • Sorting and pagination for large result sets
  • Consistent, secure access scoped to your organization and teams

​
Supported collections

You can search the following collections:

  • tickets: Support tickets, requests, or issues
  • accounts: Customer or company accounts
  • comments: Comments or notes attached to tickets or other entities
  • customer_contacts: (Contact support coming soon)

​
Endpoint

GET /v1/search/{collection}
  • collection (path parameter): The entity collection to search. Must be one of the supported collections above.

​
Key query parameters

NameTypeRequiredDescription
qstringYesThe search query string. Use * for a wildcard search.
query_bystringYesComma-separated list of fields to search in (e.g. title,description).
per_pagestringNoNumber of results per page. Default: 20.
pagestringNoPage number for pagination.
include_fieldsstringNoComma-separated list of fields to include in the response.
filter_bystringNoFilter expression using Typesense syntax (e.g. priorityName:=medium&&statusName:=resolved).
sort_bystringNoSort expression (e.g. createdAt:desc).
streamingboolNoIf true, enables streaming of paginated results.

Tip: You can use any Typesense search parameter for advanced use cases, including faceting, typo tolerance, and more.

​
Streaming Results

Thena’s search API supports streaming large result sets for improved performance and responsiveness. To enable streaming, add the streaming=true query parameter to your request.

  • How it works:
    When streaming=true is set, the API will stream each page of results as a separate JSON object. Each chunk is a full page of results, using the same structure as a normal (non-streaming) response.
  • Maximum page size:
    When streaming, the per_page parameter cannot exceed 250. If a higher value is provided, it will be capped at 250.
  • End of stream:
    The stream ends with a final chunk: { "done": true }.
  • Error handling:
    If an error occurs during streaming, a chunk with { "error": "..." } will be sent, and the stream will close.

​
Example request

curl -N -G \
  'https://api.thena.com/v1/search/tickets' \
  --data-urlencode 'q=*' \
  --data-urlencode 'query_by=title,description' \
  --data-urlencode 'per_page=100' \
  --data-urlencode 'streaming=true' \
  -H 'Authorization: Bearer <your_token>'

​
Example streamed response

{ ...page 1 results... }
{ ...page 2 results... }
...
{ "done": true }

Note: Each chunk is a full page of results in the same format as a normal search response. Process each chunk as it arrives for best performance.

​
Additional recommendations for developers

  • Process as you go: Don’t wait for the entire response—process each chunk as it arrives.
  • Respect per_page limit: If you request more than 250 results per page, only 250 will be returned per chunk.
  • Detect end of stream: Always check for the { "done": true } chunk to know when the stream is complete.
  • Handle errors: Be prepared to handle a chunk with an error property.

Ready to get started? Explore the detailed API reference for entity search to see available fields, example queries, and sample responses!

​
Best practices

Follow these tips to get the most out of the Thena entity search API:

Do:

  • Use the include_fields parameter to limit results to only the fields you need—this improves performance and reduces payload size.
  • Use specific query_by fields relevant to your use case for more accurate results.
  • Combine multiple filters in filter_by using && for precise targeting (e.g. status:=open&&priority:=high).
  • Use pagination (per_page and page) for large result sets to avoid timeouts and improve user experience.
  • Use Typesense’s advanced search parameters (faceting, typo tolerance, etc.) for complex needs.

Don’t:

  • Don’t use * as your query unless you really want all results—prefer a more specific search string when possible.
  • Don’t request all fields unless necessary; avoid omitting include_fields for large collections.
  • Don’t use overly broad filters or sort expressions, as this can slow down search performance.
  • Don’t expose sensitive fields in your include_fields or query logic.

​
Roadmap

The following features are coming soon:

  • Federated search (search across multiple collections in a single query)
  • Vector/similarity search (semantic and embedding-based search)