Zum Inhalt springen

Indexing

Documents

https://searcio.com/api/v1

Die Dokumentation ist auf Englisch verfasst.

Auf dieser Seite

Add, replace and remove content. Every indexing endpoint requires the write credentials (X-Write-Key and X-Write-Secret) and answers asynchronously with 202 Accepted: the work is queued and carried out in the background.

Base: https://searcio.com/api/v1/sites/{site}, or key-relative https://searcio.com/api/v1 (the site is resolved from the write key).

sequenceDiagram
    participant P as Your server
    participant API as Searcio API
    participant I as Search index
    P->>API: POST /documents (batch)
    API->>API: Check credentials and document limit
    API-->>P: 202 { sync_run_id, accepted, status: "queued" }
    API->>I: Index the batch in the background
    I-->>API: Document count and last sync updated

POST /documents

Add or replace a batch of 1 to 1000 documents. Use it for full syncs and large catalogue imports. Each call creates a sync run you can follow in the Searcio dashboard.

Request

http
POST /api/v1/sites/123/documents
X-Write-Key: wk_live_abc
X-Write-Secret: ••••••
Content-Type: application/json
json
{
  "documents": [
    { "id": "p-1", "type": "product", "title": "Red Shoes", "price": 89.9 },
    { "id": "p-2", "type": "product", "title": "Blue Shoes", "price": 99.0 }
  ]
}

Validation

Field Rule
documents Required array of 1 to 1000 items
documents.*.id Required string, ≤ 255 characters
documents.*.type Required string, ≤ 255 characters
documents.*.title Required string
documents.*.lang Optional language code (see below)
sync_type Optional: full (the default) or incremental
run_reference Optional name for the run these batches belong to (see below): up to 64 characters of letters, digits, ., _, : and -

Any other fields on a document are accepted and stored. See Document schema.

Each request is a row of the sync history. A sync of a large catalogue sent in several requests can be one row: give every request of it the same run_reference, a name your integration makes when the run starts (a run number or a UUID, no round trip needed). Requests with the same reference for the same site within 24 hours join one run: the response returns the same sync_run_id, the run's total is the number of documents of all of them, and it is complete when every one is accounted for. A batch that arrives after the run looked complete opens it again. The run keeps the sync_type of its first request. A request without a run_reference is a run of its own.

sync_type only names the run in the sync history. Send incremental for a batch that carries the documents that changed since the last sync, so the history does not call every small update a full sync. Either way, the batch adds or replaces the documents it holds and leaves every other document as it is.

Languages

A document may carry an optional lang, such as de. When the site has enabled languages (under Search settings in the Searcio dashboard, or through the search configuration endpoint), a document whose lang is not on that list is rejected with 422 before it counts against any quota:

json
{
  "message": "The language \"fr\" is not enabled for this site.",
  "errors": { "documents.1.lang": ["..."] }
}

Documents without a lang are always accepted, and a site with no enabled languages accepts every language, so single-language integrations need no changes. The plan's language limit and the enabled languages are reported by /health as plan.languages. On the search side, narrow results with filter[lang]=de (always allowed; see Search). Language codes are compared exactly, so use the same form everywhere; see Languages & currencies.

Response: 202 Accepted

json
{ "sync_run_id": 987, "accepted": 2, "status": "queued" }

Errors

Status When
401 Missing or invalid write credentials
402 The account has no active plan (reason: no_active_plan) or an overdue payment (reason: payment_overdue). Pause syncing until /health reports account.served.
403 The site is disabled, or the account is suspended (reason: account_suspended)
422 Validation failed (for example a missing type, or more than 1000 items)
429 The batch would exceed the plan's max_documents ({ "metric": "documents", "limit": N }). Nothing in the batch is indexed.

PUT /documents/{id}

Add or replace a single document. The id comes from the URL, and the body holds the document's fields (no id needed).

Request

http
PUT /api/v1/sites/123/documents/p-42
X-Write-Key: wk_live_abc
X-Write-Secret: ••••••
Content-Type: application/json
json
{ "type": "product", "title": "Wireless Headphones", "price": 129.0, "in_stock": true }

Response: 202 Accepted

json
{ "status": "queued", "id": "p-42" }

Call it from your platform's create and update hooks, for example when a product is saved.


DELETE /documents/{id}

Remove a single document by id.

Request

http
DELETE /api/v1/sites/123/documents/p-42
X-Write-Key: wk_live_abc
X-Write-Secret: ••••••

Response: 202 Accepted

json
{ "status": "queued", "id": "p-42" }

Call it from your platform's delete and unpublish hooks.


Tracking progress

POST returns a sync_run_id. A sync run moves through pending → running → completed (or failed) and appears under the site's Sync history in the Searcio dashboard. After a successful batch, the site's document count, last synced time and status (connected) are updated. If an indexing job fails, the account owner is notified by email.

There is no public endpoint for polling an individual sync run. Use the health endpoint to read the live document count, or the sync history in the Searcio dashboard for details of each run.

Throughput guidance

  • Send batches of a few hundred documents rather than many tiny requests.
  • For a full sync of a large catalogue, page through your data and send the POST batches one after another, within the limit of 1000 documents per batch and your plan's max_documents.
  • Indexing shares a rate limit with every other endpoint; see Errors & rate limits.