{
  "openapi": "3.0.1",
  "info": {
    "title": "The Equestrian App - AI Agent & MCP Gateway",
    "description": "Secure Model Context Protocol and REST tool APIs powering AI assistants (Grok Bot, Google Gemini, Meta Muse, Claude, OpenAI GPTs) with horse healthcare, nutrition, condition evaluation, and journal logging.",
    "version": "1.0.0",
    "contact": {
      "name": "The Equestrian App Support",
      "url": "https://mcp.equestrianapp.com"
    }
  },
  "servers": [
    {
      "url": "https://mcp.equestrianapp.com",
      "description": "Production MCP Gateway"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Personal Access Token (PAT)",
        "description": "Personal Access Token (PAT) prefixed with 'eq_pat_live_'."
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Health Check",
        "description": "Returns service health status, runtime version, and gateway endpoints.",
        "operationId": "getHealth",
        "security": [],
        "responses": {
          "200": { "description": "Service operational status" }
        }
      }
    },
    "/api/v1/tools/horses": {
      "get": {
        "summary": "List User's Horses",
        "description": "Returns all active horses owned by or connected to the authenticated user. Excludes deleted horses.",
        "operationId": "listHorses",
        "responses": {
          "200": { "description": "List of horses owned by or connected to user" },
          "401": { "description": "Unauthorized - invalid or missing Bearer token" }
        }
      }
    },
    "/api/v1/tools/health": {
      "get": {
        "summary": "Get Horse Healthcare & Farrier History",
        "description": "Retrieves medical, dental/teeth floating, farrier resets, bodywork, and vaccination history for a specific horse.",
        "operationId": "getHorseHealth",
        "parameters": [
          {
            "name": "horseId",
            "in": "query",
            "required": true,
            "description": "The unique HorseID to query",
            "schema": { "type": "integer", "format": "int64" }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Optional filter: Dental, Farrier, Vaccines, Vet, Bodywork",
            "schema": { "type": "string" }
          },
          {
            "name": "searchQuery",
            "in": "query",
            "required": false,
            "description": "Search query in notes, clinician, or details",
            "schema": { "type": "string" }
          },
          {
            "name": "lookupDate",
            "in": "query",
            "required": false,
            "description": "Optional date filter (e.g. 2026-04-15) to query records on or before date",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum records to return (default 20)",
            "schema": { "type": "integer", "default": 20 }
          }
        ],
        "responses": {
          "200": { "description": "Health records returned" },
          "401": { "description": "Unauthorized" },
          "404": { "description": "Horse not found or access denied" }
        }
      }
    },
    "/api/v1/tools/nutrition": {
      "get": {
        "summary": "Get Horse Diet & Feeding Schedule",
        "description": "Retrieves active feed items, hay, grain, supplements, measurements, and feeding instructions for a horse.",
        "operationId": "getHorseNutrition",
        "parameters": [
          {
            "name": "horseId",
            "in": "query",
            "required": true,
            "description": "The unique HorseID to query",
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": { "description": "Diet and nutrition schedule" },
          "401": { "description": "Unauthorized" },
          "404": { "description": "Horse not found or access denied" }
        }
      }
    },
    "/api/v1/tools/evaluate-health": {
      "get": {
        "summary": "Synthesize Horse Condition & Workload Context",
        "description": "Gathers vitals, active feed, past 30 days workload/rides, and upcoming health schedules to evaluate condition.",
        "operationId": "evaluateHorseHealth",
        "parameters": [
          {
            "name": "horseId",
            "in": "query",
            "required": true,
            "description": "The unique HorseID to evaluate",
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": { "description": "Comprehensive evaluation context for AI reasoning" },
          "401": { "description": "Unauthorized" },
          "404": { "description": "Horse not found or access denied" }
        }
      }
    },
    "/api/v1/tools/journal": {
      "get": {
        "summary": "Get Horse Journal & Timeline History",
        "description": "Retrieves journal, rides, training logs, care notes, and timeline entries for a horse, including horse details and latest updates, optionally filtered by category, keywords, or lookup date.",
        "operationId": "getHorseJournal",
        "parameters": [
          {
            "name": "horseId",
            "in": "query",
            "required": true,
            "description": "The unique HorseID to query",
            "schema": { "type": "integer", "format": "int64" }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Optional filter: all, Ride, Care, Training, Medical, Farrier, Feeding, Journal",
            "schema": { "type": "string" }
          },
          {
            "name": "searchQuery",
            "in": "query",
            "required": false,
            "description": "Search query in notes, category, or location",
            "schema": { "type": "string" }
          },
          {
            "name": "lookupDate",
            "in": "query",
            "required": false,
            "description": "Optional date filter (e.g. 2026-04-15) to query entries on or before date",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum records to return (default 20)",
            "schema": { "type": "integer", "default": 20 }
          }
        ],
        "responses": {
          "200": { "description": "Journal history returned" },
          "401": { "description": "Unauthorized" },
          "404": { "description": "Horse not found or access denied" }
        }
      },
      "post": {
        "summary": "Create Journal / Activity Entry",
        "description": "Creates a new journal entry, ride log, training note, or care activity for a horse.",
        "operationId": "createJournalEntry",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["horseId", "title", "notes"],
                "properties": {
                  "horseId": { "type": "integer", "format": "int64", "description": "The horse ID" },
                  "title": { "type": "string", "description": "Title of entry" },
                  "notes": { "type": "string", "description": "Observations, training notes, or healthcare details" },
                  "activityType": { "type": "string", "default": "Ride", "description": "Ride, Training, Care, Lesson, Vet, Farrier" },
                  "durationMinutes": { "type": "integer", "default": 45, "description": "Duration in minutes" },
                  "intensity": { "type": "string", "default": "Moderate", "description": "Light, Moderate, Heavy" },
                  "rating": { "type": "integer", "default": 5, "description": "Rating 1 to 5" },
                  "entryDate": { "type": "string", "format": "date-time", "description": "Date/time of activity (defaults to now)" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Journal entry created successfully" },
          "400": { "description": "Bad request" },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/api/v1/tools/journal/search": {
      "get": {
        "summary": "Multi-Keyword Search Across Horse Journals",
        "description": "Searches journal entries, timeline posts, rides, and care logs across all horses (or a specific horse) using multi-word keywords (e.g. 'Dusty Farrier', 'Bella dental', 'trail ride 2026'). Matches horse name, category, notes, location, and dates.",
        "operationId": "searchJournals",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "Search query or keywords (e.g. 'Dusty Farrier')",
            "schema": { "type": "string" }
          },
          {
            "name": "horseId",
            "in": "query",
            "required": false,
            "description": "Optional horse ID to filter to a single horse",
            "schema": { "type": "integer", "format": "int64" }
          },
          {
            "name": "lookupDate",
            "in": "query",
            "required": false,
            "description": "Optional date filter (e.g. 2026-04-15) to query entries on or before date",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum records to return (default 20)",
            "schema": { "type": "integer", "default": 20 }
          }
        ],
        "responses": {
          "200": { "description": "List of matching journal entries" },
          "400": { "description": "Bad request" },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/api/v1/tools/events": {
      "get": {
        "summary": "Get Scheduled Calendar Events",
        "description": "Retrieves scheduled appointments, lessons, vet visits, and farrier events for the user or a specific horse.",
        "operationId": "getCalendarEvents",
        "parameters": [
          {
            "name": "horseId",
            "in": "query",
            "required": false,
            "description": "Optional horse ID filter",
            "schema": { "type": "integer", "format": "int64" }
          },
          {
            "name": "startDate",
            "in": "query",
            "required": false,
            "description": "Optional start date filter",
            "schema": { "type": "string" }
          },
          {
            "name": "endDate",
            "in": "query",
            "required": false,
            "description": "Optional end date filter",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max records to return",
            "schema": { "type": "integer", "default": 20 }
          }
        ],
        "responses": {
          "200": { "description": "List of calendar events" },
          "401": { "description": "Unauthorized" }
        }
      },
      "post": {
        "summary": "Schedule Calendar Event",
        "description": "Schedules an appointment, reminder, lesson, or vet/farrier visit for a horse or the user's barn calendar.",
        "operationId": "createCalendarEvent",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["title", "startDate"],
                "properties": {
                  "title": { "type": "string", "description": "Event title" },
                  "startDate": { "type": "string", "format": "date-time", "description": "Start date/time" },
                  "endDate": { "type": "string", "format": "date-time", "description": "Optional end date/time" },
                  "horseId": { "type": "integer", "format": "int64", "description": "Optional horse ID" },
                  "eventType": { "type": "string", "description": "Farrier, Veterinarian, Lesson, Training, Show, Healthcare, Clinic, Bodywork, ToDo, or Other" },
                  "durationMinutes": { "type": "integer", "default": 60, "description": "Duration in minutes" },
                  "location": { "type": "string", "description": "Optional location" },
                  "isAllDay": { "type": "boolean", "default": false, "description": "All day flag" },
                  "notes": { "type": "string", "description": "Optional notes" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Calendar event created successfully" },
          "400": { "description": "Bad request" },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/mcp": {
      "post": {
        "summary": "Model Context Protocol Streamable HTTP Gateway",
        "description": "Standard MCP JSON-RPC 2.0 gateway endpoint. Routes to the identical handler as /mcp/rpc. Supports 'initialize', 'tools/list', and 'tools/call'.",
        "operationId": "mcpRoot",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["jsonrpc", "method", "id"],
                "properties": {
                  "jsonrpc": { "type": "string", "example": "2.0" },
                  "id": { "type": "string", "example": "1" },
                  "method": { "type": "string", "example": "tools/list" },
                  "params": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "JSON-RPC 2.0 Response" }
        }
      }
    },
    "/mcp/rpc": {
      "post": {
        "summary": "Model Context Protocol JSON-RPC 2.0 Gateway",
        "description": "Standard MCP JSON-RPC 2.0 gateway for Claude Desktop, Gemini, Grok Bot, and custom agents. Supports 'initialize', 'tools/list', and 'tools/call'.",
        "operationId": "mcpRpc",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["jsonrpc", "method", "id"],
                "properties": {
                  "jsonrpc": { "type": "string", "example": "2.0" },
                  "id": { "type": "string", "example": "1" },
                  "method": { "type": "string", "example": "tools/list" },
                  "params": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "JSON-RPC 2.0 Response" }
        }
      }
    },
    "/mcp/sse": {
      "get": {
        "summary": "Model Context Protocol Server-Sent Events (SSE)",
        "description": "Server-Sent Events endpoint establishing persistent transport for MCP AI clients.",
        "operationId": "mcpSse",
        "responses": {
          "200": { "description": "SSE stream connected" }
        }
      }
    }
  }
}