post
https://{yourinstance}.makaira.io/documents/public
Get documents directly from Elasticsearch, by id and/or document type.
Fetches one or more documents directly from the search index by datatype and/or IDs. Supports field filtering, aggregations, and sorting. This is the public endpoint — it does not require API authentication.
Request
POST /documents/public
Headers
| Header | Value |
|---|---|
Content-Type | application/json |
X-Makaira-Instance | Your Makaira instance identifier |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
datatype | string | Yes | Document type to retrieve. Note: makaira-product fetches variants and returns them with datatype: makaira-product; makaira-productgroup fetches products and returns them with datatype: makaira-productgroup. |
constraints | object | Yes | Must include query.language (language code). Optionally includes query.attribute_ids to filter by attribute IDs. |
ids | array | No | Array of document IDs to fetch. If omitted or empty, returns all documents of the given datatype (use with caution — can produce large responses). |
fields | array | No | Array of field names to include in the response. Defaults to all public fields from the whitelist. |
includeContent | boolean | No | When true, includes full document content. |
aggregations | object | No | Active filter selections. |
sorting | object | No | Sorting configuration. |
Example Request — Fetch specific documents
{
"datatype": "makaira-productgroup",
"ids": ["product-123", "product-456"],
"constraints": {
"query.language": "de"
}
}Example Request — Fetch with field filter
{
"datatype": "makaira-productgroup",
"constraints": {
"query.language": "de"
},
"fields": ["title", "price", "ean"],
"ids": ["product-789"]
}Response
Returns a JSON array of document objects. Documents not found are omitted.
Response Body
Each document object contains the requested fields under fields and meta information at the root level.
| Field | Type | Description |
|---|---|---|
id | string | Document identifier. |
fields | object | Requested document fields. |
datatype | string | The resolved document type (may differ from requested, see datatype notes above). |
Error Responses
| Status | Description |
|---|---|
500 | Malformed request. Common causes: missing datatype, missing constraints, missing query.language, or requesting fields/attributes not on the public whitelist. |
Array with documents.