Getting Started with Smart Search

Getting Started

This guide will walk you through authenticating with the Smart Search API and making your first search request.

Tip

For client-side applications where you need to perform searches directly from the browser, a read-only Search Token is also available in the WP Engine User Portal. This token is specifically restricted to search actions and cannot be used for any mutative operations like indexing or deleting documents, making it safe to use in public-facing code.

Authentication

To use the Smart Search API, you need two pieces of information, which can be found in your WP Engine User Portal:

1. Your GraphQL Endpoint: This is the unique URL for your environment’s API. It will look something like {your-smart-search-url}.
2. Your Access Token: This is a private token used to authenticate your requests.

Danger

Treat your Access Token like a password. It is private and grants full access to your environment’s data. Do not share it, publish it, or commit it to public repositories, code samples, or support forums.

All API requests must be authenticated by sending your access token in the Authorization header as a Bearer token.

Making Your First Request

You can make requests to the GraphQL endpoint using any HTTP client or dedicated GraphQL client. Popular choices include Postman, Insomnia, Altair, or Bruno.

Below is an example of a basic find query using curl.

Replace {your-smart-search-url} with your unique GraphQL endpoint and {your-access-token} with your private access token. For client-side requests, it is highly recommended to use the read-only Search Token.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {your-search-token}" \
  --data '{ "query": "query { find(query: \"hello world\") { total } }" }' \
  {your-smart-search-url}

This request performs a simple search for “hello world” and will return the total number of matching documents.

{
  "data": {
    "find": {
      "total": 123
    }
  }
}

Programmatic Examples

Here are some examples of how to make a request programmatically in a few common languages.

JavaScript (Node.js)

This example uses the built-in fetch API available in Node.js v18+ and modern browsers.

const GQL_ENDPOINT = '{your-smart-search-url}';
const SEARCH_TOKEN = '{your-search-token}';

async function search(query) {
  const response = await fetch(GQL_ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${SEARCH_TOKEN}`,
    },
    body: JSON.stringify({
      query: `
        query FindQuery($query: String!) {
          find(query: $query) {
            total
            documents {
              id
              data
            }
          }
        }
      `,
      variables: {
        query: query,
      },
    }),
  });

  const result = await response.json();
  console.log(JSON.stringify(result, null, 2));
}

search('hello world');

Python

This example uses the popular requests library.

import requests
import json

GQL_ENDPOINT = "{your-smart-search-url}"
# It is highly recommended to use the read-only Search Token for client-side applications.
SEARCH_TOKEN = "{your-search-token}"

def search(query):
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {SEARCH_TOKEN}",
    }

    graphql_query = {
        "query": """
            query FindQuery($query: String!) {
                find(query: $query) {
                    total
                    documents {
                        id
                        data
                    }
                }
            }
        """,
        "variables": {
            "query": query
        }
    }

    response = requests.post(GQL_ENDPOINT, headers=headers, data=json.dumps(graphql_query))
    response.raise_for_status()

    result = response.json()
    print(json.dumps(result, indent=2))

search("hello world")

Next Steps

Now that you know how to authenticate and make a basic request, you can explore the full capabilities of the API. For a complete guide to all available parameters, operators, and advanced features, please see the Find API Reference.