--- updatedAt: 2026-04-28T09:31:16.000Z agentTools: projectIndex: https://docs.makaira.io/llms.txt --- # Get documents by id and/or datatype 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 ```json { "datatype": "makaira-productgroup", "ids": ["product-123", "product-456"], "constraints": { "query.language": "de" } } ``` ### Example Request — Fetch with field filter ```json { "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. | # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Makaira API", "version": "1.0", "contact": { "name": "Makaira GmbH", "url": "https://www.makaira.io/", "email": "support@makaira.io" }, "description": "API of the powerful Makaira Search/Recommendation and Marketing Suite" }, "servers": [ { "url": "https://{yourinstance}.makaira.io" } ], "paths": { "/documents/public": { "post": { "tags": [ "Documents" ], "summary": "Get documents by id and/or datatype", "description": "Get documents directly from Elasticsearch, by id and/or document type.", "operationId": "post-documents-field", "parameters": [ { "$ref": "#/components/parameters/instance" } ], "responses": { "200": { "description": "Array with documents." }, "500": { "description": "Object with error description.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "type": "string", "description": "Error description. Possible responses:\n- \"Notice: Undefined index: datatype\"\n- \"Notice: Undefined index: constraints\"\n- \"Notice: Undefined index: query.language\"\n- \"Fields ... not allowed.\"\n- \"Attribute Ids ... not allowed.\"" }, "endpoint": { "type": "string" }, "file": { "type": "string" }, "line": { "type": "number" }, "stack": { "description": "Stack trace", "type": "array", "items": { "type": "string" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "datatype": { "type": "string", "description": "Datatype of the documents to retrieve.\n\nSpecial cases:\n- makaira-product will retrieve documents with datatype variant\n (datatype in the response will be makaira-product)\n- makaira-productgroup will retrieve documents with datatype product\n (datatype in the response will be makaira-productgroup)\n- variant will retrieve documents with datatype variant but the\n datatype in the response will be makaira-product\n- product will retrieve documents with datatype product but the\n datatype in the response will be makaira-productgroup" }, "ids": { "description": "The ids of the documents to retrieve.\n\nIf this array is undefined or empty then you get all documents of the given datatype.\nBe careful, this can produce very large responses.", "type": "array", "items": { "type": "string" } }, "includeContent": { "description": "If this is set to true, then the response will contain the content of the documents.", "type": "boolean" }, "fields": { "description": "Filter for the document fields to retrieve.\n\nIf not defined or empty then you will get all public fields that are whitelisted on the details page.\n\nYou can not use this to get fields that are not whitelisted.", "type": "array", "items": { "type": "string" } }, "aggregations": { "type": "object", "description": "List of selected values to filter for." }, "sorting": { "type": "object" }, "constraints": { "description": "Use this to specify the language and filter the attributes.", "type": "object", "properties": { "query.language": { "type": "string", "example": "de" }, "query.attribute_ids": { "type": "array", "items": { "type": "string" }, "description": "You can filter attributes with this.\n\nIf you give an empty list or omit this parameter,\nthen the response contains all public attributes of the detail view.\nHint: If you specify fields, but no attribute field, then this parameter has no effect." } } } }, "required": [ "datatype", "constraints" ] } } } } } } }, "components": { "parameters": { "instance": { "in": "header", "name": "X-Makaira-Instance", "required": true, "description": "Makaira Instance ID", "schema": { "type": "string" } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authentication by JSON Web Token\n" } } }, "security": [ { "bearerAuth": [] } ], "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ```