--- title: Getting Started description: Learn how to authenticate and make your first request to the Smart Search GraphQL API. url: https://developers.wpengine.com/docs/smart-search/getting-started/ image: https://developers.wpengine.com/og/docs/smart-search/getting-started.png --- # 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](https://wpengine.com/support/wp-engine-smart-search/) 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](https://developers.wpengine.com/docs/smart-search/getting-started/#tab-panel-0-0) - [Non-WP Engine Hosted](https://developers.wpengine.com/docs/smart-search/getting-started/#tab-panel-0-1) 1. Go to [my.wpengine.com/products/smart_search](https://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. ## 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](https://developers.wpengine.com/docs/smart-search/getting-started/#tab-panel-1-0) - [Non-WP Engine Hosted](https://developers.wpengine.com/docs/smart-search/getting-started/#tab-panel-1-1) Replace `` with your unique GraphQL endpoint and `` with your access token. Terminal window ```shell # 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 " \ --data '{ "query": "query { find(query: \"hello world\") { total } }" }' \ ``` ```json // 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](https://hoppscotch.io/), [Postman](https://www.postman.com/), [Insomnia](https://insomnia.rest/), or [Bruno](https://www.usebruno.com/). ## Programmatic requests You can also send Smart Search GraphQL requests directly from your application code. - [JavaScript (Node.js)](https://developers.wpengine.com/docs/smart-search/getting-started/#tab-panel-2-0) - [Python](https://developers.wpengine.com/docs/smart-search/getting-started/#tab-panel-2-1) Use this example with Node.js v18+ (built-in `fetch`) or modern browser environments. ```javascript 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); ``` ## 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](https://developers.wpengine.com/docs/smart-search/graphql-api/indexing/) > - [Find API](https://developers.wpengine.com/docs/smart-search/graphql-api/find/) > - [Recommendations API](https://developers.wpengine.com/docs/smart-search/graphql-api/recommendations/) > - [Semantic Search Config API](https://developers.wpengine.com/docs/smart-search/graphql-api/semantic-search-config/) > - [Synonyms API](https://developers.wpengine.com/docs/smart-search/graphql-api/synonyms/) > - [Content Extraction API](https://developers.wpengine.com/docs/smart-search/graphql-api/content-extraction-api/) > - [Insights API](https://developers.wpengine.com/docs/smart-search/graphql-api/insights/) > - [MCP Server](https://developers.wpengine.com/docs/smart-search/mcp/) ## Was this helpful? Thanks for the feedback! ```json {"@context":"https://schema.org","@graph":[{"@type":"WebSite","@id":"https://developers.wpengine.com/#website","name":"WP Engine Product Documentation","url":"https://developers.wpengine.com/","description":"Resources for developing, deploying, and scaling on WP Engine.","inLanguage":"en-US","keywords":["API documentation","product documentation","headless WordPress","managed WordPress hosting"],"publisher":{"@id":"https://wpengine.com/#organization"}}]} ```