Search API

Updated April 27, 2026 13:27

The Search API returns JSON search results from a Site Search App through the /emselect endpoint.

Use this reference to understand how to authenticate requests, send common query patterns, interpret response fields, and handle common HTTP errors.

Endpoint and Authentication

Search Endpoint

Method: GET
Path: /emselect
Base URL pattern (shared App deployments): https://{app_host}/{account_id}/{search_app_name}/emselect

Dedicated deployments can use a different host/path format. Copy your exact endpoint from Site Search > App Settings > All APIs > Search & Indexing.

The endpoint is shown in Site Search > App Settings > All APIs > Search & Indexing.

The Search APIs interface showing two main endpoints: /emselect for querying the index and /update for uploading and updating content.

Authentication

Use token authentication with the Authorization header:

Authorization: Token {token}

Use read-only credentials for search-only integrations.

Token Authentication

If your App uses tokens, you can create, enable or disable, and rotate tokens in the App UI.

Token management interface showing two active tokens with their creation dates, access rights, and token values, plus controls to create new tokens.

Note: Keep at least one enabled read-only token available for search traffic.

Requests

Use these parameters to control query text, result paging, filtering, spelling behavior, geospatial behavior, and profile selection.

Request Parameters

Name	Required	Type	Description
`q`	Recommended	string	Search query string for meaningful results.
`language`	No	string	Language code for multilingual App content. Both dash and underscore language-code variants are accepted and normalized automatically.
`start`	No	integer	Zero-based offset in the full result list, not a page number.
`rows`	No	integer	Number of results per request.
`sort`	No	string	Sort expression such as `score desc` or `url asc`. Fields and functions must match your App schema.
`fq`	No	string (repeatable)	Filter query to restrict which documents can be returned without changing scoring. Field names and values must match your App schema.
`model`	No	string	Search profile/model name. Defaults to the App default model when omitted.
`metadata`	No	boolean	Set to `false` to suppress metadata in the response.
`flAdditional`	No	string	Additional fields and functions to include in output, such as `score` or `geodist()`.
`facet`	No	boolean	Enables facet counts when faceting is configured in the App.
`facet.field`	No	string (repeatable)	Facet field names to include when `facet=true`.
`hl`	No	boolean	Enables highlight snippets when highlighting is configured in the App.
`hl.fl`	No	string (repeatable)	Fields to highlight when `hl=true`.
`spellcheck.correct`	No	boolean	Enables spelling autocorrection behavior.
`spellcheck.count`	No	integer	Number of spelling suggestions to return.
`spellcheck.maxResultsForSuggest`	No	integer	Suppresses suggestions when results exceed the threshold.
`pt`	No	string (`lat,lon`)	User location point for geospatial query behavior.
`sfield`	No	string	Geospatial field used with `pt` and distance or sort functions. Location-enabled Search Profiles can provide a default geospatial field; pass `sfield` when you need explicit control.
`distanceFilter`	No	number	Filters results to a radius around `pt`.
`distanceUnit`	No	string	Optional unit override, such as `mi` or `km`.

Note: Both dash and underscore language-code variants are accepted and normalized automatically, so use the language code your integration sends.

Request Examples

These examples are grouped by common implementation needs so you can find the request pattern that matches your use case.

Authentication Requests

Token Authentication

curl -H "Authorization: Token {read_only_token}" \
  --request GET \
  "https://{app_host}/{account_id}/{search_app_name}/emselect?q=*"

Core Queries

Basic Search

https://{app_host}/{account_id}/{search_app_name}/emselect?q=sitecore&language=en

Language-Specific Search

https://{app_host}/{account_id}/{search_app_name}/emselect?q=sitecore&language=es

If the same index includes documents for more than one language and your App indexes a language field such as language_s, add a language filter:

https://{app_host}/{account_id}/{search_app_name}/emselect?q=sitecore&language={language_code}&fq={language_field}:"{language_value}"

Behavior depends on your App configuration, Search Profile behavior, indexed language fields, and any profile-applied filters. A valid language code alone does not guarantee results in that language, and additional filters can change or eliminate matches.

