{
  "openapi": "3.0.3",
  "info": {
    "title": "OboeLib — Official Public REST & MCP API",
    "version": "1.0.0",
    "description": "OboeLib provides a Conservatory-system oboe fingering workbench, trill dictionary, and reed adjustment troubleshooting guide. Oboists and band directors can look up exact Half-Hole rules (Db5, D5, Eb5), Left F vs Forked F vs Regular F voice-leading rules (eliminating finger sliding), 1st/2nd/3rd octave key transitions, and orchestral solo tuning notes.",
    "contact": {
      "name": "OboeLib",
      "url": "https://oboelib.com",
      "email": "admin@oboelib.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "externalDocs": {
    "description": "OboeLib Official Web Workbench",
    "url": "https://oboelib.com"
  },
  "servers": [
    {
      "url": "https://oboelib.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_oboelib_2026)"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "paths": {
    "/api/v1/me": {
      "get": {
        "operationId": "verifyApiConnection",
        "summary": "Verify OboeLib 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": "OboeLib"
                    },
                    "domain": {
                      "type": "string",
                      "example": "oboelib.com"
                    },
                    "version": {
                      "type": "string",
                      "example": "1.0.0"
                    },
                    "toolsCount": {
                      "type": "integer",
                      "example": 4
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tools": {
      "get": {
        "operationId": "listAvailableTools",
        "summary": "List All OboeLib Read-Only Tools & Schemas",
        "responses": {
          "200": {
            "description": "Array of available read-only tools"
          }
        }
      }
    },
    "/api/mcp": {
      "get": {
        "operationId": "getMcpServerMetadata",
        "summary": "Get OboeLib 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_oboe_fingering": {
      "post": {
        "operationId": "lookup_oboe_fingering",
        "summary": "Conservatory Oboe Fingering, Half-Hole & F-Mechanism Lookup",
        "description": "Look up Conservatory system oboe fingerings, Half-Hole register rules (Db5/D5/Eb5), Left F vs Forked F rules, and octave key switches.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "note": {
                    "type": "string",
                    "description": "Oboe written pitch (e.g. \"F4\", \"Db5\", \"D5\", \"E5\", \"A5\", \"C6\")"
                  }
                },
                "required": [
                  "note"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic JSON output from lookup_oboe_fingering"
          }
        }
      }
    },
    "/api/v1/tools/check_oboe_f_fingering_choice": {
      "post": {
        "operationId": "check_oboe_f_fingering_choice",
        "summary": "Oboe Regular F vs Left F vs Forked F Voice-Leading Resolver",
        "description": "Determine whether to finger Regular Side F, Left F, or Forked F given the preceding and following notes so fingers never slide across keys.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "previousNote": {
                    "type": "string",
                    "description": "Preceding note (e.g. \"D4\", \"Eb4\", \"E4\")"
                  },
                  "nextNote": {
                    "type": "string",
                    "description": "Following note (e.g. \"D4\", \"G4\", \"Db4\")"
                  }
                },
                "required": [
                  "previousNote",
                  "nextNote"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic JSON output from check_oboe_f_fingering_choice"
          }
        }
      }
    },
    "/api/v1/tools/diagnose_oboe_reed_response": {
      "post": {
        "operationId": "diagnose_oboe_reed_response",
        "summary": "Oboe Reed Crow, Pitch & Response Troubleshooting Guide",
        "description": "Diagnose sharp/flat A440 pitch, hard attacks, or collapsed openings on North American long-scrape and European short-scrape oboe reeds.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "issue": {
                    "type": "string",
                    "enum": [
                      "flat-and-stuffy",
                      "sharp-and-closed",
                      "hard-low-notes",
                      "dry-weather-tight"
                    ],
                    "description": "Observed reed issue"
                  }
                },
                "required": [
                  "issue"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic JSON output from diagnose_oboe_reed_response"
          }
        }
      }
    },
    "/api/v1/tools/lookup_conservatory_oboe_trills": {
      "post": {
        "operationId": "lookup_conservatory_oboe_trills",
        "summary": "Conservatory Oboe Trill Key & Banana-Key Reference",
        "description": "Look up dedicated trill keys (C-D trill levers, Ab-Bb trill, Left Eb-E, Banana key C-Db) on full Conservatory oboes.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "trill": {
                    "type": "string",
                    "description": "Trill pair (e.g. \"C5-D5\", \"Ab4-Bb4\", \"F#4-G#4\", \"B4-C#5\")"
                  }
                },
                "required": [
                  "trill"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic JSON output from lookup_conservatory_oboe_trills"
          }
        }
      }
    }
  }
}