Search (Management API)

GET

https://mapi.storyblok.com/v1/spaces/:space_id/strata/search

Returns a ranked list of stories whose content matches the search term by meaning. Instead of matching exact keywords, Strata compares the meaning of the search term with the meaning of the indexed content.

For public, high-volume search, use the Content Delivery API search endpoint. This Management API endpoint is best for private queries scoped to the user’s permissions, and it’s rate-limited.

Note

Any user who can read the space’s stories can search its draft or published content. Results only include stories the user can read. A scoped personal access token or an OAuth access token also needs the strata:read scope.

Path parameters

• :space_id required number

  Numeric ID of a space.

Query parameters

• q string

  The search term.

• version string

  The content version to search: draft or published. Default is published.

• limit number

  Maximum number of results to return, between 1 and 1000. Default is 25. When starts_with or content_type is set, the maximum is 50.

• starts_with string

  Filter by the story’s full_slug to return stories starting with the given value, for example docs/. Matches only the default-language slug, so language prefixes (for example, de/) and translated slugs return no results.

• content_type string

  Retrieve stories of a specific content type block. For example, content_type=page.

Response properties

• results object[]

  A ranked array of matches, best match first. A story can appear more than once if it has multiple matching passages.

  Show child properties

  • excerpt string

    The passage of story content that matches the search term.

  • score number

    How closely the result matches the search term. A higher value means a closer match.

  • story object

    The story that contains the matching passage.

    Show child properties

    • id number

      Numeric ID of the story.

    • slug string

      Full slug of the story.

    • name string

      Name of the story.

Example Response

{
  "results": [
      {
          "excerpt": "You can return any item within 30 days of delivery for a full refund",
          "score": 0.89,
          "story": {
              "id": 1001,
              "slug": "help/returns",
              "name": "How to return an order"
          }
      },
      {
          "excerpt": "Refunds reach your original payment method within 5 business days",
          "score": 0.81,
          "story": {
              "id": 1044,
              "slug": "help/faq",
              "name": "FAQ"
          }
      }
  ]
}

Examples

cURL

curl "https://mapi.storyblok.com/v1/spaces/288868932106293/strata/search\
?q=how+do+I+return+an+order\
&version=published\
&limit=5" \
  -H "Authorization: YOUR_PERSONAL_ACCESS_TOKEN"

JS

// storyblok-js-client@>=7, node@>=18
import Storyblok from "storyblok-js-client";

const storyblok = new Storyblok({
  oauthToken: "YOUR_PERSONAL_ACCESS_TOKEN",
});

try {
  const response = await storyblok.get('spaces/288868932106293/strata/search', {
    "q": "how do I return an order",
    "version": "published",
    "limit": "5"
  })
  console.log({ response })
} catch (error) {
  console.log(error)
}

PHP

$client = new \Storyblok\ManagementClient('YOUR_PERSONAL_ACCESS_TOKEN');

$client->get('spaces/288868932106293/strata/search', [
  "q" => "how do I return an order",
  "version" => "published",
  "limit" => "5"
])->getBody();

Java

HttpResponse<String> response = Unirest.get("https://mapi.storyblok.com/v1/spaces/288868932106293/strata/search?q=how+do+I+return+an+order&version=published&limit=5")
  .header("Authorization", "YOUR_PERSONAL_ACCESS_TOKEN")
  .asString();

C#

var client = new RestClient("https://mapi.storyblok.com/v1/spaces/288868932106293/strata/search?q=how+do+I+return+an+order&version=published&limit=5");
var request = new RestRequest(Method.GET);

request.AddHeader("Authorization", "YOUR_PERSONAL_ACCESS_TOKEN");
IRestResponse response = client.Execute(request);

Python

import requests

url = "https://mapi.storyblok.com/v1/spaces/288868932106293/strata/search"

querystring = {"q":"how do I return an order","version":"published","limit":"5"}

payload = ""
headers = {
  'Authorization': "YOUR_PERSONAL_ACCESS_TOKEN"
}

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

Ruby

require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_PERSONAL_ACCESS_TOKEN')

client.get('spaces/288868932106293/strata/search', {:params => {
  "q" => "how do I return an order",
  "version" => "published",
  "limit" => "5"
}})

Swift

let storyblok = URLSession(storyblok: .mapi(accessToken: .personal("YOUR_PERSONAL_ACCESS_TOKEN")))
var request = URLRequest(storyblok: storyblok, path: "spaces/288868932106293/strata/search")
request.url!.append(queryItems: [
    URLQueryItem(name: "q", value: "how do I return an order"),
    URLQueryItem(name: "version", value: "published"),
    URLQueryItem(name: "limit", value: "5")
])
let (data, _) = try await storyblok.data(for: request)
print(try JSONSerialization.jsonObject(with: data))

Kotlin

val client = HttpClient {
    install(Storyblok(MAPI)) {
        accessToken = Personal("YOUR_PERSONAL_ACCESS_TOKEN")
    }
}

val response = client.get("spaces/288868932106293/strata/search") {
    url {
        parameters.append("q", "how do I return an order")
        parameters.append("version", "published")
        parameters.append("limit", "5")
    }
}

println(response.body<JsonElement>())