Pagination

https://{app_host}/{account_id}/{search_app_name}/emselect?q=sitecore&start=4&rows=4

start is zero-based. This example returns the second page when page size is 4. Treat start as an offset into the full result list, not as a page number. For shared pagination guidance, see Pagination.

Sorting

Sort by relevance score descending:

https://{app_host}/{account_id}/{search_app_name}/emselect?q=sitecore&sort=score%20desc

Sort by URL ascending:

https://{app_host}/{account_id}/{search_app_name}/emselect?q=sitecore&sort=url%20asc

Filter Query (`fq`)

Use fq to narrow the set of documents the API can return without changing relevance scoring for the matching documents. q answers "what am I searching for?" while fq answers "which subset of documents should be eligible to match?"

Single filter:

https://{app_host}/{account_id}/{search_app_name}/emselect?q=sitecore&fq={filter_field}:"{filter_value}"

Multiple filters:

https://{app_host}/{account_id}/{search_app_name}/emselect?q=sitecore&fq={filter_field_1}:"{filter_value_1}"&fq={filter_field_2}:"{filter_value_2}"

Single fq with an OR expression:

https://{app_host}/{account_id}/{search_app_name}/emselect?q=sitecore&fq={filter_field}:("{filter_value_1}" OR "{filter_value_2}")

You can repeat fq to apply more than one filter. Invalid sort or fq fields can produce 400 responses. Field names and values must match your App schema.

Response Controls

Spelling Suggestions

Enable spelling correction:

https://{app_host}/{account_id}/{search_app_name}/emselect?q=sitecole&spellcheck.correct=true

Set the number of suggestions:

https://{app_host}/{account_id}/{search_app_name}/emselect?q=sitecole&spellcheck.count=4

Suppress suggestions when results exist:

https://{app_host}/{account_id}/{search_app_name}/emselect?q=sitecole&spellcheck.count=4&spellcheck.maxResultsForSuggest=1

Spellcheck behavior depends on your App configuration, Search Profile behavior, and the query. A request can accept spellcheck parameters without returning suggestions or autocorrection fields.

If the App returns responseHeader.params.autoCorrectedQ, use it as the clearest signal that the API autocorrected the query. Treat spellcheck.correctlySpelled as advisory metadata.

Example response when the App returns spellcheck suggestions:

{
  "facet_counts": {},
  "spellcheck": {
    "suggestions": [
      "sitecole",
      {
        "numFound": 1,
        "startOffset": 0,
        "endOffset": 8,
        "origFreq": 0,
        "suggestion": [
          {
            "word": "sitecore",
            "freq": 49
          }
        ]
      }
    ],
    "correctlySpelled": false
  }
}

Example response when the App autocorrects the query:

{
  "responseHeader": {
    "params": {
      "originalQ": "enviroment",
      "autoCorrectedQ": "environment"
    }
  }
}

Advanced Options

Exclude metadata in the response:

https://{app_host}/{account_id}/{search_app_name}/emselect?q=sitecore&metadata=false

Request additional fields and functions:

https://{app_host}/{account_id}/{search_app_name}/emselect?q=sitecore&flAdditional=score

Request facet counts:

https://{app_host}/{account_id}/{search_app_name}/emselect?q=sitecore&facet=true&facet.field=content_type_facet

Request highlighting snippets:

https://{app_host}/{account_id}/{search_app_name}/emselect?q=sitecore&hl=true&hl.fl=title&hl.fl=meta_description

Facet and highlighting behavior depends on App-side facet and highlighting configuration.

Geospatial Queries

Location Search

Pass user location with pt:

https://{app_host}/{account_id}/{search_app_name}/emselect?q=optometrist&pt=33.9169459567478,-118.391459160454

Return calculated distance using flAdditional=geodist():

https://{app_host}/{account_id}/{search_app_name}/emselect?q=optometrist&sfield={your_geo_field}&pt=33.916945956747824,-118.39145916045463&flAdditional=geodist()

