{
  "openapi": "3.1.0",
  "info": {
    "title": "Navetica Sports Intelligence API",
    "version": "1.5.0",
    "description": "Authenticated sports intelligence infrastructure for humans and AI agents. Navetica transforms customer-supplied and properly licensed inputs into structured predictions, signal evaluation, decision context, and governed research outputs.",
    "termsOfService": "https://api.navetica.com/terms",
    "x-privacyPolicy": "https://api.navetica.com/privacy"
  },
  "servers": [
    {
      "url": "https://api.navetica.com",
      "description": "Primary edge (EWR)"
    },
    {
      "url": "https://api.navetica.com",
      "description": "Fallback edge (BOS)"
    }
  ],
  "tags": [
    {
      "name": "Public",
      "description": "Public discovery and documentation endpoints"
    },
    {
      "name": "Key Management",
      "description": "Self-serve API key rotation/revocation"
    },
    {
      "name": "Sports",
      "description": "Event context, predictions, and customer-input signal evaluation"
    },
    {
      "name": "Billing",
      "description": "Account usage and plan limits"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "MoneylineMap": {
        "type": "object",
        "description": "Customer-supplied American reference values keyed by outcome. The field name is retained for API compatibility.",
        "additionalProperties": {
          "type": "integer"
        }
      },
      "Notice": {
        "type": "object",
        "description": "Client-facing analytics-only disclaimer.",
        "properties": {
          "type": {
            "type": "string",
            "description": "Notice type."
          },
          "message": {
            "type": "string",
            "description": "Plain-language notice."
          },
          "use": {
            "type": "string",
            "description": "Use limitation."
          },
          "responsibility": {
            "type": "string",
            "description": "Client responsibility statement."
          }
        }
      },
      "PredictRequest": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string",
            "description": "Optional client-supplied trace id (also accepted as X-Request-Id)."
          },
          "sport": {
            "type": "string"
          },
          "teams": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "event_id": {
            "type": "string",
            "description": "Optional Navetica event identifier returned by /api/events."
          },
          "commence_time": {
            "type": "string",
            "description": "Optional event start time in UTC (ISO 8601)."
          },
          "confidence_threshold": {
            "type": "number"
          }
        },
        "required": [
          "sport"
        ]
      },
      "EdgeRequest": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string",
            "description": "Optional client-supplied trace id (also accepted as X-Request-Id)."
          },
          "sport": {
            "type": "string",
            "description": "Sport key (e.g., MLB, NBA, EPL)."
          },
          "teams": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Team names/codes (best-effort expanded)."
          },
          "event_id": {
            "type": "string",
            "description": "Optional Navetica event identifier returned by /api/events."
          },
          "commence_time": {
            "type": "string",
            "description": "Optional event start time in UTC (ISO 8601)."
          },
          "current_odds": {
            "$ref": "#/components/schemas/MoneylineMap",
            "description": "Customer-supplied market reference values keyed by team or outcome."
          },
          "reference_inputs": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            },
            "description": "Required customer-supplied probability references keyed by team or outcome. Values must be 0..1."
          }
        },
        "required": [
          "sport",
          "teams",
          "current_odds",
          "reference_inputs"
        ]
      },
      "GenericResponse": {
        "type": "object",
        "additionalProperties": true
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "issues": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional machine-readable validation issues (present when error=QA_REJECT)."
          }
        },
        "required": [
          "error"
        ]
      },
      "PredictionPreviewResponse": {
        "type": "object",
        "description": "Free-tier prediction preview. Expanded probability and signal fields are documented in the authenticated paid specification.",
        "properties": {
          "response_version": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "predict"
            ]
          },
          "request_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "sport": {
            "type": [
              "string",
              "null"
            ]
          },
          "teams": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "timestamp_utc": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "prediction": {
            "type": "object",
            "properties": {
              "winner": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "confidence_band": {
                "type": "string",
                "enum": [
                  "high",
                  "moderate",
                  "limited",
                  "unavailable"
                ]
              },
              "method": {
                "type": "string",
                "enum": [
                  "navetica_preview"
                ]
              }
            }
          },
          "recommended_action": {
            "type": "string",
            "enum": [
              "preview_only"
            ]
          },
          "data_quality": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string"
              },
              "vault_hit": {
                "type": "boolean",
                "description": "Indicates that prepared Navetica context was available."
              },
              "moneyline_simulated": {
                "type": "boolean",
                "description": "Indicates that a reference input was simulated rather than supplied."
              },
              "snapshot_age_minutes": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Age of the prepared context when available."
              }
            }
          },
          "rate_limit": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "tier_surface": {
            "type": "string",
            "enum": [
              "free_preview"
            ]
          },
          "notice": {
            "$ref": "#/components/schemas/Notice"
          },
          "access": {
            "type": "object",
            "properties": {
              "tier": {
                "type": "string",
                "enum": [
                  "free"
                ]
              },
              "detail": {
                "type": "string",
                "enum": [
                  "preview"
                ]
              },
              "upgrade_required": {
                "type": "boolean"
              },
              "paid_fields": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "EdgePreviewResponse": {
        "type": "object",
        "description": "Free-tier confirmation for a customer-input signal evaluation. Calculated metrics and recommendations require an eligible paid plan.",
        "properties": {
          "response_version": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "edge"
            ]
          },
          "request_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "sport": {
            "type": [
              "string",
              "null"
            ]
          },
          "teams": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "timestamp_utc": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "evaluation": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "complete"
                ]
              },
              "input_provenance": {
                "type": "string",
                "enum": [
                  "customer_supplied"
                ]
              }
            }
          },
          "recommended_action": {
            "type": "string",
            "enum": [
              "preview_only"
            ]
          },
          "data_quality": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string"
              },
              "vault_hit": {
                "type": "boolean",
                "description": "Indicates that prepared Navetica context was available."
              }
            }
          },
          "rate_limit": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "tier_surface": {
            "type": "string",
            "enum": [
              "free_preview"
            ]
          },
          "notice": {
            "$ref": "#/components/schemas/Notice"
          },
          "access": {
            "type": "object",
            "properties": {
              "tier": {
                "type": "string",
                "enum": [
                  "free"
                ]
              },
              "detail": {
                "type": "string",
                "enum": [
                  "preview"
                ]
              },
              "upgrade_required": {
                "type": "boolean"
              },
              "paid_fields": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "Service discovery",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "Health check",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "OpenAPI spec",
        "responses": {
          "200": {
            "description": "OpenAPI JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          }
        }
      }
    },
    "/docs": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "Swagger UI",
        "responses": {
          "200": {
            "description": "HTML"
          }
        }
      }
    },
    "/api/model/changelog": {
      "get": {
        "tags": [
          "Client"
        ],
        "summary": "Model audit trail (public by key)",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "sport",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/context": {
      "post": {
        "tags": [
          "AI"
        ],
        "summary": "Return structured context for LLMs (no external calls)",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scope": {
                    "type": "string",
                    "description": "Context scope: 'full' | 'usage' | 'performance' | 'changelog'",
                    "default": "full"
                  },
                  "days": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 90,
                    "default": 30
                  },
                  "format": {
                    "type": "string",
                    "description": "Response format: 'structured' | 'text'",
                    "default": "structured"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/keys/me": {
      "get": {
        "tags": [
          "Key Management"
        ],
        "summary": "Key and account status",
        "description": "Returns the stable account_id, subscription tier, plan, and key-management status. account_id is the permanent account scope; API keys are replaceable credentials.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/usage": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "Account usage and plan limits",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/events": {
      "get": {
        "tags": [
          "Sports"
        ],
        "summary": "List available events with stable event identifiers",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Client-safe event discovery for prediction and signal-evaluation requests. Use the returned event_id with /api/predict or /api/edge when event-specific context is required.",
        "parameters": [
          {
            "name": "sport",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          },
          {
            "name": "include_expired",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/predict": {
      "post": {
        "tags": [
          "Sports"
        ],
        "summary": "Generate a structured prediction preview",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Returns a tier-aware prediction response with traceable event context. Free access receives a limited preview; expanded probability, signal, and decision fields require an eligible paid plan.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PredictRequest"
              },
              "examples": {
                "mlb": {
                  "summary": "MLB prediction",
                  "value": {
                    "sport": "MLB",
                    "teams": [
                      "NYY",
                      "BOS"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PredictionPreviewResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "406": {
            "description": "Not acceptable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/edge": {
      "post": {
        "tags": [
          "Sports"
        ],
        "summary": "Evaluate customer-supplied reference inputs",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EdgeRequest"
              },
              "examples": {
                "keyed_references": {
                  "summary": "Per-team customer references",
                  "value": {
                    "sport": "MLB",
                    "teams": [
                      "NYY",
                      "BOS"
                    ],
                    "current_odds": {
                      "NYY": -120,
                      "BOS": 110
                    },
                    "reference_inputs": {
                      "NYY": 0.52,
                      "BOS": 0.48
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EdgePreviewResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "description": "Two-outcome REST contract: provide sport, two teams, current_odds keyed by team or outcome, and customer-supplied probabilities. Prefer reference_inputs keyed by team or outcome; the legacy true_probability scalar remains accepted for compatibility. Requests without usable teams, market values, or customer probabilities are rejected. For single selected-outcome sessions over MCP, use submit_reference_session with selection_team."
      }
    }
  }
}