{
    "openapi": "3.1.0",
    "info": {
        "title": "NameGender API",
        "version": "1.0.0",
        "summary": "Name to gender inference, with the evidence behind each answer.",
        "description": "Every endpoint accepts both GET and POST so it can be called from a browser, a shell or a server.\n\n**Credits.** One credit per resolved name, not per request: a bulk call for 100 names costs 100 credits. Credits are checked before any work starts, so a request is never half-processed. Free accounts get 100 credits per day.\n\n**Rate limit.** 1200 requests per minute per API key by default, counted per key rather than per IP so that several customers behind one address do not share a bucket. Every response carries `X-RateLimit-Remaining`; a 429 carries `Retry-After`.\n\n**Errors.** Every failure, at every status code, returns the same body shape. Branch on the machine-readable `error` field, never on `message`: messages are translated into 22 languages and their wording can change.\n\n**Support.** Each response carries a `request_id`, also sent as the `X-Request-Id` header. Quote it in any support request and we can find the exact call in our logs. You may send your own `X-Request-Id` to correlate with your tracing system.\n\n**Data version.** Responses include `data_version`, the name-dataset snapshot that produced the answer. If a result changes between two calls, comparing this field is the first thing to check.",
        "contact": {
            "url": "http://127.0.0.1:8901/docs"
        }
    },
    "servers": [
        {
            "url": "http://127.0.0.1:8901",
            "description": "Production"
        }
    ],
    "security": [
        {
            "bearerAuth": []
        },
        {
            "apiKeyHeader": []
        },
        {
            "apiKeyQuery": []
        }
    ],
    "tags": [
        {
            "name": "Gender",
            "description": "Name, email and username lookups."
        },
        {
            "name": "Account",
            "description": "Credit balance and key status."
        }
    ],
    "paths": {
        "/api": {
            "get": {
                "tags": [
                    "Gender"
                ],
                "summary": "Gender from a name",
                "description": "Pass a full name or a first name. Titles, punctuation and surnames are stripped before lookup; `name` in the response shows what was actually looked up.",
                "operationId": "getName",
                "parameters": [
                    {
                        "name": "name",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "maxLength": 200
                        },
                        "description": "The value to resolve.",
                        "example": "Ayşe Yılmaz"
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "minLength": 2,
                            "maxLength": 2
                        },
                        "description": "ISO-3166 alpha-2 code. Narrows the lookup to one country, which matters for names that flip gender across borders: Andrea is male in Italy and female in Germany. Omit it and the answer is the worldwide aggregate.",
                        "example": "TR"
                    },
                    {
                        "name": "askToAI",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean",
                            "default": false
                        },
                        "description": "Ask a language model when the dataset has no answer. Slower and less certain; the response reports `source: \"llm\"` so you can tell these apart."
                    },
                    {
                        "name": "forceToGenderize",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean",
                            "default": false
                        },
                        "description": "Return the best guess even below the confidence threshold, instead of null. Check `probability` before trusting the result."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resolved. `gender` is null when the name is not recognised — that is a successful answer of \"we do not know\", not an error, and it still costs one credit.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SingleResponse"
                                },
                                "examples": {
                                    "known": {
                                        "$ref": "#/components/examples/known"
                                    },
                                    "unknown": {
                                        "$ref": "#/components/examples/unknown"
                                    },
                                    "fuzzy": {
                                        "$ref": "#/components/examples/fuzzy"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/400"
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "402": {
                        "$ref": "#/components/responses/402"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    },
                    "500": {
                        "$ref": "#/components/responses/500"
                    }
                }
            },
            "post": {
                "tags": [
                    "Gender"
                ],
                "summary": "Gender from a name",
                "description": "Pass a full name or a first name. Titles, punctuation and surnames are stripped before lookup; `name` in the response shows what was actually looked up.",
                "operationId": "postName",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "name"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 200
                                    },
                                    "country": {
                                        "type": "string",
                                        "minLength": 2,
                                        "maxLength": 2
                                    },
                                    "askToAI": {
                                        "type": "boolean",
                                        "default": false
                                    },
                                    "forceToGenderize": {
                                        "type": "boolean",
                                        "default": false
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Resolved. `gender` is null when the name is not recognised — that is a successful answer of \"we do not know\", not an error, and it still costs one credit.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SingleResponse"
                                },
                                "examples": {
                                    "known": {
                                        "$ref": "#/components/examples/known"
                                    },
                                    "unknown": {
                                        "$ref": "#/components/examples/unknown"
                                    },
                                    "fuzzy": {
                                        "$ref": "#/components/examples/fuzzy"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/400"
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "402": {
                        "$ref": "#/components/responses/402"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    },
                    "500": {
                        "$ref": "#/components/responses/500"
                    }
                }
            }
        },
        "/api/bulk": {
            "post": {
                "tags": [
                    "Gender"
                ],
                "summary": "Resolve many names in one request",
                "description": "Exists so that 100 names do not cost 100 HTTP round trips. Names are resolved in a single batch lookup. Credits are checked for the whole batch up front: either every name is processed or none is.",
                "operationId": "bulkGender",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/BulkRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Every name resolved. Results are returned in the order they were sent.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BulkResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "402": {
                        "$ref": "#/components/responses/402"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    },
                    "500": {
                        "$ref": "#/components/responses/500"
                    }
                }
            }
        },
        "/api/email": {
            "get": {
                "tags": [
                    "Gender"
                ],
                "summary": "Gender from an email address",
                "description": "The local part is split on separators and digits, then resolved as a name. `john.doe@example.com` resolves as \"John\".",
                "operationId": "getEmail",
                "parameters": [
                    {
                        "name": "email",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "maxLength": 200
                        },
                        "description": "The value to resolve.",
                        "example": "john.doe@example.com"
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "minLength": 2,
                            "maxLength": 2
                        },
                        "description": "ISO-3166 alpha-2 code. Narrows the lookup to one country, which matters for names that flip gender across borders: Andrea is male in Italy and female in Germany. Omit it and the answer is the worldwide aggregate.",
                        "example": "TR"
                    },
                    {
                        "name": "askToAI",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean",
                            "default": false
                        },
                        "description": "Ask a language model when the dataset has no answer. Slower and less certain; the response reports `source: \"llm\"` so you can tell these apart."
                    },
                    {
                        "name": "forceToGenderize",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean",
                            "default": false
                        },
                        "description": "Return the best guess even below the confidence threshold, instead of null. Check `probability` before trusting the result."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resolved. `gender` is null when the name is not recognised — that is a successful answer of \"we do not know\", not an error, and it still costs one credit.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SingleResponse"
                                },
                                "examples": {
                                    "known": {
                                        "$ref": "#/components/examples/known"
                                    },
                                    "unknown": {
                                        "$ref": "#/components/examples/unknown"
                                    },
                                    "fuzzy": {
                                        "$ref": "#/components/examples/fuzzy"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/400"
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "402": {
                        "$ref": "#/components/responses/402"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    },
                    "500": {
                        "$ref": "#/components/responses/500"
                    }
                }
            },
            "post": {
                "tags": [
                    "Gender"
                ],
                "summary": "Gender from an email address",
                "description": "The local part is split on separators and digits, then resolved as a name. `john.doe@example.com` resolves as \"John\".",
                "operationId": "postEmail",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "email"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "maxLength": 200
                                    },
                                    "country": {
                                        "type": "string",
                                        "minLength": 2,
                                        "maxLength": 2
                                    },
                                    "askToAI": {
                                        "type": "boolean",
                                        "default": false
                                    },
                                    "forceToGenderize": {
                                        "type": "boolean",
                                        "default": false
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Resolved. `gender` is null when the name is not recognised — that is a successful answer of \"we do not know\", not an error, and it still costs one credit.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SingleResponse"
                                },
                                "examples": {
                                    "known": {
                                        "$ref": "#/components/examples/known"
                                    },
                                    "unknown": {
                                        "$ref": "#/components/examples/unknown"
                                    },
                                    "fuzzy": {
                                        "$ref": "#/components/examples/fuzzy"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/400"
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "402": {
                        "$ref": "#/components/responses/402"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    },
                    "500": {
                        "$ref": "#/components/responses/500"
                    }
                }
            }
        },
        "/api/me": {
            "get": {
                "tags": [
                    "Account"
                ],
                "summary": "Credit balance and account status",
                "description": "Costs no credits. Use it to show remaining balance in your own dashboard, or to check a key is live before a large batch.",
                "operationId": "getAccount",
                "responses": {
                    "200": {
                        "description": "Account status.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AccountResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    },
                    "500": {
                        "$ref": "#/components/responses/500"
                    }
                }
            }
        },
        "/api/username": {
            "get": {
                "tags": [
                    "Gender"
                ],
                "summary": "Gender from a username",
                "description": "Digits, separators and common suffixes are stripped before lookup.",
                "operationId": "getUsername",
                "parameters": [
                    {
                        "name": "username",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "maxLength": 200
                        },
                        "description": "The value to resolve.",
                        "example": "jane_doe_92"
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "minLength": 2,
                            "maxLength": 2
                        },
                        "description": "ISO-3166 alpha-2 code. Narrows the lookup to one country, which matters for names that flip gender across borders: Andrea is male in Italy and female in Germany. Omit it and the answer is the worldwide aggregate.",
                        "example": "TR"
                    },
                    {
                        "name": "askToAI",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean",
                            "default": false
                        },
                        "description": "Ask a language model when the dataset has no answer. Slower and less certain; the response reports `source: \"llm\"` so you can tell these apart."
                    },
                    {
                        "name": "forceToGenderize",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean",
                            "default": false
                        },
                        "description": "Return the best guess even below the confidence threshold, instead of null. Check `probability` before trusting the result."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resolved. `gender` is null when the name is not recognised — that is a successful answer of \"we do not know\", not an error, and it still costs one credit.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SingleResponse"
                                },
                                "examples": {
                                    "known": {
                                        "$ref": "#/components/examples/known"
                                    },
                                    "unknown": {
                                        "$ref": "#/components/examples/unknown"
                                    },
                                    "fuzzy": {
                                        "$ref": "#/components/examples/fuzzy"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/400"
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "402": {
                        "$ref": "#/components/responses/402"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    },
                    "500": {
                        "$ref": "#/components/responses/500"
                    }
                }
            },
            "post": {
                "tags": [
                    "Gender"
                ],
                "summary": "Gender from a username",
                "description": "Digits, separators and common suffixes are stripped before lookup.",
                "operationId": "postUsername",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "username"
                                ],
                                "properties": {
                                    "username": {
                                        "type": "string",
                                        "maxLength": 200
                                    },
                                    "country": {
                                        "type": "string",
                                        "minLength": 2,
                                        "maxLength": 2
                                    },
                                    "askToAI": {
                                        "type": "boolean",
                                        "default": false
                                    },
                                    "forceToGenderize": {
                                        "type": "boolean",
                                        "default": false
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Resolved. `gender` is null when the name is not recognised — that is a successful answer of \"we do not know\", not an error, and it still costs one credit.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SingleResponse"
                                },
                                "examples": {
                                    "known": {
                                        "$ref": "#/components/examples/known"
                                    },
                                    "unknown": {
                                        "$ref": "#/components/examples/unknown"
                                    },
                                    "fuzzy": {
                                        "$ref": "#/components/examples/fuzzy"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/400"
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "402": {
                        "$ref": "#/components/responses/402"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    },
                    "500": {
                        "$ref": "#/components/responses/500"
                    }
                }
            }
        },
        "/api/v1/gender": {
            "get": {
                "tags": [
                    "Gender"
                ],
                "summary": "Gender from a name",
                "description": "Versioned alias of `/api`, identical in behaviour. Use the versioned path if you want a guarantee that a future breaking change will land on `/api/v2` and leave this one alone.\n\nPass a full name or a first name. Titles, punctuation and surnames are stripped before lookup; `name` in the response shows what was actually looked up.",
                "operationId": "getNameV1",
                "parameters": [
                    {
                        "name": "name",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "maxLength": 200
                        },
                        "description": "The value to resolve.",
                        "example": "Ayşe Yılmaz"
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "minLength": 2,
                            "maxLength": 2
                        },
                        "description": "ISO-3166 alpha-2 code. Narrows the lookup to one country, which matters for names that flip gender across borders: Andrea is male in Italy and female in Germany. Omit it and the answer is the worldwide aggregate.",
                        "example": "TR"
                    },
                    {
                        "name": "askToAI",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean",
                            "default": false
                        },
                        "description": "Ask a language model when the dataset has no answer. Slower and less certain; the response reports `source: \"llm\"` so you can tell these apart."
                    },
                    {
                        "name": "forceToGenderize",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean",
                            "default": false
                        },
                        "description": "Return the best guess even below the confidence threshold, instead of null. Check `probability` before trusting the result."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resolved. `gender` is null when the name is not recognised — that is a successful answer of \"we do not know\", not an error, and it still costs one credit.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SingleResponse"
                                },
                                "examples": {
                                    "known": {
                                        "$ref": "#/components/examples/known"
                                    },
                                    "unknown": {
                                        "$ref": "#/components/examples/unknown"
                                    },
                                    "fuzzy": {
                                        "$ref": "#/components/examples/fuzzy"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/400"
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "402": {
                        "$ref": "#/components/responses/402"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    },
                    "500": {
                        "$ref": "#/components/responses/500"
                    }
                }
            },
            "post": {
                "tags": [
                    "Gender"
                ],
                "summary": "Gender from a name",
                "description": "Versioned alias of `/api`, identical in behaviour. Use the versioned path if you want a guarantee that a future breaking change will land on `/api/v2` and leave this one alone.\n\nPass a full name or a first name. Titles, punctuation and surnames are stripped before lookup; `name` in the response shows what was actually looked up.",
                "operationId": "postNameV1",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "name"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 200
                                    },
                                    "country": {
                                        "type": "string",
                                        "minLength": 2,
                                        "maxLength": 2
                                    },
                                    "askToAI": {
                                        "type": "boolean",
                                        "default": false
                                    },
                                    "forceToGenderize": {
                                        "type": "boolean",
                                        "default": false
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Resolved. `gender` is null when the name is not recognised — that is a successful answer of \"we do not know\", not an error, and it still costs one credit.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SingleResponse"
                                },
                                "examples": {
                                    "known": {
                                        "$ref": "#/components/examples/known"
                                    },
                                    "unknown": {
                                        "$ref": "#/components/examples/unknown"
                                    },
                                    "fuzzy": {
                                        "$ref": "#/components/examples/fuzzy"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/400"
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "402": {
                        "$ref": "#/components/responses/402"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    },
                    "500": {
                        "$ref": "#/components/responses/500"
                    }
                }
            }
        },
        "/api/v1/gender/bulk": {
            "post": {
                "tags": [
                    "Gender"
                ],
                "summary": "Resolve many names in one request",
                "description": "Versioned alias of `/api/bulk`, identical in behaviour. Use the versioned path if you want a guarantee that a future breaking change will land on `/api/v2` and leave this one alone.\n\nExists so that 100 names do not cost 100 HTTP round trips. Names are resolved in a single batch lookup. Credits are checked for the whole batch up front: either every name is processed or none is.",
                "operationId": "bulkGenderV1",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/BulkRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Every name resolved. Results are returned in the order they were sent.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BulkResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "402": {
                        "$ref": "#/components/responses/402"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    },
                    "500": {
                        "$ref": "#/components/responses/500"
                    }
                }
            }
        },
        "/api/v1/gender/email": {
            "get": {
                "tags": [
                    "Gender"
                ],
                "summary": "Gender from an email address",
                "description": "Versioned alias of `/api/email`, identical in behaviour. Use the versioned path if you want a guarantee that a future breaking change will land on `/api/v2` and leave this one alone.\n\nThe local part is split on separators and digits, then resolved as a name. `john.doe@example.com` resolves as \"John\".",
                "operationId": "getEmailV1",
                "parameters": [
                    {
                        "name": "email",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "maxLength": 200
                        },
                        "description": "The value to resolve.",
                        "example": "john.doe@example.com"
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "minLength": 2,
                            "maxLength": 2
                        },
                        "description": "ISO-3166 alpha-2 code. Narrows the lookup to one country, which matters for names that flip gender across borders: Andrea is male in Italy and female in Germany. Omit it and the answer is the worldwide aggregate.",
                        "example": "TR"
                    },
                    {
                        "name": "askToAI",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean",
                            "default": false
                        },
                        "description": "Ask a language model when the dataset has no answer. Slower and less certain; the response reports `source: \"llm\"` so you can tell these apart."
                    },
                    {
                        "name": "forceToGenderize",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean",
                            "default": false
                        },
                        "description": "Return the best guess even below the confidence threshold, instead of null. Check `probability` before trusting the result."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resolved. `gender` is null when the name is not recognised — that is a successful answer of \"we do not know\", not an error, and it still costs one credit.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SingleResponse"
                                },
                                "examples": {
                                    "known": {
                                        "$ref": "#/components/examples/known"
                                    },
                                    "unknown": {
                                        "$ref": "#/components/examples/unknown"
                                    },
                                    "fuzzy": {
                                        "$ref": "#/components/examples/fuzzy"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/400"
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "402": {
                        "$ref": "#/components/responses/402"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    },
                    "500": {
                        "$ref": "#/components/responses/500"
                    }
                }
            },
            "post": {
                "tags": [
                    "Gender"
                ],
                "summary": "Gender from an email address",
                "description": "Versioned alias of `/api/email`, identical in behaviour. Use the versioned path if you want a guarantee that a future breaking change will land on `/api/v2` and leave this one alone.\n\nThe local part is split on separators and digits, then resolved as a name. `john.doe@example.com` resolves as \"John\".",
                "operationId": "postEmailV1",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "email"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "maxLength": 200
                                    },
                                    "country": {
                                        "type": "string",
                                        "minLength": 2,
                                        "maxLength": 2
                                    },
                                    "askToAI": {
                                        "type": "boolean",
                                        "default": false
                                    },
                                    "forceToGenderize": {
                                        "type": "boolean",
                                        "default": false
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Resolved. `gender` is null when the name is not recognised — that is a successful answer of \"we do not know\", not an error, and it still costs one credit.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SingleResponse"
                                },
                                "examples": {
                                    "known": {
                                        "$ref": "#/components/examples/known"
                                    },
                                    "unknown": {
                                        "$ref": "#/components/examples/unknown"
                                    },
                                    "fuzzy": {
                                        "$ref": "#/components/examples/fuzzy"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/400"
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "402": {
                        "$ref": "#/components/responses/402"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    },
                    "500": {
                        "$ref": "#/components/responses/500"
                    }
                }
            }
        },
        "/api/v1/gender/username": {
            "get": {
                "tags": [
                    "Gender"
                ],
                "summary": "Gender from a username",
                "description": "Versioned alias of `/api/username`, identical in behaviour. Use the versioned path if you want a guarantee that a future breaking change will land on `/api/v2` and leave this one alone.\n\nDigits, separators and common suffixes are stripped before lookup.",
                "operationId": "getUsernameV1",
                "parameters": [
                    {
                        "name": "username",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "maxLength": 200
                        },
                        "description": "The value to resolve.",
                        "example": "jane_doe_92"
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "minLength": 2,
                            "maxLength": 2
                        },
                        "description": "ISO-3166 alpha-2 code. Narrows the lookup to one country, which matters for names that flip gender across borders: Andrea is male in Italy and female in Germany. Omit it and the answer is the worldwide aggregate.",
                        "example": "TR"
                    },
                    {
                        "name": "askToAI",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean",
                            "default": false
                        },
                        "description": "Ask a language model when the dataset has no answer. Slower and less certain; the response reports `source: \"llm\"` so you can tell these apart."
                    },
                    {
                        "name": "forceToGenderize",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean",
                            "default": false
                        },
                        "description": "Return the best guess even below the confidence threshold, instead of null. Check `probability` before trusting the result."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resolved. `gender` is null when the name is not recognised — that is a successful answer of \"we do not know\", not an error, and it still costs one credit.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SingleResponse"
                                },
                                "examples": {
                                    "known": {
                                        "$ref": "#/components/examples/known"
                                    },
                                    "unknown": {
                                        "$ref": "#/components/examples/unknown"
                                    },
                                    "fuzzy": {
                                        "$ref": "#/components/examples/fuzzy"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/400"
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "402": {
                        "$ref": "#/components/responses/402"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    },
                    "500": {
                        "$ref": "#/components/responses/500"
                    }
                }
            },
            "post": {
                "tags": [
                    "Gender"
                ],
                "summary": "Gender from a username",
                "description": "Versioned alias of `/api/username`, identical in behaviour. Use the versioned path if you want a guarantee that a future breaking change will land on `/api/v2` and leave this one alone.\n\nDigits, separators and common suffixes are stripped before lookup.",
                "operationId": "postUsernameV1",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "username"
                                ],
                                "properties": {
                                    "username": {
                                        "type": "string",
                                        "maxLength": 200
                                    },
                                    "country": {
                                        "type": "string",
                                        "minLength": 2,
                                        "maxLength": 2
                                    },
                                    "askToAI": {
                                        "type": "boolean",
                                        "default": false
                                    },
                                    "forceToGenderize": {
                                        "type": "boolean",
                                        "default": false
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Resolved. `gender` is null when the name is not recognised — that is a successful answer of \"we do not know\", not an error, and it still costs one credit.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SingleResponse"
                                },
                                "examples": {
                                    "known": {
                                        "$ref": "#/components/examples/known"
                                    },
                                    "unknown": {
                                        "$ref": "#/components/examples/unknown"
                                    },
                                    "fuzzy": {
                                        "$ref": "#/components/examples/fuzzy"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/400"
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "402": {
                        "$ref": "#/components/responses/402"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    },
                    "500": {
                        "$ref": "#/components/responses/500"
                    }
                }
            }
        },
        "/api/v1/me": {
            "get": {
                "tags": [
                    "Account"
                ],
                "summary": "Credit balance and account status",
                "description": "Versioned alias of `/api/me`, identical in behaviour. Use the versioned path if you want a guarantee that a future breaking change will land on `/api/v2` and leave this one alone.\n\nCosts no credits. Use it to show remaining balance in your own dashboard, or to check a key is live before a large batch.",
                "operationId": "getAccountV1",
                "responses": {
                    "200": {
                        "description": "Account status.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AccountResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    },
                    "500": {
                        "$ref": "#/components/responses/500"
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "Recommended: `Authorization: Bearer <key>`."
            },
            "apiKeyHeader": {
                "type": "apiKey",
                "in": "header",
                "name": "X-Api-Key",
                "description": "Alternative header form."
            },
            "apiKeyQuery": {
                "type": "apiKey",
                "in": "query",
                "name": "key",
                "description": "Query-string form, accepted for drop-in compatibility with existing integrations. Avoid it in production: query strings end up in server and proxy access logs."
            }
        },
        "schemas": {
            "Error": {
                "type": "object",
                "description": "The one error shape. Returned by every endpoint at every failing status code.",
                "required": [
                    "status",
                    "error",
                    "message",
                    "docs"
                ],
                "properties": {
                    "status": {
                        "type": "boolean",
                        "const": false
                    },
                    "error": {
                        "type": "string",
                        "description": "Machine-readable and stable. **Branch on this.** New codes may be added over time, so treat an unrecognised value as a generic failure rather than crashing.",
                        "enum": [
                            "missing_key",
                            "invalid_key",
                            "revoked_key",
                            "blocked",
                            "email_not_verified",
                            "ip_not_allowed",
                            "forbidden",
                            "no_credits",
                            "missing_input",
                            "invalid_input",
                            "too_many_items",
                            "ai_consent_required",
                            "unknown_endpoint",
                            "method_not_allowed",
                            "payload_too_large",
                            "rate_limited",
                            "not_ready",
                            "server_error"
                        ]
                    },
                    "message": {
                        "type": "string",
                        "description": "Human-readable, translated into the caller's language. Wording can change; never parse or compare it."
                    },
                    "request_id": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "Quote this in support requests.",
                        "example": "req_9c1f5b2a7e0d4a13"
                    },
                    "docs": {
                        "type": "string",
                        "format": "uri",
                        "description": "Link to this error in the documentation."
                    },
                    "errors": {
                        "type": "object",
                        "description": "Field-level detail. Present on validation failures only.",
                        "additionalProperties": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        }
                    },
                    "retry_after": {
                        "type": "integer",
                        "description": "Seconds to wait. Present on 429 only, and mirrored in the `Retry-After` header."
                    }
                }
            },
            "GenderResult": {
                "type": "object",
                "required": [
                    "q",
                    "name",
                    "gender",
                    "probability",
                    "total_names",
                    "source"
                ],
                "properties": {
                    "q": {
                        "type": "string",
                        "description": "The input exactly as you sent it."
                    },
                    "name": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "The first name actually looked up, after stripping titles and surnames."
                    },
                    "gender": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "enum": [
                            "male",
                            "female",
                            null
                        ],
                        "description": "null means the dataset has no confident answer. This is not an error."
                    },
                    "probability": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100,
                        "description": "Share of people with this name who have the reported gender. 0 when unknown. Measured against held-out data, answers at 80+ come true about 95% of the time, so this number runs slightly conservative rather than optimistic."
                    },
                    "total_names": {
                        "type": "integer",
                        "description": "How many real people the answer is based on. A probability of 100 from a sample of 3 is weaker than 85 from a sample of 90,000 — read the two fields together. 0 means the source recorded proportions rather than counts."
                    },
                    "country": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "The country the answer came from, when narrowed."
                    },
                    "duration": {
                        "type": "string",
                        "example": "1ms"
                    },
                    "source": {
                        "type": "string",
                        "enum": [
                            "db",
                            "script",
                            "fuzzy",
                            "llm",
                            "cache",
                            "none"
                        ],
                        "description": "How the answer was reached. `db` exact match; `script` matched after transliterating a non-Latin script; `fuzzy` closest spelling; `llm` language model; `none` no answer. Competitors do not tell you this; use it to decide how much to trust a row."
                    },
                    "confidence": {
                        "type": "string",
                        "enum": [
                            "high",
                            "medium",
                            "low",
                            "unverified",
                            "unknown"
                        ],
                        "description": "Sample size bucket: high ≥100 people, medium ≥25, low ≥1, unverified when the source gave proportions instead of counts."
                    },
                    "matched_as": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "For `fuzzy` and `script` sources, the dictionary entry that was actually matched. Always inspect this before accepting a fuzzy result."
                    }
                }
            },
            "Envelope": {
                "type": "object",
                "required": [
                    "status",
                    "used_credits",
                    "remaining_credits"
                ],
                "properties": {
                    "status": {
                        "type": "boolean",
                        "const": true
                    },
                    "used_credits": {
                        "type": "integer"
                    },
                    "remaining_credits": {
                        "type": "integer"
                    },
                    "expires": {
                        "type": "null",
                        "description": "Always null: credits do not expire."
                    },
                    "data_version": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "2026.08"
                    },
                    "request_id": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                }
            },
            "SingleResponse": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/Envelope"
                    },
                    {
                        "$ref": "#/components/schemas/GenderResult"
                    }
                ]
            },
            "BulkRequest": {
                "type": "object",
                "required": [
                    "names"
                ],
                "properties": {
                    "names": {
                        "type": "array",
                        "minItems": 1,
                        "maxItems": 100,
                        "items": {
                            "type": "string",
                            "maxLength": 200
                        }
                    },
                    "country": {
                        "type": "string",
                        "minLength": 2,
                        "maxLength": 2
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "name",
                            "email",
                            "username"
                        ],
                        "default": "name",
                        "description": "How to read the values in `names`."
                    }
                },
                "example": {
                    "names": [
                        "Ayşe",
                        "Mehmet",
                        "Andrea"
                    ],
                    "country": "TR"
                }
            },
            "BulkResponse": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/Envelope"
                    },
                    {
                        "type": "object",
                        "required": [
                            "results",
                            "summary"
                        ],
                        "properties": {
                            "duration": {
                                "type": "string",
                                "example": "12ms"
                            },
                            "summary": {
                                "type": "object",
                                "properties": {
                                    "total": {
                                        "type": "integer"
                                    },
                                    "identified": {
                                        "type": "integer"
                                    },
                                    "unknown": {
                                        "type": "integer"
                                    },
                                    "match_rate": {
                                        "type": "number",
                                        "description": "Percentage identified."
                                    }
                                }
                            },
                            "results": {
                                "type": "array",
                                "description": "Same order as the names you sent.",
                                "items": {
                                    "$ref": "#/components/schemas/GenderResult"
                                }
                            }
                        }
                    }
                ]
            },
            "AccountResponse": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "boolean",
                        "const": true
                    },
                    "email": {
                        "type": "string",
                        "format": "email"
                    },
                    "remaining_credits": {
                        "type": "integer",
                        "description": "Paid balance plus free quota left today."
                    },
                    "purchased_credits": {
                        "type": "integer"
                    },
                    "free_today": {
                        "type": "integer"
                    },
                    "free_daily_limit": {
                        "type": "integer"
                    },
                    "lifetime_requests": {
                        "type": "integer"
                    },
                    "data_version": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                }
            }
        },
        "responses": {
            "401": {
                "description": "No usable API key. Codes: `missing_key`, `invalid_key`, `revoked_key`.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "403": {
                "description": "Key or account is not permitted to make this call. Codes: `blocked`, `email_not_verified`, `ip_not_allowed`, `forbidden`.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "402": {
                "description": "Out of credits. Buy more, or wait for the daily free quota to reset at midnight UTC.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "400": {
                "description": "Bad request. Codes: `missing_input`.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "422": {
                "description": "Input failed validation. `errors` names the offending fields. Codes: `invalid_input`, `too_many_items`, `ai_consent_required`.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "404": {
                "description": "No endpoint at this path. Check the URL against this document.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "405": {
                "description": "Wrong HTTP method for this endpoint.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "413": {
                "description": "Request body too large.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "429": {
                "description": "Rate limit exceeded. Wait `retry_after` seconds. Limits are per API key.",
                "headers": {
                    "Retry-After": {
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Seconds to wait."
                    }
                },
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "503": {
                "description": "The name dataset is being rebuilt. Retry shortly; this is brief and expected during a data refresh.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "500": {
                "description": "Unexpected server error. Nothing was charged. Quote `request_id` if it persists.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            }
        },
        "examples": {
            "known": {
                "summary": "Recognised name",
                "value": {
                    "status": true,
                    "used_credits": 1,
                    "remaining_credits": 4821,
                    "expires": null,
                    "data_version": "2026.08",
                    "request_id": "req_9c1f5b2a7e0d4a13",
                    "q": "Ayşe Yılmaz",
                    "name": "Ayşe",
                    "gender": "female",
                    "country": null,
                    "total_names": 655,
                    "probability": 99,
                    "duration": "1ms",
                    "source": "db",
                    "confidence": "high",
                    "matched_as": null
                }
            },
            "unknown": {
                "summary": "Name not in the dataset — a successful \"we do not know\"",
                "value": {
                    "status": true,
                    "used_credits": 1,
                    "remaining_credits": 4820,
                    "expires": null,
                    "data_version": "2026.08",
                    "request_id": "req_1d7e3c9048ba52f6",
                    "q": "Qzzxvv",
                    "name": "Qzzxvv",
                    "gender": null,
                    "country": null,
                    "total_names": 0,
                    "probability": 0,
                    "duration": "1ms",
                    "source": "none",
                    "confidence": "unknown",
                    "matched_as": null
                }
            },
            "fuzzy": {
                "summary": "Resolved by closest spelling — note the capped probability",
                "value": {
                    "status": true,
                    "used_credits": 1,
                    "remaining_credits": 4819,
                    "expires": null,
                    "data_version": "2026.08",
                    "request_id": "req_44a0be71c3925fd8",
                    "q": "Micheal",
                    "name": "Micheal",
                    "gender": "male",
                    "country": null,
                    "total_names": 152388,
                    "probability": 86,
                    "duration": "2ms",
                    "source": "fuzzy",
                    "confidence": "high",
                    "matched_as": "michael"
                }
            }
        }
    }
}