Replace {your_geo_field} with a geospatial field from your App schema. If the sfield value is not a valid geospatial field, the request can return 400. If your Search Profile already configures geospatial search behavior, the platform can provide a default geospatial field; set sfield explicitly when you need to override that default.

Rename the distance output field:

https://{app_host}/{account_id}/{search_app_name}/emselect?q=optometrist&sfield={your_geo_field}&pt=33.916945956747824,-118.39145916045463&flAdditional=my_distance:geodist()

Convert kilometers to miles:

https://{app_host}/{account_id}/{search_app_name}/emselect?q=optometrist&sfield={your_geo_field}&pt=33.916945956747824,-118.39145916045463&flAdditional=my_distance:product(geodist(),0.621371)

Sort by distance:

https://{app_host}/{account_id}/{search_app_name}/emselect?q=optometrist&sfield={your_geo_field}&pt=33.916945956747824,-118.39145916045463&sort=geodist()%20asc

Filter by distance radius:

https://{app_host}/{account_id}/{search_app_name}/emselect?q=optometrist&pt=33.916945956747824,-118.39145916045463&distanceFilter=15

Boost relevance by distance:

https://{app_host}/{account_id}/{search_app_name}/emselect?q=optometrist&sfield={your_geo_field}&pt=33.916945956747824,-118.39145916045463&bf=recip(geodist(),1,1000,1000)

Profile Selection

Search Using a Specific Model

https://{app_host}/{account_id}/{search_app_name}/emselect?q=sitecore&model={search_profile_name}

If model is omitted, the App's default model is used.

Responses and Errors

Response fields and error behavior can vary based on your App configuration, enabled features, and request parameters.

Response Example

{
  "responseHeader": {
    "status": 0,
    "QTime": 13,
    "params": {
      "q": "sitecore",
      "language": "en",
      "rows": "12",
      "start": "0",
      "spellcheck.correct": "true"
    }
  },
  "spellcheck": {
    "suggestions": [],
    "collations": [],
    "correctlySpelled": true
  },
  "externalLinks": [
    {
      "name": "Resurgence of Search",
      "description": "White paper promotion triggered by the query.",
      "url": "https://www.searchstax.com/white-papers/resurgence-of-search-white-paper/"
    }
  ],
  "response": {
    "numFound": 680,
    "start": 0,
    "docs": [
      {
        "title": ["Hosted Solr Service for Sitecore | SearchStax"],
        "url": "https://www.searchstax.com/solutions/sitecore-solr/",
        "meta_description": [
          "SearchStax Cloud is the hosted Solr solution for Sitecore and offers an easy, reliable, performant and scalable Solr service."
        ],
        "content_type": ["Webpage"],
        "[elevated]": true
      },
      {
        "title": ["Site Search Tool for Sitecore | SearchStax"],
        "url": "https://www.searchstax.com/searchstudio/sitecore/",
        "meta_description": [
          "Get personalized site search for Sitecore. Understand user behavior with analytics and optimize Sitecore site search with easy-to-use tools."
        ],
        "content_type": ["Webpage"],
        "[elevated]": true
      },
      {
        "title": ["Sitecore Relies on SearchStax Cloud | SearchStax Blog"],
        "url": "https://www.searchstax.com/blog/sitecore-relies-on-searchstax-managed-solr/",
        "author_name": "Tom Humbarger",
        "content_type": ["Blog"],
        "[elevated]": true
      }
    ]
  },
  "facet_counts": {
    "facet_fields": {
      "content_type_facet": [
        "Documentation", 337,
        "Blog", 164,
        "Webpage", 116
      ],
      "metaplatforms_ss": [
        "Sitecore", 57,
        "Drupal", 19
      ]
    }
  },
  "highlighting": {
    "https://www.searchstax.com/solutions/sitecore-solr/": {
      "title": [
        "Hosted Solr Service for <em>Sitecore</em> | SearchStax"
      ],
      "meta_description": [
        "SearchStax Cloud is the hosted Solr solution for <em>Sitecore</em> and offers an easy, reliable, performant and scalable Solr service."
      ]
    }
  }
}

Key response fields:

