{
  "openapi": "3.1.0",
  "info": {
    "title": "Oddly Likely Public Markets API",
    "version": "1.0.0",
    "description": "Read-only access to published market summaries and evidence-led analysis. No authentication is required. Version 1 is stable; breaking changes use a new versioned path and retiring versions are announced at least 90 days before removal.",
    "license": {
      "name": "All rights reserved",
      "identifier": "LicenseRef-Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://oddlylikely.com"
    }
  ],
  "security": [],
  "paths": {
    "/api/v1/markets.json": {
      "get": {
        "operationId": "listMarkets",
        "summary": "List published market analyses",
        "description": "Returns the current catalogue of published market identifiers, canonical URLs, Markdown companions, status, and event metadata.",
        "tags": [
          "Markets"
        ],
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "description": "Requested response media type. This endpoint serves application/json.",
            "schema": {
              "type": "string",
              "enum": [
                "application/json"
              ],
              "default": "application/json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Published market summaries",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MarketList"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Maximum requests allowed during the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests remaining during the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/markets/{marketId}.json": {
      "get": {
        "operationId": "getMarket",
        "summary": "Get one published market analysis",
        "description": "Returns one typed market record with editorial evidence, recorded price offers, and cited sources.",
        "tags": [
          "Markets"
        ],
        "parameters": [
          {
            "name": "marketId",
            "in": "path",
            "required": true,
            "description": "Stable lowercase identifier returned by listMarkets.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]+$",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Published market analysis",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Market"
                }
              }
            }
          },
          "400": {
            "description": "Invalid market identifier",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Market not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Maximum requests allowed during the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests remaining during the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "hint",
              "status"
            ],
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "hint": {
                "type": "string"
              },
              "status": {
                "type": "integer"
              }
            }
          }
        }
      },
      "MarketList": {
        "type": "object",
        "required": [
          "apiVersion",
          "documentation",
          "markets"
        ],
        "additionalProperties": false,
        "properties": {
          "apiVersion": {
            "type": "string",
            "const": "v1"
          },
          "documentation": {
            "type": "string",
            "format": "uri"
          },
          "markets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MarketSummary"
            }
          }
        }
      },
      "EventSummary": {
        "type": "object",
        "required": [
          "name",
          "sport",
          "competition",
          "startsAt",
          "marketType",
          "participants"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string"
          },
          "sport": {
            "type": "string"
          },
          "competition": {
            "type": "string"
          },
          "startsAt": {
            "type": "string",
            "format": "date-time"
          },
          "venue": {
            "type": [
              "string",
              "null"
            ]
          },
          "marketType": {
            "type": "string"
          },
          "participants": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "MarketSummary": {
        "type": "object",
        "required": [
          "id",
          "url",
          "markdownUrl",
          "title",
          "description",
          "status",
          "event"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "markdownUrl": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "upcoming",
              "archived"
            ]
          },
          "modifiedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "event": {
            "$ref": "#/components/schemas/EventSummary"
          }
        }
      },
      "ProofPoint": {
        "type": "object",
        "required": [
          "value",
          "label"
        ],
        "additionalProperties": false,
        "properties": {
          "value": {
            "type": "string"
          },
          "label": {
            "type": "string"
          }
        }
      },
      "Editorial": {
        "type": "object",
        "required": [
          "backedSide",
          "thesis",
          "shortAnswer",
          "counterargument",
          "response",
          "proofPoints"
        ],
        "additionalProperties": false,
        "properties": {
          "backedSide": {
            "type": "string"
          },
          "thesis": {
            "type": "string"
          },
          "shortAnswer": {
            "type": "string"
          },
          "counterargument": {
            "type": "string"
          },
          "response": {
            "type": "string"
          },
          "proofPoints": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProofPoint"
            }
          }
        }
      },
      "Offer": {
        "type": "object",
        "required": [
          "partner",
          "rank",
          "prices",
          "checkedAt"
        ],
        "additionalProperties": false,
        "properties": {
          "partner": {
            "type": "string"
          },
          "rank": {
            "type": "integer"
          },
          "prices": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            }
          },
          "checkedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "Source": {
        "type": "object",
        "required": [
          "name",
          "url"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Market": {
        "type": "object",
        "required": [
          "id",
          "url",
          "markdownUrl",
          "title",
          "description",
          "status",
          "event",
          "editorial",
          "offers",
          "sources"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "markdownUrl": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "upcoming",
              "archived"
            ]
          },
          "modifiedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "event": {
            "$ref": "#/components/schemas/EventSummary"
          },
          "editorial": {
            "$ref": "#/components/schemas/Editorial"
          },
          "offers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Offer"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Source"
            }
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "Oddly Likely developer resources, versioning, and usage policy",
    "url": "https://oddlylikely.com/developers.html"
  }
}