{
  "openapi": "3.1.0",
  "info": {
    "title": "Linkflare API",
    "version": "1.0.0",
    "description": "Public and authenticated REST API for Linkflare — the universal bookmark manager and personal knowledge system. Authenticated endpoints accept a Clerk session bearer token or a personal API key (see https://linkflare.io/auth.md).",
    "contact": { "url": "https://linkflare.io/docs/" }
  },
  "servers": [
    { "url": "https://api.linkflare.io", "description": "Production API" }
  ],
  "externalDocs": {
    "description": "Linkflare documentation",
    "url": "https://linkflare.io/docs/"
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Clerk session token or personal API key."
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Personal API key generated in app settings."
      }
    }
  },
  "paths": {
    "/public/profile": {
      "get": {
        "summary": "Get a user's public profile and discoverable shares",
        "operationId": "getPublicProfile",
        "parameters": [
          { "name": "username", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Public profile with discoverable collections, saved searches, and knowledge cards." } }
      }
    },
    "/public/resolve": {
      "get": {
        "summary": "Resolve a public share URL to its share metadata",
        "operationId": "resolvePublicShare",
        "responses": { "200": { "description": "Resolved share metadata." } }
      }
    },
    "/public/sitemap": {
      "get": {
        "summary": "List public shares for sitemap generation",
        "operationId": "getPublicSitemap",
        "responses": { "200": { "description": "JSON list of public shares." } }
      }
    },
    "/links": {
      "get": {
        "summary": "List the authenticated user's bookmarks",
        "operationId": "getLinks",
        "security": [{ "bearerAuth": [] }, { "apiKeyAuth": [] }],
        "responses": {
          "200": { "description": "{ links, tags, types, total }." },
          "401": { "description": "Missing or invalid credentials." }
        }
      }
    },
    "/knowledge": {
      "get": {
        "summary": "List the authenticated user's knowledge cards (Pro)",
        "operationId": "getKnowledge",
        "security": [{ "bearerAuth": [] }, { "apiKeyAuth": [] }],
        "responses": {
          "200": { "description": "{ knowledge, total }." },
          "401": { "description": "Missing or invalid credentials." }
        }
      }
    }
  }
}