Getting started
Introduction
Die Dokumentation ist auf Englisch verfasst.
Auf dieser Seite
Searcio is a hosted search service for online shops and websites. The Searcio API keeps a site's content in a Searcio index and serves everything a shopper uses to find it: keyword and AI search, autocomplete, filters, product recommendations, search by photo and a conversational shopping assistant.
This reference is for developers who connect a shop, a website or an application to Searcio: authors of plugins and platform modules, agencies, and teams that build their own storefront.
How the API is organised
The API has two halves, each with its own credential:
| Indexing | Search | |
|---|---|---|
| What it does | Adds, updates and removes documents; reads and changes the site's search configuration; manages quizzes | Search, autocomplete, filters, recommendations, photo search, the AI assistant, result cards and quizzes for the storefront |
| Credential | Write key and write secret | Search key |
| Called from | Your server only | The shopper's browser, or your server |
Two further endpoints sit beside them: health, which confirms a connection and reports the plan's usage, and connect, which creates a site and its credentials from inside a plugin without the merchant having to sign up first.
Base URL
All endpoints live under one base URL:
https://searcio.com/api/v1Every endpoint is available in two forms:
/api/v1/sites/{site}/... # with the numeric site id
/api/v1/... # without it: the key identifies the siteWrite keys and search keys are issued per site, so the key alone identifies the site. The shorter form saves a plugin from asking the merchant for a site id; health returns the id if you want to display it.
Quickstart
Three requests take you from a connected site to a working search. Replace the variables with your own values:
BASE=https://searcio.com/api/v1
WK=wk_... # write key
WS=... # write secret
SK=sk_... # search key1. Verify the connection.
curl "$BASE/health" \
-H "X-Write-Key: $WK" -H "X-Write-Secret: $WS"2. Index a product.
curl -X PUT "$BASE/documents/p-42" \
-H "X-Write-Key: $WK" -H "X-Write-Secret: $WS" \
-H "Content-Type: application/json" \
-d '{ "type": "product", "title": "Wireless Headphones", "price": 129.0 }'Indexing is asynchronous: the request answers 202 Accepted, and the product is
searchable a moment later.
3. Search for it.
curl "$BASE/search?q=headphones&key=$SK"Endpoints at a glance
Every path below is shown with the site id; each one except /connect also
works without the /sites/{site} prefix.
| Method | Path | Credential | Purpose |
|---|---|---|---|
GET |
/connect |
None | The links a plugin shows on its consent screen. See Building a plugin. |
POST |
/connect |
None | Create a site and its credentials from a plugin. See Building a plugin. |
GET |
/sites/{site}/health |
Write key | Verify the connection; read the plan, usage and status. |
POST |
/sites/{site}/documents |
Write key | Index or replace documents in bulk. |
PUT |
/sites/{site}/documents/{id} |
Write key | Index or replace one document. |
DELETE |
/sites/{site}/documents/{id} |
Write key | Remove one document. |
GET |
/sites/{site}/search-config |
Write key | Read the search configuration. |
PUT |
/sites/{site}/search-config |
Write key | Change the search configuration. |
POST |
/sites/{site}/upgrade-link |
Write key | Email the account owner a link that opens their billing page. |
DELETE |
/sites/{site}/disconnect |
Write key | Delete the site and its index permanently. |
GET |
/sites/{site}/quiz-templates |
Write key | List the site's quizzes, drafts included. See Quizzes. |
POST |
/sites/{site}/quiz-templates |
Write key | Create a quiz. |
GET |
/sites/{site}/quiz-templates/{id} |
Write key | Read a quiz with its questions. |
PUT |
/sites/{site}/quiz-templates/{id} |
Write key | Change, publish or unpublish a quiz. |
DELETE |
/sites/{site}/quiz-templates/{id} |
Write key | Delete a quiz. |
GET |
/sites/{site}/quiz-templates/facet-values |
Write key | The values each filter field holds, for building quiz answers. |
POST |
/sites/{site}/quiz-templates/endings |
Write key | Where each path through a quiz ends, and how many products it finds. |
GET |
/sites/{site}/storefront-config |
Search key | What the storefront may offer, such as the AI assistant. |
GET |
/sites/{site}/search |
Search key | Search, with filters, ranges and facets. |
GET |
/sites/{site}/search/suggest |
Search key | Autocomplete suggestions. |
POST |
/sites/{site}/search/visual |
Search key | Search with a photo. See Visual search. |
GET |
/sites/{site}/search/similar |
Search key | Products similar to a given one. |
GET |
/sites/{site}/search/popular |
Search key | The most popular recent searches. |
POST |
/sites/{site}/search/click |
Search key | Report a click on a result. |
POST |
/sites/{site}/assistant |
Search key | Ask the AI shopping assistant. |
POST |
/sites/{site}/assistant/stream |
Search key | Ask the AI shopping assistant and receive the answer as it is written. |
GET |
/sites/{site}/card-templates |
Search key | The published result card designs. See Result cards. |
GET |
/sites/{site}/quizzes |
Search key | The published quizzes. See Quizzes. |
"Write key" means the write key and the write secret together; see Authentication & security.
Conventions
- HTTPS and JSON. Every request uses HTTPS. Send
application/jsonand expect it back, except for photo search, which takes a file upload. - Asynchronous writes. Indexing endpoints answer
202 Acceptedonce the work is queued. - Your ids. The
idyou give a document is its key. Sending the same id again replaces the document. - Errors. Errors use standard HTTP status codes and a JSON body; validation errors name the field. See Errors & rate limits.
- Compatibility. Within v1, fields and endpoints are added but never removed or changed. Ignore fields you do not recognise. See Versioning.
Next steps
- Core concepts: sites, documents, search settings and limits.
- Authentication & security: which key goes where, and how to keep the write secret safe.
- Documents and Document schema: keeping the index in step with your catalogue.
- Search: every search endpoint in detail.
- Building a plugin: a complete integration, from connecting a site to keeping it in sync.
- MCP server: the same data for AI assistants such as Claude.