Articles in this section

Solve API Documentation

Solve API

This is the main endpoint that provides relevant documents for a given ticket or search query.



Example body:

"subject": "How to reset...",
"description": "I am unable...",
"session_id": "abc-123-def", (Optional)
"request_type": "search",
"max_num_results": 3,
"doc_types": [
], (Optional)
"offset": 0 (Defaults to 0)
  • “subject” - is a text field that represents the subject of the email. Leave empty if this API is being used to power a search bar.
  • “description” - is a text field that represents the body of the ticket, or the search query.
  • “session_id” - if there are successive requests (e.g. user keeps typing the ticket body), please include the session_id you’ve gotten on the first request to correctly track analytics. Don’t include “session_id” on the first request (it would be returned in the response).
  • “request_type” - one of “search” or “support_ticket”, depending on whether it’s being used via search bar (aka site-search), or on a page to file a support ticket.
  • “doc_types” - list of document types to return results for. Defaults to all available doc types.
  • “offset” - return results after `offset` (defaults to 0) - useful if API results are displayed with pagination
  • “language” - only return documents in a specific language (by default no restrictions). The values passed here are language codes such as “en”, “de” or “es”.
  • “paraphrase_answer” - if true, we’re going to use generative AI to rephrase the document in order to answer the given question. Note that in that case at most one result will be returned. If the best document does not answer the given question well, no results will be returned (and optionally you can fall back to paraphrase_answer=false).

SolveAPI  Documentation-3.png



Authentication is required and is done through a Bearer Token sent through request Headers. Forethought will provide the Token.



Example response:

  • session_id is the identifier of this user session that will be generated for the initial request and should be included in the subsequent requests throughout that session.
  • total_count is the total number of results available for this query. You can use this number to compute the total number of pages in case you’re using pagination.
  • documents is the list of resources used in the reply. Could be empty if no suitable documents were found. The documents would be labeled from the most relevant to the least relevant.
  • link is the link to the support document.
  • title is the title of the support document.
  • html is the html version of the support document fragment to provide to the user.
  • body is the plain text version of the support document fragment to provide to the user.


Usage Notes

Please make the requests to this endpoint whenever the user enters a whitespace character, after a pause in typing (typically 1-2 seconds), or presses the enter key rather than after every character.


Example Request As Curl Command

curl --location --request POST '' \

--header 'Authorization: Bearer <TOKEN>' \

--header 'Content-Type: application/json' \

--data-raw '{

"doc_types": ["upland_solution"],

"subject": "How to reset...",

"description": "I am unable...",

"max_num_results": 3,

"request_type": "search"



Tracking Events API

The tracking events endpoint collects data on how deflections are performing to provide analytics and improve performance.




Example body:

"session_id": "abc-123-def",
"document_id": "doc1", (Optional)
"event_type": "click"
  • “session_id” - identifier of the session for which this
  • “document_id” - identifier of which document did the event take place for (if known)
  • “event_type” - one of deflection_failed, click - specifies the event type that you wish to report. deflection_failed means that the user proceeded to file the support ticket, while click represents following the hyperlink for the document.



Authentication is required and done through a Bearer Token sent through request Headers. The token will be provided by Forethought.



Example response:

"success": true

The endpoint should acknowledge whether the response was processed or error (e.g. non-existent session).

Was this article helpful?
0 out of 0 found this helpful

More resources

  • Need support?

    Submit a request and our support team will assist you

  • Business hours

    Monday to Friday 8am - 5pm PST excluding US holidays

  • Contact us