Start here: build a search box

This tutorial builds one thing, step by step: the search box for a movie-night website. By the end, a visitor can type into a box and instantly find films and actors — filtered by genre and year, with posters, smarter suggestions over time, and cinemas near them.

Here's what you're building — the finished box, live on the last page:

You'll add one feature per page, and each page builds on the last. Everything here is real: you do it in the Search Stack console, and every list you create gets a live search API the moment you make it. Each step takes a few minutes.

What a list is

A list is where your searchable data lives — a collection of results that all share the same set of fields. Think of it as a single table: a list of movies has a field for the title, another for the plot, another for the genre; a list of cinemas has a name and a location. Every list you create automatically gets its own live search API, so the moment it exists you can search it from a website, an app, or a script.

We'll build a list called movies. Sign in to the console and choose Create List.

The only thing you have to decide is the name. Type movies and leave the rest on their defaults — the free plan, no embedding model, and the platform's built-in storage are all fine to start. (You can add a semantic model or move to your own search server later, on the Go live page.)

That's it — you have a list. It's empty, so let's put a few films in it.

Add a few movies

A single entry in a list is called a search result — for the movies list, each one is a film. Open the movies list and choose Add Search Result. The only thing a result needs to start with is a name, so type a film title and save it. Add a handful of your favourites.

After adding a few, the list shows them all. Here we've added five:

You already have a working search API

The moment the list existed, Search Stack gave it a live, read-only search API. Any client — a browser, a mobile app, a server — can call it. There's nothing to deploy. The base address for every call is https://api.searchstack.dev/, and each request carries your API key in an X‑API‑Key header. (Create a key on the Developers tab; a read-only key is safe to use in a browser.)

The three things a list can do:

• suggest – fast as-you-type completions, made for an autocomplete box.
• search – full search over your fields, returning complete results, paged, with filters applied.
• facet – counts grouped by a field's values, for building filter menus (you'll use this once your list has facet fields).

Try a suggestion as your visitor types the letters inc. The version number in the path is 1 for a brand-new list:

GET https://api.searchstack.dev/suggest/Demo/movies/1/inc
X-API-Key: {your key}

comes back with the matching titles:

[
  { "name": "Inception" }
]

The same list, searched with the search operation, returns the full results with a total count:

GET https://api.searchstack.dev/search/Demo/movies/1?query=dark
X-API-Key: {your key}

{
  "results": [
    { "name": "The Dark Knight" }
  ],
  "count": 1,
  "total_count": 1
}

Right now a search only matches the film's name, because that's the only field the list has. On the next page we'll add a plot field — so a visitor can find a film by what it's about, not just its title.