{
  "openapi": "3.1.0",
  "info": {
    "title": "tabs.garden Public API",
    "summary": "Public API for discovering tabs.garden songs and tab JSON payloads.",
    "description": "The tabs.garden Public API exposes no-login read endpoints for agents and developers that need song metadata and machine-readable guitar tab payloads.",
    "version": "1.0.0",
    "contact": {
      "name": "tabs.garden",
      "url": "https://tabs.garden/contact/",
      "email": "contact@tabs.garden"
    }
  },
  "servers": [
    { "url": "https://tabs.garden", "description": "Production" }
  ],
  "tags": [
    { "name": "Songs", "description": "Song index discovery endpoints." },
    { "name": "Tabs", "description": "Tab payload retrieval endpoints." }
  ],
  "paths": {
    "/api/songs": {
      "get": {
        "operationId": "listSongs",
        "tags": ["Songs"],
        "summary": "List public songs",
        "description": "Returns the complete public tabs.garden song index. Use each song entry's file field to derive the tabKey for /api/tabs/{tabKey}.",
        "responses": {
          "200": {
            "description": "Array of public song records.",
            "headers": {
              "ETag": { "description": "Version hash for conditional requests.", "schema": { "type": "string" } },
              "Cache-Control": { "description": "Public cache policy.", "schema": { "type": "string" } }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/SongReference" }
                }
              }
            }
          },
          "304": { "description": "The song index has not changed for the supplied If-None-Match ETag." },
          "503": {
            "description": "Songs are temporarily unavailable.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          }
        }
      }
    },
    "/api/tabs/{tabKey}": {
      "get": {
        "operationId": "getTabByKey",
        "tags": ["Tabs"],
        "summary": "Get a tab payload",
        "description": "Returns a single machine-readable guitar tab payload. The tabKey is the song file name from /api/songs without the .json suffix.",
        "parameters": [
          {
            "name": "tabKey",
            "in": "path",
            "required": true,
            "description": "Tab JSON identifier, derived from a song file field by removing the .json extension.",
            "schema": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9._-]+$" }
          }
        ],
        "responses": {
          "200": {
            "description": "A tab payload with metadata, chord list, tuning, and lyric-aligned tab sections.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TabPayload" } } }
          },
          "400": {
            "description": "Invalid tab identifier.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          },
          "404": {
            "description": "Tab not found.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SongReference": {
        "type": "object",
        "required": ["id", "title", "artist", "file"],
        "properties": {
          "id": { "type": "string", "description": "Stable tabs.garden song identifier." },
          "title": { "type": "string", "description": "Song title." },
          "artist": { "type": "string", "description": "Primary artist name." },
          "file": { "type": "string", "description": "Tab JSON file name, for example abc123.json." },
          "metadata": { "$ref": "#/components/schemas/SongMetadata" },
          "genres": { "type": "array", "items": { "type": "string" }, "description": "Optional genre labels." }
        },
        "additionalProperties": true
      },
      "SongMetadata": {
        "type": "object",
        "properties": {
          "capo": { "type": "string" },
          "difficulty": { "type": "string" },
          "key": { "type": "string" },
          "tuning": { "type": "array", "items": { "type": "string" } }
        },
        "additionalProperties": true
      },
      "TabPayload": {
        "type": "object",
        "required": ["title", "artist", "tabs"],
        "properties": {
          "url": { "type": "string", "format": "uri", "description": "Source tab URL when available." },
          "title": { "type": "string" },
          "artist": { "type": "string" },
          "tuning": { "type": "array", "items": { "type": "string" } },
          "capo": { "type": "string" },
          "difficulty": { "type": "string" },
          "chords_unique": { "type": "array", "items": { "type": "string" } },
          "tabs": {
            "type": "array",
            "description": "Lyric and chord rows grouped into sections.",
            "items": { "type": "object", "additionalProperties": true }
          },
          "_meta": { "type": "object", "additionalProperties": true }
        },
        "additionalProperties": true
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["message"],
        "properties": { "message": { "type": "string" } }
      }
    }
  }
}