Getting Started

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

Prerequisites

This tutorial assumes you have a Smart Search AI instance set up and running. If you haven’t done so already, please follow the Smart Search AI Setup Guide to create your instance.

Authentication Credentials

All API requests must be authenticated by sending a key (a.k.a. “Token”) in the Authorization header as a Bearer token.

Authorization: Bearer {your-api-key}

Find your credentials in the WP Engine User Portal, and save them securely.

WP Engine Hosted

1. Go to my.wpengine.com/products/smart_search
2. Open the 3-dot menu for your site
3. Select, “Show Credentials”
4. Save, “URL” - This is the URL you will use to send your GraphQL requests.
5. Save, “Access Token” - A private token used to authenticate your requests.

You should now have saved info that looks like this:

Credential	Example Value
GraphQL Endpoint	https://{site_slug}-{short_id}-atlassearch-{unique_id}-uc.a.run.app/graphql
Access Token	00000000-0000-4000-8000-000000000000

Tip

For applications that perform searches, a Search Token is also available in the WP Engine User Portal. This token is restricted to search actions and cannot be used for mutative operations like indexing or deleting documents; making it safe to use in public-facing code.

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.

Non-WP Engine Hosted

1. Go to my.wpengine.com/products/smart_search_per_site
2. Open the 3-dot menu for your site
3. Select, “API site credentials”
4. Save the “API URL” - This is the URL you will use to send your GraphQL requests.
5. Select, “Manage API Keys” from the modal
6. Select, “Generate new Credentials” to create a new “Full access” key
7. Save this API key for use in the next step. This is your private access token.

You should now have saved info that looks like this:

Credential	Example Value
GraphQL Endpoint	https://api.ai.wpengine.com/v1/smart-search/{instance-name}/graphql
Full Access Key	wpe_exampleFullAccessKey1234567890

Tip

For applications that only perform searches, a Read only key is also available in the WP Engine User Portal. This token is restricted to search actions and cannot be used for mutative operations like indexing or deleting documents; making it safe to use in public-facing code.

Danger

Treat your Full Access key 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.

Making your first request

You can make requests to the GraphQL endpoint using any HTTP client or dedicated GraphQL client.

This is an example of a basic find query using curl from the terminal of your choice.

WP Engine Hosted

Replace <your-smart-search-url> with your unique GraphQL endpoint and <your-access-token> with your access token.

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

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

// The response will look like this:

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

Non-WP Engine Hosted

Replace <your-api-url> with your unique API URL and <your-api-key> with your API key.

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

$ curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  --data '{ "query": "query { find(query: \"hello world\") { total } }" }' \
  <your-api-url>

// The response will look like this:

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

Tip

If you’re looking for a graphical interface to test your queries, popular choices include Hoppscotch, Postman, Insomnia, or Bruno.

Programmatic requests

You can also send Smart Search GraphQL requests directly from your application code.

JavaScript (Node.js)

Use this example with Node.js v18+ (built-in fetch) or modern browser environments.

const GQL_ENDPOINT = '{your-smart-search-url}';
const API_KEY = '{your-api-key}';

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

  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }

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

search('hello world').catch(console.error);

Python

This example uses the requests package.

import json
import requests

GQL_ENDPOINT = "{your-smart-search-url}"
API_KEY = "{your-api-key}"

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

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

    response = requests.post(
        GQL_ENDPOINT,
        headers=headers,
        data=json.dumps(payload),
        timeout=30,
    )
    response.raise_for_status()
    print(json.dumps(response.json(), 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 individual API pages.

Smart Search API reference guides

• Index API
• Find API
• Recommendations API
• Semantic Search Config API
• Synonyms API
• Content Extraction API
• Insights API
• MCP Server