REST API

Basics

The API lives at https://api.zaproo-search.com. Every request body and response is JSON, every route except the health checks sits under /v1, and every request authenticates with one header:

-H "Authorization: Bearer zs_sk_..."

The bearer is a secret key (zs_sk_…) for a server, a public key (zs_pk_…) for the two storefront routes, or the cabinet's session token for a signed-in user.

Who may call a route is printed under each one:

An id that belongs to another organization or project answers 404, never 403, so ids cannot be probed. A key with an index scope gets 404 for every other index.

Errors share one shape:

{"error": {"code": "PROFILE_INVALID", "message": "...", "details": [{"path": "queryFields.title", "message": "..."}]}}

Storefront

The two routes a storefront calls. They take a public handle in the path instead of a project id.

These two routes answer the CORS preflight for every origin, without cookies, so a shop's pages can call them from the browser with a public key. The key's allowed origins are checked on the real request. A server sends no Origin header, so call them from a server with a secret key.

Indices

See Indices and languages, Mapping and fields and Reindex. A mapping change, reindex or replace session that would break a profile, rule, facet, autocomplete field or data source answers 409 MAPPING_BREAKS_CONFIG; details lists each use to change first.

A shop platform plugin, such as the Magento 2 module, reports itself with PUT .../integration (body platform, name, optional url and version, settings.manageMapping) each time its settings change, and GET .../:indexId returns it as integration. Only a full-access secret key may connect one; a signed-in user gets 403 INTEGRATION_KEY_ONLY. While settings.manageMapping is on, PUT .../mapping from anyone but the plugin's own key answers 409 MAPPING_MANAGED_BY_INTEGRATION. While any integration is connected, PUT .../feed and POST .../feed/sync answer 409 INDEX_HAS_INTEGRATION. DELETE .../integration disconnects it, answers 204 and is safe to repeat. See Integrations.

Documents and full sync

POST .../documents takes a bare JSON array of up to 1000 documents; POST .../documents/delete a bare array of ids. Both accept an Idempotency-Key header. POST .../documents/flush takes no body, deletes every document and answers 202 with taskId and previousDocCount; see Delete all documents. Replace sessions upload a whole catalog and swap it in at commit. See Documents and tasks and Full catalog sync.

Tasks

Search and profiles

POST .../indices/:indexId/search is the secret search by index id: a saved profile by profileKey, or an inline profile to try settings before saving them. See Search API and Search profiles.

Synonyms

See Synonyms.

Ranking rules

See Ranking rules.

Autocomplete

See Autocomplete.

Analytics

See Search analytics.

API keys

Keys are managed from a cabinet session only; no key can create or revoke another key. Creating a key needs a confirmed email. See API keys.

Account and sign-in

The cabinet's own routes. refresh and logout read the refresh cookie the cabinet holds. impersonate and impersonation/exit serve Zaproo support: they trade a one-time code from an administrator for a session as the account owner, and end it. See Account and sign-in.

Organizations, members and projects

See Organizations, members and roles and Projects.

MCP

The MCP server, for AI agents. See MCP setup.

Status

See Status for what it answers. GET /health and GET /ready are probes for the infrastructure that runs the API.

Not allowed while impersonating

When Zaproo support acts as an account owner, these routes answer 403 IMPERSONATION_FORBIDDEN: creating an API key, changing the password, ending a session, changing the plan, and adding, changing or removing a member.