{
  "openapi": "3.1.0",
  "info": {
    "title": "Zorse games API",
    "version": "1.0.0",
    "description": "A public, static catalog generated from the same content as the Zorse website. No authentication is required. API contracts use major versions in the URL; backward-compatible additions may be released within v1, and clients should ignore unknown response fields. Breaking changes require a new major version. Version 1 is supported with no retirement scheduled. Retirement requires at least 90 days of notice, a working replacement, a migration guide, and Deprecation and Sunset response headers. See https://zorse.io/api#versioning."
  },
  "externalDocs": {
    "description": "Usage, response fields, and examples",
    "url": "https://zorse.io/api"
  },
  "servers": [
    {
      "url": "https://zorse.io"
    }
  ],
  "security": [],
  "paths": {
    "/api/v1": {
      "get": {
        "operationId": "getApiVersion",
        "summary": "Discover the version 1 API",
        "description": "Get the version support status and links to the game catalog, documentation, and OpenAPI schema. Also supports HEAD with the same status and headers and no body.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "The version 1 discovery index.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiVersionIndex"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/games": {
      "get": {
        "operationId": "listGames",
        "summary": "List all Zorse games",
        "description": "Use this operation to find Zorse games, compare descriptions and supported platforms, or get store download links. It returns the complete catalog; filter the games locally. It provides published information only and performs no actions. Also supports HEAD with the same status and headers and no body.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "The complete catalog, in the same order as the website, with descriptions and store download links.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GameCatalog"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "ApiNotFound": {
        "description": "RFC 9457 problem details for GET requests to unknown /api/ endpoints (HTTP 404). HEAD returns the same status and headers without a body. The error and links extension members preserve the original routing error fields. This does not describe origin errors for known API files.",
        "headers": {
          "Cache-Control": {
            "schema": {
              "type": "string",
              "const": "no-store"
            }
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ApiNotFound"
            }
          }
        }
      }
    },
    "schemas": {
      "ApiVersionIndex": {
        "type": "object",
        "required": [
          "version",
          "status",
          "documentation",
          "openapi",
          "endpoints"
        ],
        "properties": {
          "version": {
            "type": "string",
            "const": "v1"
          },
          "status": {
            "type": "string",
            "enum": [
              "supported",
              "deprecated"
            ],
            "description": "The version lifecycle status. Version 1 is currently supported with no retirement scheduled."
          },
          "documentation": {
            "type": "string",
            "format": "uri",
            "const": "https://zorse.io/api"
          },
          "openapi": {
            "type": "string",
            "format": "uri",
            "const": "https://zorse.io/openapi.json"
          },
          "endpoints": {
            "type": "object",
            "required": [
              "games"
            ],
            "properties": {
              "games": {
                "type": "string",
                "format": "uri",
                "const": "https://zorse.io/api/v1/games"
              }
            }
          }
        }
      },
      "ApiNotFound": {
        "type": "object",
        "description": "RFC 9457 routing problem with compatibility extensions. See https://www.rfc-editor.org/rfc/rfc9457.html.",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "instance",
          "error",
          "links"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "const": "about:blank"
          },
          "title": {
            "type": "string",
            "const": "Not Found"
          },
          "status": {
            "type": "integer",
            "const": 404
          },
          "detail": {
            "type": "string",
            "const": "Unknown API endpoint."
          },
          "instance": {
            "type": "string",
            "format": "uri-reference",
            "description": "The requested unknown API path, without its query string."
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "status"
            ],
            "properties": {
              "code": {
                "type": "string",
                "const": "not_found"
              },
              "message": {
                "type": "string",
                "const": "Unknown API endpoint."
              },
              "status": {
                "type": "integer",
                "const": 404
              }
            }
          },
          "links": {
            "type": "object",
            "required": [
              "documentation",
              "games",
              "openapi"
            ],
            "properties": {
              "documentation": {
                "type": "string",
                "format": "uri",
                "const": "https://zorse.io/api"
              },
              "games": {
                "type": "string",
                "format": "uri",
                "const": "https://zorse.io/api/v1/games"
              },
              "openapi": {
                "type": "string",
                "format": "uri",
                "const": "https://zorse.io/openapi.json"
              }
            }
          }
        }
      },
      "GameCatalog": {
        "type": "object",
        "required": [
          "schemaVersion",
          "games"
        ],
        "properties": {
          "schemaVersion": {
            "type": "integer",
            "const": 1
          },
          "games": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Game"
            }
          }
        }
      },
      "Game": {
        "type": "object",
        "required": [
          "id",
          "name",
          "description",
          "url",
          "platforms",
          "genres",
          "icon",
          "stores"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The stable game slug used in its website URL."
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The canonical game page."
          },
          "platforms": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string"
            }
          },
          "genres": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string"
            }
          },
          "icon": {
            "type": "string",
            "format": "uri",
            "description": "The absolute game icon URL."
          },
          "stores": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/Store"
            }
          }
        }
      },
      "Store": {
        "type": "object",
        "required": [
          "name",
          "url"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "The store name, such as App Store or Google Play."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The download URL. For API attribution, Google Play links include utm_source=zorse_api and utm_campaign=game_catalog; App Store links include pt=121532493, ct=zorse_api_game_catalog, and mt=8."
          }
        }
      }
    }
  }
}