Zum Inhalt springen

Indexing

Document schema

https://searcio.com/api/v1

Die Dokumentation ist auf Englisch verfasst.

Auf dieser Seite

A document is one searchable record: a product, a post, a page or anything else. Documents are largely free-form. A few fields are recognised and handled specially, and everything else you send is stored and returned as it is.

Required fields

Every document must include:

Field Type Notes
id string (≤ 255) Your stable identifier. Sending it again replaces the document. For PUT, the id is in the URL, not the body.
type string (≤ 255) Content type (product, post, page, …). Used for filtering and boosts.
title string The primary display field. Powers autocomplete.

Recognised optional fields

These fields are indexed in a dedicated way, which gives better relevance and behaviour:

Field Type Behaviour
content text Full-text body, matched without regard to accents or case.
url keyword The canonical link to show in results. Exact match only.
image keyword Image URL. Stored but not indexed, for display only.
published_at date When the content was first published, in ISO 8601 (2026-11-01T08:00:00Z). Orders a search sent with sort=newest.
indexed_at date Set automatically by Searcio when the document is indexed. Do not send it.

Custom fields

Any other JSON fields you include are indexed dynamically and returned in source, for example price, sku, brand, category, in_stock or rating. in_stock also affects ranking: a product sent with in_stock: false is moved down in the results rather than hidden.

json
{
  "id": "p-42",
  "type": "product",
  "title": "Wireless Headphones",
  "content": "Over-ear, 30h battery, noise cancelling",
  "url": "/products/wireless-headphones",
  "image": "https://cdn.example.com/wh.jpg",
  "price": 129.00,
  "sku": "WH-42",
  "brand": "Acme",
  "in_stock": true
}

Tip: keep custom field names consistent across documents and sites if you want to search or filter on them. To make a custom field searchable, add it with a weight under the site's Search settings in the Searcio dashboard, or send the whole configuration from your plugin through the search configuration endpoint.

Variants

A product whose variants differ in colour, size or another attribute can send them as variants, a list with one object per variant:

json
{
  "id": "p-1",
  "type": "product",
  "title": "Down jacket Summit",
  "attr_color": ["Red", "Blue"],
  "attr_size": ["M", "XL"],
  "variants": [
    { "attr_color": "Red", "attr_size": "M", "in_stock": true },
    { "attr_color": "Blue", "attr_size": "XL", "in_stock": true },
    { "attr_color": "Red", "attr_size": "XL", "in_stock": false }
  ]
}

Keep the product's own fields as well: they power the facet counts and the filters of a site that does not use variants. List the attributes in variant_fields, and a search filtered by red and XL then skips this jacket, since its red XL is sold out. A variant without in_stock, or with in_stock: true, counts as available.

Purchase price and margin

Send one of these with a product to use profit ranking (set up under Search settings > Ranking in the Searcio dashboard, or through profit_ranking):

Field Type Meaning
cost_price number What the product costs you, in the same currency as price.
margin_percent number The margin in percent of price (35 for 35%), for a shop that would rather not send purchase prices. Ignored when cost_price is sent.
price_excluding_tax number The selling price without tax, for a shop whose price includes it. Optional. With it, the profit per sale is counted without tax.

Send price and cost_price on one basis, both with tax or both without: the margin is then the same either way. The profit per sale that a minimum profit is compared with is the margin times the price without tax when you send price_excluding_tax (the price at which the document is indexed, a sale price included), so tax is never counted as profit. Without it, it is price minus cost_price in the prices you send, and tax counts as profit when your prices include it. A value that is not a number, or above price, is ignored.

Both need price. Searcio works out the margin at the price the document is indexed with, so a sale price lowers it until the next sync after the sale.

None of these fields is stored as sent, and the margin Searcio works out from them never leaves Searcio: it is not returned in source, in suggestions, by the shopping assistant, through MCP or in exports, and it cannot be made a searchable, facet or suggest field. The field names profit_amount_cents and profit_ratio_bp are reserved for it; a document that sends them has them replaced.

How fields are indexed

flowchart LR
    subgraph Doc["Your document"]
        T[title] --- C[content] --- U[url] --- I[image] --- X["price, sku, ... (dynamic)"]
    end
    T --> TM["text (folding)<br/>+ .keyword<br/>+ .autocomplete (edge-ngram)"]
    C --> CM["text (folding)"]
    U --> UM["keyword"]
    I --> IM["keyword, not indexed"]
    X --> XM["dynamic mapping"]
  • title is indexed three ways: as typo-tolerant full text, as an exact keyword, and as an autocomplete field for suggestions while the shopper types.
  • content is matched without regard to accents or case, for forgiving full-text search.
  • type is a keyword, which makes it ideal for filters and facets.
  • A field ending in _paths, such as category_paths, holds a tree: each category as its path from the top, levels joined by >, plus every level above it. See Category trees.
  • indexed_at is added for you: the time of the last sync, not of the content. Send published_at to order results by date.
  • A field of your own takes its type from the first value it receives. A number sent as text ("5", as WordPress stores every custom field) makes it a text field, where a range compares text. List such a field in numeric_fields to map it as a number.

Identity and replacement

  • The pair (site, id) uniquely identifies a document.
  • Replacement: sending an existing id (in a POST batch or with PUT) replaces the whole document. Send the complete object, not a partial update.
  • Deletion: remove a document by id with DELETE, or leave it out of the next full sync and then remove the documents that sync did not include (see Building a plugin).

Sizes and limits

Constraint Value
Documents per POST batch 1 to 1000
id length ≤ 255 characters
type length ≤ 255 characters
Total documents Your plan's max_documents

A batch with more than 1000 documents is rejected with 422. Split large catalogues into several batches; see Documents.