{
  "openapi": "3.1.0",
  "info": {
    "title": "Tolinks Public API",
    "version": "1.0.0",
    "description": "Programmatic access to Tolinks link-in-bio pages. Authenticated endpoints use API tokens issued in the dashboard (Agency plan).",
    "contact": { "email": "support@tolinks.in" }
  },
  "servers": [{ "url": "https://tolinks.in" }],
  "tags": [
    { "name": "Pages", "description": "Public page data, no authentication required" },
    { "name": "Links", "description": "Manage links on your own page (Bearer token required)" }
  ],
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/api/health": {
      "get": {
        "tags": ["System"],
        "summary": "Health check",
        "responses": {
          "200": {
            "description": "Service is up",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } }
          }
        }
      }
    },
    "/api/public/v1/page/{handle}": {
      "get": {
        "tags": ["Pages"],
        "summary": "Fetch a public page by handle",
        "security": [],
        "parameters": [
          { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Page handle without @, e.g. rishav" }
        ],
        "responses": {
          "200": {
            "description": "Public profile and active links",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page" } } }
          },
          "400": { "description": "Invalid handle" },
          "404": { "description": "Page not found or disabled" }
        }
      }
    },
    "/api/public/v1/links": {
      "get": {
        "tags": ["Links"],
        "summary": "List links of the authenticated page",
        "responses": {
          "200": {
            "description": "Profile and links for the API token owner",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page" } } }
          },
          "401": { "description": "Missing or invalid Bearer token" },
          "403": { "description": "Page unavailable or plan does not include API access" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API token from the dashboard API page" }
    },
    "schemas": {
      "Health": {
        "type": "object",
        "properties": { "status": { "type": "string" }, "service": { "type": "string" }, "time": { "type": "string" } }
      },
      "Link": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "url": { "type": "string" },
          "icon": { "type": "string", "nullable": true },
          "style": { "type": "string", "nullable": true },
          "position": { "type": "integer" }
        }
      },
      "Page": {
        "type": "object",
        "properties": {
          "handle": { "type": "string" },
          "displayName": { "type": "string" },
          "bio": { "type": "string", "nullable": true },
          "avatarUrl": { "type": "string", "nullable": true },
          "links": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } }
        }
      }
    }
  }
}