{"openapi":"3.1.0","info":{"title":"SudnoKontrol AI Public API","description":"Read-only, LLM-friendly access to Ukrainian national vessel registry data (Державний судновий реєстр України + Суднова книга України). Open, IP-rate-limited (300 req / 15 min). Use /tools to discover function-calling tool definitions.","version":"1.0.1","contact":{"support":"https://sk.ukrfish.org/support"}},"servers":[{"url":"https://api.sk.ukrfish.org","description":"Production API"}],"tags":[{"name":"AI","description":"LLM-facing registry access endpoints"}],"paths":{"/api/ai/meta":{"get":{"tags":["AI"],"summary":"Dataset metadata","description":"Describes available data sources, import dates, counts, and example queries so an agent knows what data exists and how fresh it is.","operationId":"getAIMeta","responses":{"200":{"description":"Dataset metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaResponse"}}}}}}},"/api/ai/tools":{"get":{"tags":["AI"],"summary":"Agent tool definitions","description":"Returns function-calling tool definitions (name, description, JSON Schema parameters and response schema) for wiring the API into an LLM agent's tool config.","operationId":"getAITools","responses":{"200":{"description":"Array of tool definitions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ToolDefinition"}}}}}}}},"/api/ai/openapi.json":{"get":{"tags":["AI"],"summary":"OpenAPI specification","description":"The full OpenAPI 3.1 document describing every /api/ai endpoint.","operationId":"getAIOpenApi","responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/ai/registry/search":{"get":{"tags":["AI"],"summary":"Search vessel registries","description":"Search Ukrainian vessel registries by free-text query and structured filters. Returns deterministic ordering: exact registration-number matches first.","operationId":"searchRegistry","parameters":[{"name":"q","in":"query","required":false,"description":"Free-text search matching registration number, vessel name, or owner name. Minimum 2 characters. Accepts Latin or Cyrillic.","schema":{"type":"string","minLength":2}},{"name":"vessel_type","in":"query","required":false,"description":"Partial match on vessel type (e.g. земснаряд).","schema":{"type":"string"}},{"name":"build_year_min","in":"query","required":false,"description":"Inclusive minimum build year.","schema":{"type":"integer"}},{"name":"build_year_max","in":"query","required":false,"description":"Inclusive maximum build year.","schema":{"type":"integer"}},{"name":"home_port","in":"query","required":false,"description":"Partial match on home port.","schema":{"type":"string"}},{"name":"source","in":"query","required":false,"description":"Which national dataset to search.","schema":{"$ref":"#/components/schemas/Source"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of results per page.","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"offset","in":"query","required":false,"description":"Number of results to skip for pagination.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Paginated search results","headers":{"X-AI-Search-Count":{"description":"Total number of matching records.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/ai/registry/lookup/{registrationNumber}":{"get":{"tags":["AI"],"summary":"Look up vessel by registration number","description":"Returns a single vessel by exact registration number. Separator and case variants (-, ., space) are normalized. Latin script also accepted.","operationId":"lookupRegistry","parameters":[{"name":"registrationNumber","in":"path","required":true,"description":"Registration number (e.g. УПС-0129).","schema":{"type":"string","minLength":3}}],"responses":{"200":{"description":"The matched vessel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistryResult"}}}},"400":{"description":"Invalid registration number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Vessel not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/ai/stats":{"get":{"tags":["AI"],"summary":"Registry statistics","description":"Aggregate public counts for answering 'how many vessels' questions.","operationId":"getAIStats","responses":{"200":{"description":"Aggregate statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}}}}}},"components":{"schemas":{"Source":{"type":"string","enum":["registry","book","both"],"default":"both"},"RegistrationMatch":{"type":"object","properties":{"field":{"type":"string","enum":["registration_number","name","owner_name","vessel_type","home_port","fuzzy_name"]},"score":{"type":"number","minimum":0,"maximum":1}}},"RegistryResult":{"type":"object","properties":{"registration_number":{"type":"string"},"name":{"type":"string"},"vessel_type":{"type":["string","null"]},"owner_name":{"type":["string","null"]},"owner_address":{"type":["string","null"]},"build_year":{"type":["integer","null"]},"home_port":{"type":["string","null"]},"tonnage":{"type":["number","null"]},"source":{"type":"string","enum":["registry","book"]},"source_name":{"type":"string"},"match":{"$ref":"#/components/schemas/RegistrationMatch"}},"required":["registration_number","name","source","source_name","match"]},"SearchResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RegistryResult"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["items","total","limit","offset"]},"MetaResponse":{"type":"object","properties":{"api":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"}}},"data_sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"name":{"type":"string"},"imported_at":{"type":["string","null"]},"record_count":{"type":"integer"}}}},"example_queries":{"type":"array","items":{"type":"string"}}}},"StatsResponse":{"type":"object","properties":{"total_vessels":{"type":"integer"},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"name":{"type":"string"},"count":{"type":"integer"}}}}}},"ToolDefinition":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"parameters":{"$ref":"#/components/schemas/SearchParameters"},"responseSchema":{"type":"object"}},"required":["name","description","parameters","responseSchema"]},"SearchParameters":{"type":"object","properties":{"type":{"type":"string","enum":["object"]},"properties":{"type":"object","properties":{"q":{"type":"string","minLength":2},"vessel_type":{"type":"string"},"build_year_min":{"type":"integer"},"build_year_max":{"type":"integer"},"home_port":{"type":"string"},"source":{"$ref":"#/components/schemas/Source"},"limit":{"type":"integer","minimum":1,"maximum":50},"offset":{"type":"integer","minimum":0}}}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["invalid_parameter","vessel_not_found","internal_error"]},"detail":{"type":"object"}},"required":["error"]}}}}