{
  "openapi": "3.1.0",
  "info": {
    "title": "WOXA Search API",
    "version": "1.0.0",
    "summary": "Private, zero-AI web search over WOXA's own Thai + English index and open/community sources.",
    "description": "Results come only from WOXA's own index and open/community sources (Wikipedia, Hacker News, GitHub, arXiv, Stack Exchange, Lemmy, Mastodon, Nostr, Internet Archive, CoinGecko, DexScreener). No commercial search engine results are ever returned. WOXA never stores or logs query text; only per-key request counters and timestamps are kept. Keys are stored as SHA-256 hashes.\n\nAuthenticate with `Authorization: Bearer <key>` or `X-API-Key: <key>`. Keys in the URL are rejected.\n\nEvery metered response carries `X-RateLimit-Limit` (requests per second), `X-RateLimit-Remaining` (whole requests left in the burst), `X-RateLimit-Reset` (seconds until the burst is full), `X-Quota-Limit` / `X-Quota-Remaining` (monthly search quota, or `unlimited`), `X-Quota-Used` and `X-Quota-Reset` (Unix time of the next UTC month start). A 429 always includes `Retry-After` in seconds.",
    "termsOfService": "https://search.api.woxa.com/terms",
    "contact": { "name": "WOXA API", "email": "api@woxa.com", "url": "https://search.api.woxa.com" }
  },
  "servers": [{ "url": "https://search.api.woxa.com" }],
  "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
  "tags": [
    { "name": "Search" },
    { "name": "Account" },
    { "name": "Portal" },
    { "name": "Meta" }
  ],
  "paths": {
    "/v1/search": {
      "get": {
        "tags": ["Search"],
        "operationId": "search",
        "summary": "Web search",
        "description": "Search WOXA's own index plus open/community sources. Counts 1 query against the monthly quota. Search operators inside `q` are supported: `site:example.com`, `-site:`, `\"exact phrase\"`, `-exclude`, `intitle:`, `inurl:`, `filetype:`, `after:YYYY-MM-DD`, `before:YYYY-MM-DD`.",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "description": "Query text (1-512 characters). Supports search operators.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "example": "เชียงใหม่ site:wikipedia.org" },
          { "name": "lang", "in": "query", "description": "Keep only results in this language. `auto` keeps every language.", "schema": { "type": "string", "enum": ["auto", "th", "en"], "default": "auto" } },
          { "name": "count", "in": "query", "description": "Results per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } },
          { "name": "offset", "in": "query", "description": "Number of results to skip. `offset + count` must not exceed 200.", "schema": { "type": "integer", "minimum": 0, "maximum": 199, "default": 0 } },
          { "name": "lens", "in": "query", "description": "Ranking lens.", "schema": { "type": "string", "enum": ["all", "tech", "finance", "indie", "decentralized", "osint"], "default": "all" } },
          { "name": "tab", "in": "query", "description": "Result vertical. `news` is an alias of `feeds`.", "schema": { "type": "string", "enum": ["web", "news", "feeds", "code", "decentralized", "markets"], "default": "web" } },
          { "name": "safesearch", "in": "query", "schema": { "type": "string", "enum": ["off", "moderate", "strict"], "default": "moderate" } },
          { "name": "freshness", "in": "query", "description": "Keep only results with a known publication date within the last day, week or month.", "schema": { "type": "string", "enum": ["day", "week", "month"] } }
        ],
        "responses": {
          "200": {
            "description": "Search results.",
            "headers": {
              "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "X-Quota-Limit": { "$ref": "#/components/headers/QuotaLimit" },
              "X-Quota-Remaining": { "$ref": "#/components/headers/QuotaRemaining" },
              "X-Quota-Used": { "$ref": "#/components/headers/QuotaUsed" },
              "X-Quota-Reset": { "$ref": "#/components/headers/QuotaReset" }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/v1/suggest": {
      "get": {
        "tags": ["Search"],
        "operationId": "suggest",
        "summary": "Autocomplete suggestions",
        "description": "Suggestions from WOXA's own index. Uses the per-second rate limit but does not count against the monthly quota.",
        "parameters": [
          { "name": "q", "in": "query", "required": false, "description": "Prefix typed so far (up to 128 characters). Empty returns no suggestions.", "schema": { "type": "string", "maxLength": 128 }, "example": "bangk" },
          { "name": "count", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 8 } }
        ],
        "responses": {
          "200": {
            "description": "Suggestions.",
            "headers": {
              "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestResponse" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "tags": ["Account"],
        "operationId": "usage",
        "summary": "Usage and limits for the calling key",
        "description": "Not metered. Returns counters only; WOXA keeps no record of what was searched.",
        "responses": {
          "200": { "description": "Usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/v1/plans": {
      "get": {
        "tags": ["Meta"],
        "operationId": "plans",
        "summary": "Available plans",
        "security": [],
        "responses": {
          "200": {
            "description": "Plans.",
            "content": { "application/json": { "schema": { "type": "object", "required": ["plans", "default_plan"], "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } }, "default_plan": { "type": "string" } } } } }
          }
        }
      }
    },
    "/v1/openapi.json": {
      "get": {
        "tags": ["Meta"],
        "operationId": "openapi",
        "summary": "This OpenAPI document",
        "security": [],
        "responses": { "200": { "description": "OpenAPI 3.1 document.", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/v1/health": {
      "get": {
        "tags": ["Meta"],
        "operationId": "health",
        "summary": "Service health",
        "security": [],
        "responses": {
          "200": {
            "description": "Healthy.",
            "content": { "application/json": { "schema": { "type": "object", "required": ["status"], "properties": { "status": { "type": "string", "const": "ok" }, "api_version": { "type": "string" }, "version": { "type": "string" }, "search_ready": { "type": "boolean" }, "time": { "type": "string", "format": "date-time" } } } } }
          }
        }
      }
    },
    "/v1/portal/signup": {
      "post": {
        "tags": ["Portal"],
        "operationId": "signup",
        "summary": "Create a Free API key",
        "description": "Returns the full key exactly once. Limited per client network (the address is only held as a rotating in-memory HMAC and never stored). No password: the key is the credential.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["email", "accept_terms"], "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "accept_terms": { "type": "boolean", "const": true } } } } }
        },
        "responses": {
          "201": { "description": "Key created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewKeyResponse" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "409": { "description": "This email already has the maximum number of active keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "415": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/v1/portal/rotate": {
      "post": {
        "tags": ["Portal"],
        "operationId": "rotateKey",
        "summary": "Replace the calling key",
        "description": "Issues a new key (shown once) on the same plan with the same usage counters, and revokes the calling key immediately.",
        "responses": {
          "200": { "description": "New key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewKeyResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/v1/portal/upgrade-request": {
      "post": {
        "tags": ["Portal"],
        "operationId": "upgradeRequest",
        "summary": "Ask the WOXA team to move you to a paid plan",
        "description": "Records the request for the team; no payment is taken. Sending your key (optional) links the request to it.",
        "security": [{}, { "bearerAuth": [] }, { "apiKeyHeader": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["plan", "email"], "additionalProperties": false, "properties": { "plan": { "type": "string", "description": "A paid plan id from /v1/plans." }, "email": { "type": "string", "format": "email" }, "company": { "type": "string", "maxLength": 200 }, "message": { "type": "string", "maxLength": 2000 } } } } }
        },
        "responses": {
          "202": { "description": "Recorded.", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "id"], "properties": { "status": { "type": "string", "const": "received" }, "id": { "type": "string" }, "plan": { "type": "string" }, "notice": { "type": "string" } } } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer wx_live_..." },
      "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" }
    },
    "headers": {
      "RateLimitLimit": { "description": "Sustained requests per second for this key.", "schema": { "type": "number" } },
      "RateLimitRemaining": { "description": "Requests left in the current burst.", "schema": { "type": "integer" } },
      "RateLimitReset": { "description": "Seconds until the burst is fully refilled.", "schema": { "type": "integer" } },
      "QuotaLimit": { "description": "Monthly search quota, or `unlimited`.", "schema": { "type": "string" } },
      "QuotaRemaining": { "description": "Searches left this month, or `unlimited`.", "schema": { "type": "string" } },
      "QuotaUsed": { "description": "Searches counted this month.", "schema": { "type": "integer" } },
      "QuotaReset": { "description": "Unix time (seconds) when the monthly quota resets (start of next UTC month).", "schema": { "type": "integer" } },
      "RetryAfter": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }
    },
    "responses": {
      "BadRequest": { "description": "Invalid parameters or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unauthorized": { "description": "Missing or invalid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Forbidden": { "description": "The key was revoked (`key_revoked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "TooManyRequests": {
        "description": "`rate_limited` (per-second limit) or `quota_exceeded` (monthly quota).",
        "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "ServerError": { "description": "Server-side failure; the call is not counted against the quota.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "string", "enum": ["invalid_request", "terms_not_accepted", "unauthorized", "forbidden", "key_revoked", "not_found", "method_not_allowed", "email_limit", "rate_limited", "quota_exceeded", "internal_error", "unavailable"] },
              "message": { "type": "string" }
            }
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "required": ["title", "url", "display_url", "snippet", "published_at", "source", "language", "score"],
        "properties": {
          "title": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "display_url": { "type": "string", "description": "Host and path without scheme, at most 80 characters." },
          "snippet": { "type": "string" },
          "published_at": { "type": ["string", "null"], "format": "date-time" },
          "source": { "type": "string", "description": "`woxa` when WOXA's own index has the page, otherwise the open source that returned it (e.g. `wikipedia-th`, `hackernews`, `github`, `arxiv`)." },
          "language": { "type": "string", "examples": ["th", "en"] },
          "score": { "type": "number", "description": "Relative ranking score within this response (higher is better). Not comparable across queries." }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": ["query", "results", "total_estimated", "next_offset", "took_ms", "sources_used", "own_index_share"],
        "properties": {
          "query": { "type": "string" },
          "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } },
          "total_estimated": { "type": "integer", "description": "Estimated number of matching results (after filters)." },
          "next_offset": { "type": ["integer", "null"], "description": "Pass as `offset` to get the next page; null when there are no more results." },
          "took_ms": { "type": "integer" },
          "sources_used": { "type": "array", "items": { "type": "string" }, "description": "Sources that answered this query (`woxa` = WOXA's own index)." },
          "own_index_share": { "type": "number", "minimum": 0, "maximum": 1, "description": "Fraction of returned results that WOXA's own index contains." }
        }
      },
      "SuggestResponse": {
        "type": "object",
        "required": ["query", "suggestions"],
        "properties": { "query": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } } }
      },
      "Plan": {
        "type": "object",
        "required": ["id", "name", "monthly_quota", "rate_per_sec", "burst"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "monthly_quota": { "type": "integer", "description": "Searches per calendar month (UTC). 0 = custom / unmetered." },
          "rate_per_sec": { "type": "number" },
          "burst": { "type": "number" },
          "price_usd_month": { "type": "integer" },
          "price_thb_month": { "type": "integer" },
          "contact_sales": { "type": "boolean" },
          "self_serve": { "type": "boolean" },
          "description": { "type": "string" }
        }
      },
      "KeyInfo": {
        "type": "object",
        "required": ["prefix", "display", "plan", "status", "created_at"],
        "properties": {
          "prefix": { "type": "string", "examples": ["wx_live_ab12cd34ef56"] },
          "display": { "type": "string" },
          "plan": { "type": "string" },
          "status": { "type": "string", "enum": ["active", "revoked"] },
          "created_at": { "type": "string", "format": "date-time" },
          "last_used_at": { "type": "string", "format": "date-time", "description": "Rounded to the minute." },
          "email": { "type": "string", "description": "Masked except right after signup." },
          "email_verified": { "type": "boolean" }
        }
      },
      "NewKeyResponse": {
        "type": "object",
        "required": ["api_key", "key"],
        "properties": {
          "api_key": { "type": "string", "description": "The full key. Shown only once." },
          "key": { "$ref": "#/components/schemas/KeyInfo" },
          "plan": { "$ref": "#/components/schemas/Plan" },
          "revoked_prefix": { "type": "string", "description": "Rotate only: the key that stopped working." },
          "notice": { "type": "string" }
        }
      },
      "UsageResponse": {
        "type": "object",
        "required": ["key", "plan", "limits", "today", "month", "daily"],
        "properties": {
          "key": { "$ref": "#/components/schemas/KeyInfo" },
          "plan": { "$ref": "#/components/schemas/Plan" },
          "limits": { "type": "object", "properties": { "monthly_quota": { "type": "integer" }, "rate_per_sec": { "type": "number" }, "burst": { "type": "number" } } },
          "today": { "type": "object", "properties": { "date": { "type": "string" }, "requests": { "type": "integer" }, "errors": { "type": "integer" } } },
          "month": { "type": "object", "properties": { "month": { "type": "string" }, "queries": { "type": "integer" }, "requests": { "type": "integer" }, "errors": { "type": "integer" }, "quota_remaining": { "type": ["integer", "string"] }, "resets_at": { "type": "string", "format": "date-time" } } },
          "total_requests": { "type": "integer" },
          "daily": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "requests": { "type": "integer" } } } }
        }
      }
    }
  }
}
