{
  "openapi": "3.1.0",
  "info": { "title": "who.gen.tr API", "version": "1.0.0", "description": "Single-domain public WHOIS/RDAP lookup. Raw source text requires a lookup:raw project key." },
  "servers": [{ "url": "/" }],
  "paths": {
    "/api/v1/lookup": {
      "get": {
        "summary": "Look up one registrable domain",
        "parameters": [{ "name": "domain", "in": "query", "required": true, "schema": { "type": "string", "example": "example.com" } }, { "name": "includeRaw", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Requires lookup:raw scope; bypasses normalized cache." }],
        "security": [{}, { "projectKey": [] }],
        "responses": {
          "200": { "description": "Registration result, including valid negative results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupResponse" } } } },
          "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/usage": { "get": { "summary": "Project quota use", "security": [{ "projectKey": [] }], "responses": { "200": { "description": "UTC day and month counters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } },
    "/api/v1/capabilities": { "get": { "summary": "Known source and observed support for a TLD", "parameters": [{ "name": "tld", "in": "query", "required": true, "schema": { "type": "string", "example": "tr" } }], "responses": { "200": { "description": "Capability status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilitiesResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } } },
    "/health/live": { "get": { "summary": "Process liveness", "responses": { "200": { "description": "Live" } } } },
    "/health/ready": { "get": { "summary": "Database and schema readiness", "responses": { "200": { "description": "Ready" }, "503": { "description": "Unready" } } } }
  },
  "components": {
    "securitySchemes": { "projectKey": { "type": "http", "scheme": "bearer" } },
    "responses": { "Error": { "description": "Stable machine-readable error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } },
    "schemas": {
      "DateValue": { "type": "object", "required": ["value", "precision"], "properties": { "value": { "type": "string" }, "precision": { "type": "string", "enum": ["date", "second"] } } },
      "LookupResult": { "type": "object", "required": ["domain", "registration", "registrar", "dates", "nameservers", "statuses", "dnssec", "source", "fetchedAt", "warnings"], "properties": {
        "domain": { "type": "object", "required": ["ascii", "unicode"], "properties": { "ascii": { "type": "string" }, "unicode": { "type": "string" } } },
        "registration": { "type": "string", "enum": ["registered", "not_found", "unknown"] }, "registrar": { "type": ["string", "null"] },
        "dates": { "type": "object", "required": ["created", "updated", "expires"], "properties": { "created": { "anyOf": [{ "$ref": "#/components/schemas/DateValue" }, { "type": "null" }] }, "updated": { "anyOf": [{ "$ref": "#/components/schemas/DateValue" }, { "type": "null" }] }, "expires": { "anyOf": [{ "$ref": "#/components/schemas/DateValue" }, { "type": "null" }] } } },
        "nameservers": { "type": "array", "items": { "type": "string" } }, "statuses": { "type": "array", "items": { "type": "string" } }, "dnssec": { "type": ["boolean", "null"] },
        "source": { "type": "object", "required": ["protocol", "authority", "checkedAt"], "properties": { "protocol": { "type": "string", "enum": ["rdap", "whois", "trabis"] }, "authority": { "type": "string" }, "checkedAt": { "type": "string", "format": "date-time" } } },
        "fetchedAt": { "type": "string", "format": "date-time" }, "warnings": { "type": "array", "items": { "type": "string" } }
      } },
      "LookupResponse": { "type": "object", "required": ["requestId", "result", "cache"], "properties": { "requestId": { "type": "string", "format": "uuid" }, "result": { "$ref": "#/components/schemas/LookupResult" }, "cache": { "type": "object", "required": ["hit", "expiresAt"], "properties": { "hit": { "type": "boolean" }, "expiresAt": { "type": ["string", "null"], "format": "date-time" } } }, "raw": { "type": "object", "required": ["contentType", "text"], "properties": { "contentType": { "type": "string" }, "text": { "type": "string" } }, "description": "Only with lookup:raw scope and includeRaw=true" } } },
      "UsagePeriod": { "type": "object", "required": ["limit", "successful", "reserved", "remaining", "periodStart", "periodEnd"], "properties": { "limit": { "type": "integer" }, "successful": { "type": "integer" }, "reserved": { "type": "integer" }, "remaining": { "type": "integer" }, "periodStart": { "type": "string", "format": "date-time" }, "periodEnd": { "type": "string", "format": "date-time" } } },
      "UsageResponse": { "type": "object", "required": ["requestId", "usage"], "properties": { "requestId": { "type": "string", "format": "uuid" }, "usage": { "type": "object", "required": ["day", "month"], "properties": { "day": { "$ref": "#/components/schemas/UsagePeriod" }, "month": { "$ref": "#/components/schemas/UsagePeriod" } } } } },
      "CapabilitiesResponse": { "type": "object", "required": ["requestId", "tld", "known", "source", "status", "testedAt"], "properties": { "requestId": { "type": "string", "format": "uuid" }, "tld": { "type": "string" }, "known": { "type": "boolean" }, "source": { "anyOf": [{ "type": "object", "required": ["protocol", "authority"], "properties": { "protocol": { "type": "string", "enum": ["rdap", "whois", "trabis"] }, "authority": { "type": "string" } } }, { "type": "null" }] }, "status": { "type": "string", "enum": ["supported", "unknown"] }, "testedAt": { "type": ["string", "null"], "format": "date-time" } } },
      "ApiError": { "type": "object", "required": ["requestId", "error"], "properties": { "requestId": { "type": "string", "format": "uuid" }, "error": { "type": "object", "required": ["code", "message", "retryAfterSeconds"], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryAfterSeconds": { "type": ["integer", "null"] } } } } }
    }
  }
}