API Reference

When using WOPR to expose search results to end-users, you have two choices:

  • Use our pre-built React component to render search results via a CMD+K menu. This is recommended for most use cases, and can be done in a few lines of code.
  • Use the API directly, which allows you to create your own UI for displaying search results to your users.

Note: If you decide to build your own UI library, please consider doing a PR against our pre-built component repository to help us improve the experience for everyone.

Authorization

Whenever doing API requests to WOPR, you must provide an authorization token. There are two keys which you should be aware of:

  • Your publishable key, which can be exposed client-side. Mainly used for search & feedback operations.
  • Your secret key, which shouldn't be exposed. This is used for administrative operations, such as re-indexing a project.

When using the API, you must supply the publishable or secret key as the value for an Authorization header.

Note: You shouldn't include a Bearer prefix to the token, as this will cause an error.

Search Documents

The core endpoint for searching over and returning documents.

POST https://wopr-api.operand.ai/services.ops.v1.OpsService/SearchDocuments

Required headers:
  Authorization: <publishable-key>

Request body:
{
    "query": "hello world",
    "max_results": 5
}

Expected status code: 200

Response body:
{
    "id": "85891c44-36f4-4c32-9aad-4a04c155c6f8",
    "documents": [
        {
            "id": "c113a82d-c020-493a-8944-3dd5077de6a2",
			"title": "A cool title here",
			"url": "https://example.com/cool-title",
			"snippet": "A small snippet from the document, relevant to the query."
		},
        ...
    ]
}

Some notes:

  • The project_id is the ID of the project you want to search. It can be found in the dashboard.
  • The query is the search query itself, and cannot be empty. An empty query will error.
  • max_results is the maximum number of results to return. If not specified, will default to 5.
    • Note: Max results is a maximum, WOPR will never return more than this number of results, but it may return less. This needs to be accounted for in your UI.

Feedback

Feedback is incredibly important, and we suggest that users submit feedback as much as they can in response to user behavior after a search. Specifically, we want to know when a user clicks on a search result, and how long it takes them to do so.

Behind the scenes, feedback is used to improve future search results and can be helpful when trying to understand areas for improvements within your technical documentation. For instance, poor clickthrough rates on a query can be a good indicator that your documentation doesn't contain a good answer for a given query.

POST https://wopr-api.operand.ai/services.ops.v1.OpsService/Feedback

Required headers:
  Authorization: <publishable-key>

Request body:
{
    "search_id": <id returned from search request>,
    "document_id": <id of the document that user clicked on>
}

Expected status code: 200

Response body: None

Some notes:

  • Feedback should be prioritized when integrating with WOPR, as it gives us a chance to improve our search results for your end-users, auto-magically.
  • You shouldn't wait to submit feedback, do so as soon as the user clicks on a search result.
  • It is reasonable and expected to submit feedback multiple times for a given search result. For instance, if a user performs a search, clicks on a result, then goes back to the search page and clicks on a different result, we want to submit feedback for both clicks.

Re-Index Project

Whenever the contents of your documentation change, we want to make sure that our indexes are always up-to-date. To do this, we expose an API endpoint which lets you manually re-index a project. We recommend that this be done on commit to your main branch, i.e., as a Github action. For a full tutorial on how to set this up, see the guide.

POST https://wopr-api.operand.ai/services.project.v1.ProjectService/ReIndexProject

Required headers:
  Authorization: <secret-key>

Request body: (Must be empty)
{}

Expected status code: 200

Response body: None

Some notes:

  • This endpoint will return instantly, i.e., indexing will happen in the background.
  • During indexing, search results will not be affected. Once complete, the new index will be swapped in atomically and search results will be updated without downtime.
  • Depending on the load of the system and the number of documents we're indexing, an indexing operation may take a little while to complete. We're actively working on some features which'll let you keep track of running indexing operations, and possibly even notifications for when they're complete.