responseHeader.params: echoed request parameters.
response.numFound: total matched documents.
response.start: zero-based offset for the returned page.
response.docs: returned documents based on App result configuration. Field sets vary by App result settings.
response.docs[n]."[elevated]" (optional): promotion marker from Search App promotions, not a standard schema result field.
facet_counts.facet_fields: facet values and counts configured in the App.
highlighting: highlighted snippets when highlighting is enabled.
spellcheck (optional): spelling suggestion or autocorrection data when the endpoint or Search Profile returns it.
externalLinks (optional): appears when external promotions are triggered.

Exact fields vary by App configuration, enabled features, Search Profile behavior, and result settings.

Search API uses the eDisMax parser and supports standard eDisMax query syntax. For shared request and response guidance, see Request and Response Conventions.

HTTP Status Codes and Error Handling

HTTP Code	When It Happens	Typical Response Body	What to Do
`200`	Request succeeds	Search payload with `responseHeader` and `response`	Process results
`400`	Invalid request parameters, such as unsupported `sort` or `fq` fields for the App schema	Error payload with `responseHeader.status=400`	Correct the request syntax or use fields that match your App schema.
`401`	Authentication or authorization is invalid	`{"message":"Unauthorized"}`	Verify your token, credentials, and access level.
`429`	Rate or plan limit is exceeded	`{"message":"Too Many Requests"}` or `{"message":"Plan Limit Exceeded"}`	Retry with delay and verify usage.
`413`	Payload exceeds the platform limit	`HTTP content length exceeded 10485760 bytes`	Reduce the payload size.
`414`	URL or request exceeds platform limits	`Request Entity Too Large`, `Requests-URI Too Large`, or `An HTTP line is larger than 10240 bytes.`	Reduce query and URL size.
`500`	Internal service failure, which can occur with monthly overage conditions	Internal service error	Check monthly usage and contact support.

A 429 response doesn't always mean the same thing. It can indicate either temporary throttling or a plan-limit condition, so check the response body's message value first.

Use the response body to choose your next step:

{"message":"Too Many Requests"} means you hit a short-term request-rate limit. Wait a short time and retry.
{"message":"Plan Limit Exceeded"} means you hit a plan limit. Check your monthly request and document usage.

Response details: both 429 cases use content-type: application/json and include these headers: access-control-allow-origin: *, access-control-allow-headers: *,Authorization, access-control-allow-methods: GET,OPTIONS, and access-control-expose-headers: *. 429 responses don't include a Retry-After header.

Rate Limits and Backoff

Limit Type	Current Limit	Behavior When Exceeded
Requests per second (per App)	`20+ requests/second`	`429` responses can occur
Monthly search requests (subscription)	Contract-specific	Query service can pause. `429` or `500` responses can occur.

Recommended backoff:

Occasional 429: wait briefly and retry.
Persistent 429 or 500: check monthly request and document usage, then escalate to support.

Shared API Foundations

Use these shared references for authentication, request and response structure, and pagination behavior used across Site Search APIs:

Articles in this section

Search API

Endpoint and Authentication

Search Endpoint

Authentication

Token Authentication

Requests

Request Parameters

Request Examples

Authentication Requests

Token Authentication

Core Queries

Basic Search

Language-Specific Search

Pagination

Sorting

Filter Query (`fq`)

Response Controls

Spelling Suggestions

Advanced Options

Geospatial Queries

Location Search

Profile Selection

Search Using a Specific Model

Responses and Errors

Response Example

HTTP Status Codes and Error Handling

Rate Limits and Backoff

Shared API Foundations

Products

Pricing

Services

Resources

Endpoint and Authentication

Search Endpoint

Authentication

Token Authentication

Requests

Request Parameters

Request Examples

Authentication Requests

Token Authentication

Core Queries

Basic Search

Language-Specific Search

Pagination

Sorting

Filter Query (fq)

Response Controls

Spelling Suggestions

Advanced Options

Geospatial Queries

Location Search

Profile Selection

Search Using a Specific Model

Responses and Errors

Response Example

HTTP Status Codes and Error Handling

Rate Limits and Backoff

Shared API Foundations

Filter Query (`fq`)