{
  "openapi": "3.0.3",
  "info": {
    "title": "TbmLib — Official Public REST & MCP API",
    "version": "1.0.0",
    "description": "TbmLib is an acoustic reference and interactive slide position workbench for Tenor, F-attachment, and Bass trombone players. Musicians can check primary 1st-through-7th slide positions, F-trigger shortcuts (converting 6th/7th position low C3 and B2 into T-1 and T-flat-2), natural harmonic cent adjustments (raising flat 5th-partial D4 in 1st position), and legato doodle-tongue slurs.",
    "contact": {
      "name": "TbmLib",
      "url": "https://tbmlib.com",
      "email": "admin@tbmlib.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "externalDocs": {
    "description": "TbmLib Official Web Workbench",
    "url": "https://tbmlib.com"
  },
  "servers": [
    {
      "url": "https://tbmlib.com",
      "description": "Production Cloudflare Global Edge"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Optional API Key for Albato / automation tracking (e.g. pk_live_tbmlib_2026)"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "paths": {
    "/api/v1/me": {
      "get": {
        "operationId": "verifyApiConnection",
        "summary": "Verify TbmLib API Key & Service Health",
        "description": "Authentication test and metadata endpoint for Albato App Integrator, RapidAPI, Make, and custom workflows.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          },
          {}
        ],
        "responses": {
          "200": {
            "description": "Authenticated connection status and tool count",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "authenticated": {
                      "type": "boolean",
                      "example": true
                    },
                    "service": {
                      "type": "string",
                      "example": "TbmLib"
                    },
                    "domain": {
                      "type": "string",
                      "example": "tbmlib.com"
                    },
                    "version": {
                      "type": "string",
                      "example": "1.0.0"
                    },
                    "toolsCount": {
                      "type": "integer",
                      "example": 4
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tools": {
      "get": {
        "operationId": "listAvailableTools",
        "summary": "List All TbmLib Read-Only Tools & Schemas",
        "responses": {
          "200": {
            "description": "Array of available read-only tools"
          }
        }
      }
    },
    "/api/mcp": {
      "get": {
        "operationId": "getMcpServerMetadata",
        "summary": "Get TbmLib MCP Server Metadata",
        "responses": {
          "200": {
            "description": "MCP Server metadata and Grade-A tool annotations"
          }
        }
      },
      "post": {
        "operationId": "invokeMcpJsonRpc",
        "summary": "Execute Streamable HTTP JSON-RPC 2.0 MCP Request",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "id",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "example": "2.0"
                  },
                  "id": {
                    "type": "integer",
                    "example": 1
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "initialize",
                      "tools/list",
                      "tools/call"
                    ],
                    "example": "tools/list"
                  },
                  "params": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response envelope"
          }
        }
      }
    },
    "/api/v1/tools/lookup_trombone_slide_position": {
      "post": {
        "operationId": "lookup_trombone_slide_position",
        "summary": "Tenor & F-Attachment Trombone Slide Position Lookup",
        "description": "Look up primary slide position (1st–7th), F-trigger shortcut position, alternate legato positions, and harmonic cent adjustments for any trombone pitch.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "note": {
                    "type": "string",
                    "description": "Concert pitch note name with octave (e.g. \"Bb2\", \"C3\", \"B2\", \"F3\", \"D4\", \"F4\")"
                  }
                },
                "required": [
                  "note"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic JSON output from lookup_trombone_slide_position"
          }
        }
      }
    },
    "/api/v1/tools/analyze_trombone_overtone_intonation": {
      "post": {
        "operationId": "analyze_trombone_overtone_intonation",
        "summary": "Trombone Harmonic Partial Cent Deviation & Slide Adjustment Guide",
        "description": "Analyze equal-temperament cent deviations across partials 2 through 8 (including the -14 cent flat 5th partial and -31 cent 7th partial) for any slide position.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "slidePosition": {
                    "type": "integer",
                    "description": "Slide position from 1 to 7"
                  }
                },
                "required": [
                  "slidePosition"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic JSON output from analyze_trombone_overtone_intonation"
          }
        }
      }
    },
    "/api/v1/tools/compare_trombone_bore_and_mouthpieces": {
      "post": {
        "operationId": "compare_trombone_bore_and_mouthpieces",
        "summary": "Small-Bore Jazz vs Large-Bore Symphonic Trombone & Mouthpiece Selector",
        "description": "Compare .500/.508 small-shank jazz horns vs .547 large-bore F-attachment orchestral horns and standard Bach/Schilke mouthpiece sizes (12C, 6.5AL, 5G, 4G, 1.5G).",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "style": {
                    "type": "string",
                    "enum": [
                      "beginner-band",
                      "jazz-lead",
                      "symphonic-tenor",
                      "bass-trombone"
                    ],
                    "description": "Performance context"
                  }
                },
                "required": [
                  "style"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic JSON output from compare_trombone_bore_and_mouthpieces"
          }
        }
      }
    },
    "/api/v1/tools/generate_trombone_legato_warmup": {
      "post": {
        "operationId": "generate_trombone_legato_warmup",
        "summary": "Daily Trombone Remington Long-Tone & Legato Tongue Routine",
        "description": "Generate a structured trombone warm-up covering Remington relaxation tones, natural slurs, F-valve coordination, and \"Dah/Doo\" legato tonguing.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "minutes": {
                    "type": "integer",
                    "description": "Practice warm-up minutes (15, 30, 45)"
                  }
                },
                "required": [
                  "minutes"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic JSON output from generate_trombone_legato_warmup"
          }
        }
      }
    }
  }
}