{
  "openapi": "3.0.3",
  "info": {
    "title": "Relatiq Tracker — Public API",
    "version": "1.0.0",
    "description": "The only endpoint intended for external integration is `GET /rq/recos`. There is no separate public ingestion API — the tracking snippet (`rq.js`) handles event collection internally over an encrypted, origin-restricted channel, and isn't meant to be called directly.\n\nTo call `/rq/recos` correctly, pass the visitor's session ID from `window.RelatiqTracker.sessionId()` (available once the tracking snippet has loaded on the page) as the `session` query parameter."
  },
  "servers": [
    { "url": "/" }
  ],
  "paths": {
    "/rq/recos": {
      "get": {
        "summary": "Get recommendations for a visitor",
        "description": "Returns ranked recommendations for a tracked visitor, sourced from this deployment's connected search backend (configured under Settings → Recommendations in the admin dashboard).\n\nReturns an empty array — never an error — whenever there's nothing to recommend yet: no search connection configured, the visitor has fewer than 5 tracked page views (not enough signal for a good match), or the search backend is temporarily unreachable.\n\nEach returned item is `{ score, ...document }` — a relevance score plus whatever fields exist on the matched document in the connected index (e.g. `title`, `url`, `tags` for a product catalog; field names vary per deployment since each customer's content schema is different). There is no fixed document shape beyond `score` — treat the rest as your own known content fields.",
        "parameters": [
          {
            "name": "index",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Which content index to search (a doc_type/collection name defined on your connected search backend — e.g. \"products\", \"articles\")."
          },
          {
            "name": "session",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "The visitor's session ID, from `window.RelatiqTracker.sessionId()` in the browser."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 },
            "description": "Maximum number of recommendations to return."
          }
        ],
        "responses": {
          "200": {
            "description": "Recommendations for this visitor, ranked by relevance — an empty array if there's nothing to recommend yet.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": ["score"],
                    "properties": {
                      "score": { "type": "number", "description": "Relevance score reported by the search backend." }
                    },
                    "additionalProperties": true,
                    "description": "score plus every field the matched document has in your connected index — this varies per deployment."
                  }
                },
                "examples": {
                  "product-catalog": {
                    "summary": "Example with a product-catalog index",
                    "value": [
                      { "score": 0.91, "title": "Wool Blend Overcoat", "url": "/products/wool-overcoat", "tags": ["fashion", "home"] },
                      { "score": 0.84, "title": "Running Shoes Pro", "url": "/products/running-shoes", "tags": ["fashion", "sports"] }
                    ]
                  },
                  "no-recommendations-yet": {
                    "summary": "No search connection configured, or not enough visitor signal yet",
                    "value": []
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing required `index` parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "error": { "type": "string" } }
                },
                "example": { "error": "index required" }
              }
            }
          }
        }
      }
    }
  }
}