Zum Inhalt springen

Getting started

Introduction

https://searcio.com/api/v1

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/v1

Every endpoint is available in two forms:

/api/v1/sites/{site}/...   # with the numeric site id
/api/v1/...                # without it: the key identifies the site

Write 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:

bash
BASE=https://searcio.com/api/v1
WK=wk_...   # write key
WS=...      # write secret
SK=sk_...   # search key

1. Verify the connection.

bash
curl "$BASE/health" \
  -H "X-Write-Key: $WK" -H "X-Write-Secret: $WS"

2. Index a product.

bash
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.

bash
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/json and expect it back, except for photo search, which takes a file upload.
  • Asynchronous writes. Indexing endpoints answer 202 Accepted once the work is queued.
  • Your ids. The id you 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