Instant Results – Post Search API

In this article, you will find all the endpoints and parameters of the Post Search API, the ElasticPress.io API that powers the Instant Result feature. Generally, the ElasticPress plugin will handle everything for you, but if you are building a custom solution — like a headless website, for example — this is a great way to integrate your search experience with our servers.

The API is divided into two major functionalities:

• Post Search: the search itself, where a search term is sent and search results are returned and
• Post Search Template: a model of an Elasticsearch query, with a search term placeholder that is replaced every time a search is performed.

The domain to be used is your ElasticPress.io Host URL, which can be seen on your account page (typically something like https://<prefix>.us-east-1.staging.clients.hosted-elasticpress.io.)

The <index> parameter, present on all the endpoints, has to be replaced by your index name, which can be seen on the Health page of your account and follows the <prefix>--mysitecom-post-1 format.

Post Search Template

All the requests related to the Post Search Template need to be authenticated. That means you need to send an Authorization header with Basic base64_encoded(subscriptionID:subscriptionToken) as its value.

Post Search Template requests should NOT be sent by the public part of your headless solution, but only be part of your setup. Leaking your ElasticPress.io credentials can lead to data leaks and attacks, so make sure you are not sending any of these requests through your end users.

You can find your Subscription ID and Token on your account page. To encode it using the base64 format you can use online tools or call php -r "echo base64_encode('subscriptionID:subscriptionToken');" in your terminal.

PUT /api/v1/search/posts/<index>/template

Sending a PUT request to this endpoint with an Elasticsearch query as the request body will store that query as the model for all searches. Attention: The search term of that query should be {{ep_placeholder}}, so it can be replaced by the actual search term sent by the user later.

You can also see an example of a search query in the Understanding the default ElasticPress/Elasticsearch search query article.

GET /api/v1/search/posts/<index>/template

Sending a GET request to that endpoint will return the template previously stored with a 200 HTTP status code. If no template is found, the return will be a Search template not found. message with a 404 status code.

DELETE /api/v1/search/posts/<index>/template

Sending a DELETE request to that endpoint will delete the template previously stored. The return is empty and the status code is 204.

Post Search

GET /api/v1/search/posts/<index>

This is the endpoint responsible for returning search results and will be the one called by your application front end. It does not need the authorization header, as it is meant to be fired by your end-user browser.

Here is the query parameter list: