​

Thena entity search API

​

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

• 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

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

​

Streaming Results

• 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.

​

Best practices

• 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 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

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