{
  "openapi": "3.0.3",
  "info": {
    "title": "StrainCompass API",
    "version": "1.0.0",
    "description": "Server-side REST access to StrainCompass catalog records. Keep API keys on your server; browser-embedded keys are prohibited. Filtered pages are capped at page 50."
  },
  "servers": [{ "url": "https://straincompass.com" }],
  "paths": {
    "/api/strains": {
      "get": {
        "operationId": "listStrains",
        "summary": "Browse and filter strain records",
        "parameters": [
          { "$ref": "#/components/parameters/type" },
          { "$ref": "#/components/parameters/effect" },
          { "$ref": "#/components/parameters/flavor" },
          { "$ref": "#/components/parameters/terpene" },
          { "$ref": "#/components/parameters/breeder" },
          { "$ref": "#/components/parameters/slug" },
          { "$ref": "#/components/parameters/q" },
          { "$ref": "#/components/parameters/thcMin" },
          { "$ref": "#/components/parameters/thcMax" },
          { "$ref": "#/components/parameters/sort" },
          { "$ref": "#/components/parameters/page" },
          { "$ref": "#/components/parameters/limit" }
        ],
        "responses": {
          "200": { "description": "A bounded page of strain records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrainPage" } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }
        },
        "security": [{}, { "bearerAuth": [] }, { "apiKeyAuth": [] }]
      }
    },
    "/api/strains/search": {
      "get": {
        "operationId": "searchStrains",
        "summary": "Autocomplete strain search",
        "description": "Queries shorter than two characters return an empty result list. Queries longer than 120 characters return HTTP 400.",
        "parameters": [{ "$ref": "#/components/parameters/searchQuery" }],
        "responses": {
          "200": { "description": "Up to ten matching strains", "content": { "application/json": { "schema": { "type": "object", "required": ["results"], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } } } } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }
        },
        "security": [{}, { "bearerAuth": [] }, { "apiKeyAuth": [] }]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key" },
      "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" }
    },
    "parameters": {
      "type": { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["indica", "sativa", "hybrid", "cbd"] } },
      "effect": { "name": "effect", "in": "query", "schema": { "type": "string", "maxLength": 120 } },
      "flavor": { "name": "flavor", "in": "query", "schema": { "type": "string", "maxLength": 120 } },
      "terpene": { "name": "terpene", "in": "query", "schema": { "type": "string", "maxLength": 120 } },
      "breeder": { "name": "breeder", "in": "query", "schema": { "type": "string", "maxLength": 120 } },
      "slug": { "name": "slug", "in": "query", "schema": { "type": "string", "maxLength": 240 } },
      "q": { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 } },
      "searchQuery": { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 120 } },
      "thcMin": { "name": "thcMin", "in": "query", "schema": { "type": "number", "minimum": 0, "maximum": 100 } },
      "thcMax": { "name": "thcMax", "in": "query", "schema": { "type": "number", "minimum": 0, "maximum": 100 } },
      "sort": { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["popular", "name", "thc-high", "thc-low", "rating", "newest"], "default": "popular" } },
      "page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 1 } },
      "limit": { "name": "limit", "in": "query", "description": "Maximum depends on tier: anonymous 24, Free 50, Pro 100, Enterprise 500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 24 } }
    },
    "responses": {
      "Error": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" } } },
      "SearchResult": {
        "type": "object",
        "required": ["slug", "name", "type"],
        "properties": {
          "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" },
          "type": { "type": "string", "enum": ["INDICA", "SATIVA", "HYBRID", "CBD", "UNKNOWN"] },
          "thcMax": { "type": "number", "nullable": true },
          "imageUrl": { "type": "string", "nullable": true },
          "illustrationUrl": { "type": "string" },
          "illustrationKind": { "type": "string" },
          "illustrationDisclaimer": { "type": "string" },
          "effects": { "type": "array", "items": { "type": "object", "additionalProperties": true } }
        }
      },
      "StrainPage": {
        "type": "object",
        "required": ["strains", "total", "page", "limit", "totalPages", "maxPage", "paginationLimitReached"],
        "properties": {
          "strains": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "total": { "type": "integer" },
          "page": { "type": "integer" },
          "limit": { "type": "integer" },
          "totalPages": { "type": "integer" },
          "maxPage": { "type": "integer", "enum": [50] },
          "paginationLimitReached": { "type": "boolean" }
        }
      }
    }
  }
}
