{
  "openapi": "3.1.0",
  "info": {
    "title": "Lolik Intelligence API",
    "version": "1.0.0",
    "description": "Live trend → money-ready brief, in one call. Data endpoints cost 1 credit; intelligence endpoints cost 5. Max 10 items per call; no pagination by design."
  },
  "servers": [
    {
      "url": "https://lolikai.eu"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "paths": {
    "/api/public/trends": {
      "get": {
        "operationId": "trends",
        "summary": "Top trending topics from our aggregated cache.",
        "tags": [
          "data"
        ],
        "parameters": [
          {
            "name": "niche",
            "in": "query",
            "required": false,
            "description": "Filter to a niche.",
            "schema": {
              "type": "string",
              "enum": [
                "AI",
                "Crypto",
                "Tech",
                "Finance",
                "Business",
                "Health"
              ]
            }
          },
          {
            "name": "source",
            "in": "query",
            "required": false,
            "description": "Where the trend is measured.",
            "schema": {
              "type": "string",
              "enum": [
                "google",
                "youtube"
              ],
              "default": "google"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientCredits"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/public/news": {
      "get": {
        "operationId": "news",
        "summary": "Freshest news stories from our cache.",
        "tags": [
          "data"
        ],
        "parameters": [
          {
            "name": "topic",
            "in": "query",
            "required": false,
            "description": "Filter to a topic.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientCredits"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/public/forecast": {
      "get": {
        "operationId": "forecast",
        "summary": "Timing / momentum / lifecycle for a topic (rising vs peaking).",
        "tags": [
          "data"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Topic to forecast.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientCredits"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/public/virality-score": {
      "get": {
        "operationId": "virality_score",
        "summary": "Virality score + breakout probability + hook type for a topic.",
        "tags": [
          "data"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Topic or title to score.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientCredits"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/public/opportunities": {
      "get": {
        "operationId": "opportunities",
        "summary": "Ranked opportunities with possible monetization paths.",
        "tags": [
          "intelligence"
        ],
        "parameters": [
          {
            "name": "niche",
            "in": "query",
            "required": false,
            "description": "Filter to a niche.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientCredits"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/public/brief": {
      "get": {
        "operationId": "brief",
        "summary": "The daily what-to-post brief: phase-labeled pre-breakout alerts + measured receipts + a validated pattern + the day's steepest mover.",
        "tags": [
          "intelligence"
        ],
        "parameters": [
          {
            "name": "niche",
            "in": "query",
            "required": false,
            "description": "Filter to a niche.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientCredits"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/public/hook-rescue": {
      "get": {
        "operationId": "hook_rescue",
        "summary": "Hooks for your topic, anchored in the title patterns currently VALIDATED across creators (live data, not a static list). Hook text is AI-drafted; the proof next to each is measured.",
        "tags": [
          "intelligence"
        ],
        "parameters": [
          {
            "name": "topic",
            "in": "query",
            "required": true,
            "description": "Your topic or working title (4-120 chars).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientCredits"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/public/grade": {
      "get": {
        "operationId": "grade",
        "summary": "Grade a draft title/hook against the patterns currently VALIDATED in live data — this week's data, not a static rubric. Score math runs in code; every component states its basis (measured / ai_judged / rule).",
        "tags": [
          "intelligence"
        ],
        "parameters": [
          {
            "name": "draft",
            "in": "query",
            "required": true,
            "description": "Your draft title or hook (4-200 chars).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientCredits"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/public/prebreakout": {
      "get": {
        "operationId": "prebreakout",
        "summary": "What's accelerating now, before it peaks — early-mover signal.",
        "tags": [
          "intelligence"
        ],
        "parameters": [
          {
            "name": "niche",
            "in": "query",
            "required": false,
            "description": "Filter to a niche.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientCredits"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/public/viral-patterns": {
      "get": {
        "operationId": "viral_patterns",
        "summary": "Validated viral patterns (hook / structure) confirmed over time by convergence + persistence + amplification. The moat.",
        "tags": [
          "intelligence"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientCredits"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/public/usage": {
      "get": {
        "operationId": "usage",
        "summary": "Credits remaining + rate-limit status. Free — spends no credit or rate slot.",
        "tags": [
          "data"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-lolik-api-key"
      }
    },
    "schemas": {
      "Envelope": {
        "type": "object",
        "properties": {
          "data": {},
          "confidence": {
            "type": "string",
            "enum": [
              "observed",
              "aiEstimated",
              "pending"
            ]
          },
          "credits_used": {
            "type": "integer"
          },
          "credits_remaining": {
            "type": "integer"
          }
        },
        "required": [
          "data",
          "confidence",
          "credits_used",
          "credits_remaining"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing / invalid / revoked key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "InsufficientCredits": {
        "description": "Out of credits (carries credits_remaining + topup_url)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over a rate limit (scope: burst | daily | intel). Retry-After header set.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}