Zum Inhalt springen

Indexing

Health

https://searcio.com/api/v1

Die Dokumentation ist auf Englisch verfasst.

Auf dieser Seite

One endpoint that plugins use to verify a connection and read a site's live status and quota. It is authenticated with the write credentials, because it exposes usage data.

Base: https://searcio.com/api/v1/sites/{site}, or key-relative https://searcio.com/api/v1. In the key-relative form the site is resolved from the write key, and site.id in the response gives you its id without asking the user.


GET /health

Request

http
GET /api/v1/sites/123/health
X-Write-Key: wk_live_abc
X-Write-Secret: ••••••

Response: 200 OK

json
{
  "site": {
    "id": 123,
    "name": "Acme Store",
    "status": "connected",
    "platform": "woocommerce",
    "last_synced_at": "2026-06-23T09:12:44+00:00",
    "statistics_url": "https://searcio.com/acme/sites/123"
  },
  "account": {
    "served": true,
    "reason": null,
    "support_url": "https://searcio.com/acme/support"
  },
  "usage": {
    "searches":    { "used": 8123,  "limit": 100000, "percent": 8, "exceeded": false, "near_limit": false },
    "ai_messages": { "used": 180,   "limit": 500,   "percent": 36, "exceeded": false, "near_limit": false },
    "documents":   { "used": 12450, "limit": 50000, "percent": 24, "exceeded": false, "near_limit": false, "indexed": 4120 },
    "sites":       { "used": 2,     "limit": 5,     "percent": 40, "exceeded": false, "near_limit": false },
    "members":     { "used": 3,     "limit": 5,     "percent": 60, "exceeded": false, "near_limit": false }
  },
  "plan": {
    "id": 4,
    "slug": "starter",
    "name": "Starter",
    "is_free": false,
    "upgrade_url": "https://searcio.com/acme/billing",
    "languages": { "limit": 3, "allowed": ["de", "en"] }
  },
  "engine": { "reachable": true },
  "version": "v1"
}

Fields

Field Meaning
site.status pending, connected or disabled.
site.last_synced_at When the last successful indexing run finished (ISO 8601), or null.
site.statistics_url Absolute link to this site's search statistics in the dashboard, so a plugin can link straight to them.
account.served Whether searching and indexing are served. false when the account has no active plan or is suspended.
account.reason Why not: no_active_plan, payment_overdue or account_suspended, or null when the account is served. It is the same reason a refused call returns. See Errors.
account.support_url Absolute link to the account's support page in the dashboard, in every account state, so a plugin can offer "Contact support" for a suspended account.
usage.* For each metric: used, limit (null means unlimited), percent, exceeded and near_limit (80% or more). Without an active plan every limit is 0, except ai_messages, which keeps the platform cap.
usage.documents.indexed How many documents this site's search index holds right now, counted live. used is the account's counter across all its sites and is only as fresh as the last sync, so after a rebuild went wrong the two can differ. 0 means the index is empty or missing: run a full sync. null when the engine is unreachable.
plan.id / slug / name The account's current plan, or null if it has none. name is localized.
plan.is_free true when the account is on a free plan, a good moment to suggest an upgrade in your plugin.
plan.upgrade_url Absolute link to the customer's billing page, so a plugin can link to "Upgrade your plan".
plan.languages The plan's languages: limit (null means unlimited) and the site's enabled languages (allowed; empty means unrestricted). See Documents.
engine.reachable Whether the search engine is reachable.
version API version.

Errors

Status When
401 Missing or invalid write credentials, or an unknown site id (the two are deliberately indistinguishable)
403 Site disabled

Health keeps answering 200 for an account that is not served, so a plugin can show the state from account instead of an error.


How plugins use it

flowchart TD
    A["User clicks 'Test connection'"] --> B["GET /health with entered keys"]
    B -- 200 --> C["Show ✓ Connected<br/>+ 'X / Y documents indexed'"]
    B -- "200, account.served false" --> F["Show ✗ No active plan / suspended<br/>+ link to plan.upgrade_url"]
    B -- 401 --> D["Show ✗ Invalid credentials"]
    B -- 403 --> E["Show ✗ Site disabled"]

Recommended uses:

  1. Validate on save. When a user pastes credentials into your plugin's settings, call /health before saving them and show a clear ✓ or ✗.
  2. Status widget. Display "Connected · 12,450 / 50,000 documents · last synced 5 min ago" from usage.documents and last_synced_at.
  3. Check before a large sync. Read usage.documents and warn the user if the catalogue would exceed the limit, rather than meeting a 429 halfway through.
  4. Search engine availability. If engine.reachable is false, show a degraded state and rely on the platform's own search until it recovers.
  5. Upgrade prompt. When plan.is_free is true, show an "Upgrade for more capacity" link to plan.upgrade_url.