Indexing
Documents
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 updatedPOST /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
POST /api/v1/sites/123/documents
X-Write-Key: wk_live_abc
X-Write-Secret: ••••••
Content-Type: application/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:
{
"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
{ "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
PUT /api/v1/sites/123/documents/p-42
X-Write-Key: wk_live_abc
X-Write-Secret: ••••••
Content-Type: application/json{ "type": "product", "title": "Wireless Headphones", "price": 129.0, "in_stock": true }Response: 202 Accepted
{ "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
DELETE /api/v1/sites/123/documents/p-42
X-Write-Key: wk_live_abc
X-Write-Secret: ••••••Response: 202 Accepted
{ "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
POSTbatches one after another, within the limit of 1000 documents per batch and your plan'smax_documents. - Indexing shares a rate limit with every other endpoint; see Errors & rate limits.