{
  "name": "Grade",
  "description": "Catálogo pesquisável de transmissões públicas (iptv-org) e biblioteca pessoal endereçável: categorias, sub-abas, feeds M3U/JSON/XSPF. Sem proxy de mídia.",
  "auth": {
    "none": "Público, sem credencial.",
    "guest": "Guest `ipt_…` (`POST /api/guest` em `X-Guest-Token` ou Bearer) ou API key `iptk_…` (Bearer / `X-Api-Key`). A key é a conta do agente.",
    "token": "Token de operador `METRICS_TOKEN`."
  },
  "docs": {
    "llms": "https://gradetv.pages.dev/llms.txt",
    "openapi": "https://gradetv.pages.dev/openapi.json",
    "human_ui": "https://gradetv.pages.dev/"
  },
  "endpoints": [
    {
      "method": "GET",
      "path": "/api/",
      "auth": "none",
      "summary": "Índice auto-descrito.",
      "returns": "{ name, endpoints[] }",
      "url": "https://gradetv.pages.dev/api/",
      "auth_detail": "Público, sem credencial."
    },
    {
      "method": "GET",
      "path": "/api/health",
      "auth": "none",
      "summary": "Liveness e build.",
      "returns": "{ ok, app, build, ts }",
      "url": "https://gradetv.pages.dev/api/health",
      "auth_detail": "Público, sem credencial."
    },
    {
      "method": "GET",
      "path": "/api/channels",
      "auth": "none",
      "summary": "Busca paginada do catálogo (q, country, category, language, playable, nsfw).",
      "returns": "{ items[], limit, offset, next_offset, filters }",
      "url": "https://gradetv.pages.dev/api/channels",
      "auth_detail": "Público, sem credencial."
    },
    {
      "method": "GET",
      "path": "/api/channels/:id",
      "auth": "none",
      "summary": "Canal + streams + URLs absolutas.",
      "returns": "{ id, name, streams[], api, _links }",
      "url": "https://gradetv.pages.dev/api/channels/:id",
      "auth_detail": "Público, sem credencial."
    },
    {
      "method": "GET",
      "path": "/api/countries",
      "auth": "none",
      "summary": "Facetas de país.",
      "returns": "{ items[] }",
      "url": "https://gradetv.pages.dev/api/countries",
      "auth_detail": "Público, sem credencial."
    },
    {
      "method": "GET",
      "path": "/api/categories",
      "auth": "none",
      "summary": "Facetas de categoria iptv-org.",
      "returns": "{ items[] }",
      "url": "https://gradetv.pages.dev/api/categories",
      "auth_detail": "Público, sem credencial."
    },
    {
      "method": "GET",
      "path": "/api/languages",
      "auth": "none",
      "summary": "Facetas de idioma.",
      "returns": "{ items[] }",
      "url": "https://gradetv.pages.dev/api/languages",
      "auth_detail": "Público, sem credencial."
    },
    {
      "method": "POST",
      "path": "/api/guest",
      "auth": "none",
      "summary": "Cria guest `ipt_…`.",
      "returns": "{ token }",
      "url": "https://gradetv.pages.dev/api/guest",
      "auth_detail": "Público, sem credencial."
    },
    {
      "method": "POST",
      "path": "/api/keys",
      "auth": "guest",
      "summary": "Mint API key `iptk_…` (texto 1×).",
      "returns": "{ id, token, masked }",
      "url": "https://gradetv.pages.dev/api/keys",
      "auth_detail": "Guest `ipt_…` (`POST /api/guest` em `X-Guest-Token` ou Bearer) ou API key `iptk_…` (Bearer / `X-Api-Key`). A key é a conta do agente."
    },
    {
      "method": "GET",
      "path": "/api/keys",
      "auth": "guest",
      "summary": "Lista chaves mascaradas do dono.",
      "returns": "{ keys[] }",
      "url": "https://gradetv.pages.dev/api/keys",
      "auth_detail": "Guest `ipt_…` (`POST /api/guest` em `X-Guest-Token` ou Bearer) ou API key `iptk_…` (Bearer / `X-Api-Key`). A key é a conta do agente."
    },
    {
      "method": "DELETE",
      "path": "/api/keys/:id",
      "auth": "guest",
      "summary": "Revoga uma key.",
      "returns": "{ ok }",
      "url": "https://gradetv.pages.dev/api/keys/:id",
      "auth_detail": "Guest `ipt_…` (`POST /api/guest` em `X-Guest-Token` ou Bearer) ou API key `iptk_…` (Bearer / `X-Api-Key`). A key é a conta do agente."
    },
    {
      "method": "GET",
      "path": "/api/library",
      "auth": "guest",
      "summary": "Árvore categoria → sub-aba → canais + URLs de feed.",
      "returns": "{ owner, feeds, categories[] }",
      "url": "https://gradetv.pages.dev/api/library",
      "auth_detail": "Guest `ipt_…` (`POST /api/guest` em `X-Guest-Token` ou Bearer) ou API key `iptk_…` (Bearer / `X-Api-Key`). A key é a conta do agente."
    },
    {
      "method": "POST",
      "path": "/api/categories",
      "auth": "guest",
      "summary": "Cria tab principal.",
      "body": {
        "name": "Notícias"
      },
      "returns": "{ id, …library }",
      "url": "https://gradetv.pages.dev/api/categories",
      "auth_detail": "Guest `ipt_…` (`POST /api/guest` em `X-Guest-Token` ou Bearer) ou API key `iptk_…` (Bearer / `X-Api-Key`). A key é a conta do agente."
    },
    {
      "method": "PATCH",
      "path": "/api/categories/:id",
      "auth": "guest",
      "summary": "Renomeia categoria.",
      "body": {
        "name": "…"
      },
      "returns": "{ …library }",
      "url": "https://gradetv.pages.dev/api/categories/:id",
      "auth_detail": "Guest `ipt_…` (`POST /api/guest` em `X-Guest-Token` ou Bearer) ou API key `iptk_…` (Bearer / `X-Api-Key`). A key é a conta do agente."
    },
    {
      "method": "DELETE",
      "path": "/api/categories/:id",
      "auth": "guest",
      "summary": "Apaga categoria e o que tem dentro.",
      "returns": "{ …library }",
      "url": "https://gradetv.pages.dev/api/categories/:id",
      "auth_detail": "Guest `ipt_…` (`POST /api/guest` em `X-Guest-Token` ou Bearer) ou API key `iptk_…` (Bearer / `X-Api-Key`). A key é a conta do agente."
    },
    {
      "method": "POST",
      "path": "/api/groups",
      "auth": "guest",
      "summary": "Cria sub-aba.",
      "body": {
        "category_id": "cat_…",
        "name": "Manchete"
      },
      "returns": "{ id, …library }",
      "url": "https://gradetv.pages.dev/api/groups",
      "auth_detail": "Guest `ipt_…` (`POST /api/guest` em `X-Guest-Token` ou Bearer) ou API key `iptk_…` (Bearer / `X-Api-Key`). A key é a conta do agente."
    },
    {
      "method": "DELETE",
      "path": "/api/groups/:id",
      "auth": "guest",
      "summary": "Apaga sub-aba.",
      "returns": "{ …library }",
      "url": "https://gradetv.pages.dev/api/groups/:id",
      "auth_detail": "Guest `ipt_…` (`POST /api/guest` em `X-Guest-Token` ou Bearer) ou API key `iptk_…` (Bearer / `X-Api-Key`). A key é a conta do agente."
    },
    {
      "method": "POST",
      "path": "/api/items",
      "auth": "guest",
      "summary": "Põe um canal na sub-aba.",
      "body": {
        "group_id": "grp_…",
        "channel_id": "Globo.br"
      },
      "returns": "{ id, …library }",
      "url": "https://gradetv.pages.dev/api/items",
      "auth_detail": "Guest `ipt_…` (`POST /api/guest` em `X-Guest-Token` ou Bearer) ou API key `iptk_…` (Bearer / `X-Api-Key`). A key é a conta do agente."
    },
    {
      "method": "DELETE",
      "path": "/api/items/:id",
      "auth": "guest",
      "summary": "Remove canal da sub-aba.",
      "returns": "{ …library }",
      "url": "https://gradetv.pages.dev/api/items/:id",
      "auth_detail": "Guest `ipt_…` (`POST /api/guest` em `X-Guest-Token` ou Bearer) ou API key `iptk_…` (Bearer / `X-Api-Key`). A key é a conta do agente."
    },
    {
      "method": "POST",
      "path": "/api/items/:id/play",
      "auth": "guest",
      "summary": "Marca último canal tocado da sub-aba.",
      "returns": "{ …library }",
      "url": "https://gradetv.pages.dev/api/items/:id/play",
      "auth_detail": "Guest `ipt_…` (`POST /api/guest` em `X-Guest-Token` ou Bearer) ou API key `iptk_…` (Bearer / `X-Api-Key`). A key é a conta do agente."
    },
    {
      "method": "GET",
      "path": "/api/billing",
      "auth": "none",
      "summary": "Preço do contato e tetos da galeria.",
      "returns": "{ prices, limits, network }",
      "url": "https://gradetv.pages.dev/api/billing",
      "auth_detail": "Público, sem credencial."
    },
    {
      "method": "POST",
      "path": "/api/contact",
      "auth": "none",
      "summary": "Contato: Turnstile (humano) ou x402 $0.10 (agente).",
      "body": {
        "name": "…",
        "email": "a@example.com",
        "message": "…",
        "form_ts": 0
      },
      "returns": "{ ok } | 402",
      "url": "https://gradetv.pages.dev/api/contact",
      "auth_detail": "Público, sem credencial."
    },
    {
      "method": "POST",
      "path": "/api/visit",
      "auth": "none",
      "summary": "Cada ping da UI incrementa o contador do dia. Sem janela.",
      "returns": "{ ok, counted }",
      "url": "https://gradetv.pages.dev/api/visit",
      "auth_detail": "Público, sem credencial."
    },
    {
      "method": "GET",
      "path": "/api/metrics",
      "auth": "none",
      "summary": "Métricas 7d. Sem token: visitas/uso/contas. Com METRICS_TOKEN: + payments (só Base mainnet).",
      "returns": "{ app, today_visits, days[], usage, accounts [, payments] }",
      "url": "https://gradetv.pages.dev/api/metrics",
      "auth_detail": "Público, sem credencial."
    }
  ],
  "quickstart": [
    "POST https://gradetv.pages.dev/api/guest → ipt_…",
    "GET https://gradetv.pages.dev/api/channels?country=BR&playable=1",
    "POST https://gradetv.pages.dev/api/keys com X-Guest-Token → iptk_…",
    "GET https://gradetv.pages.dev/api/library com Bearer iptk_…"
  ]
}