{
    "openapi": "3.0.3",
    "info": {
        "title": "Get Countries/States",
        "description": "Get list of countries and states.",
        "version": "1.0.0",
        "contact": {
            "name": "RunSignup API Support",
            "url": "https://runsignup.com/API",
            "email": "info@runsignup.com"
        }
    },
    "servers": [
        {
            "url": "https://api.runsignup.com/rest",
            "description": "Production API Server"
        }
    ],
    "tags": [
        {
            "name": "Basic Info",
            "description": "APIs related to Basic Info"
        }
    ],
    "components": {
        "schemas": {
            "Error": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "string",
                        "description": "Error message"
                    },
                    "details": {
                        "type": "object",
                        "description": "Additional error details",
                        "additionalProperties": true
                    }
                },
                "required": [
                    "error"
                ]
            },
            "BadRequestError": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/Error"
                    },
                    {
                        "description": "Error indicating invalid request parameters or structure"
                    }
                ]
            },
            "UnauthorizedError": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/Error"
                    },
                    {
                        "description": "Error indicating authentication failure"
                    }
                ]
            },
            "ForbiddenError": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/Error"
                    },
                    {
                        "description": "Error indicating the authenticated user lacks required permissions"
                    }
                ]
            },
            "NotFoundError": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/Error"
                    },
                    {
                        "description": "Error indicating the requested resource does not exist"
                    }
                ]
            },
            "ServerError": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/Error"
                    },
                    {
                        "description": "Error indicating an unexpected server-side issue"
                    }
                ]
            },
            "CountriesGetResponse": {
                "type": "object",
                "title": "Countries List",
                "description": "List of countries and their states",
                "properties": {
                    "countries": {
                        "type": "array",
                        "description": "Array of country objects",
                        "items": {
                            "type": "object",
                            "description": "Country object",
                            "example": {
                                "country_code": "US",
                                "country_name": "United States",
                                "country_states": [
                                    {
                                        "state_initials": "AK",
                                        "state_name": "Alaska"
                                    },
                                    {
                                        "state_initials": "AL",
                                        "state_name": "Alabama"
                                    }
                                ]
                            },
                            "properties": {
                                "country_code": {
                                    "type": "string",
                                    "description": "ISO 2-letter country code",
                                    "example": "US"
                                },
                                "country_name": {
                                    "type": "string",
                                    "description": "Full country name",
                                    "example": "United States"
                                },
                                "country_states": {
                                    "type": "array",
                                    "description": "Array of state/province objects",
                                    "example": [
                                        {
                                            "state_initials": "AK",
                                            "state_name": "Alaska"
                                        },
                                        {
                                            "state_initials": "AL",
                                            "state_name": "Alabama"
                                        }
                                    ],
                                    "items": {
                                        "type": "object",
                                        "description": "State/province object",
                                        "properties": {
                                            "state_initials": {
                                                "type": "string",
                                                "description": "State/province code"
                                            },
                                            "state_name": {
                                                "type": "string",
                                                "description": "Full state/province name"
                                            }
                                        },
                                        "required": [
                                            "state_initials",
                                            "state_name"
                                        ]
                                    }
                                }
                            },
                            "required": [
                                "country_code",
                                "country_name"
                            ]
                        }
                    }
                },
                "required": [
                    "countries"
                ],
                "example": {
                    "countries": [
                        {
                            "country_code": "US",
                            "country_name": "United States",
                            "country_states": [
                                {
                                    "state_initials": "AK",
                                    "state_name": "Alaska"
                                },
                                {
                                    "state_initials": "AL",
                                    "state_name": "Alabama"
                                }
                            ]
                        },
                        {
                            "country_code": "CA",
                            "country_name": "Canada",
                            "country_states": [
                                {
                                    "state_initials": "AB",
                                    "state_name": "Alberta"
                                },
                                {
                                    "state_initials": "BC",
                                    "state_name": "British Columbia"
                                }
                            ]
                        }
                    ]
                }
            }
        },
        "securitySchemes": {
            "apiKey": {
                "type": "apiKey",
                "in": "query",
                "name": "api_key",
                "description": "RunSignup API Key"
            },
            "apiSecret": {
                "type": "apiKey",
                "in": "query",
                "name": "api_secret",
                "description": "RunSignup API Secret"
            },
            "apiCaller": {
                "type": "apiKey",
                "in": "query",
                "name": "rsu_api_reg",
                "description": "API caller token (format: <id>.<token>)"
            },
            "apiCallerSecret": {
                "type": "apiKey",
                "in": "header",
                "name": "X-RSU-API-REG-SECRET",
                "description": "API caller password"
            }
        }
    },
    "paths": {
        "/countries": {
            "get": {
                "tags": [
                    "Basic Info"
                ],
                "summary": "Get Countries/States",
                "description": "Get list of countries and states.",
                "operationId": "countries",
                "parameters": [
                    {
                        "name": "rsu_api_reg",
                        "in": "query",
                        "description": "API caller token. If used, you must send the API caller password in an HTTP header named X-RSU-API-REG-SECRET.",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "X-RSU-API-REG-SECRET",
                        "in": "header",
                        "description": "API caller password.",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "format",
                        "in": "query",
                        "description": "Format of response. The default if not sent is `xml`, but `json` is preferred.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "xml",
                                "json",
                                "csv"
                            ],
                            "default": "xml"
                        }
                    }
                ],
                "security": [
                    {
                        "apiKey": [],
                        "apiSecret": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Countries List - List of countries and their states",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/CountriesGetResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BadRequestError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/UnauthorizedError"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ForbiddenError"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/NotFoundError"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ServerError"
                                }
                            }
                        }
                    }
                },
                "x-permissions": [
                    "affiliates",
                    "partners",
                    "race_directors",
                    "timers"
                ]
            }
        }
    }
}