{"openapi":"3.1.0","info":{"title":"Ai Address Address Normalizer API","description":"Нормализация стандартно записанных адресов по локальному ГАР. Жаргон и произвольные сокращения не поддерживаются. Качество — в quality.status и quality.match_level.","version":"1.0.0"},"paths":{"/health":{"get":{"tags":["System"],"summary":"Health Check","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/ready":{"get":{"tags":["System"],"summary":"Readiness Check","operationId":"readiness_check_ready_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/meta":{"get":{"tags":["System"],"summary":"Get Metadata","operationId":"get_metadata_api_v1_meta_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/internal/reload-db":{"post":{"tags":["System","System Internal"],"summary":"Reload Database","description":"Hot-reloads the GAR database. Closes active SQLite connections and re-opens the file.\nMust be called after Blue-Green deployment to drop connections to the old inode.","operationId":"reload_database_internal_reload_db_post","parameters":[{"name":"x-updater-secret","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Updater-Secret"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/internal/maintenance/{action}":{"post":{"tags":["System"],"summary":"Maintenance","operationId":"maintenance_internal_maintenance__action__post","parameters":[{"name":"action","in":"path","required":true,"schema":{"type":"string","title":"Action"}},{"name":"x-updater-secret","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Updater-Secret"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/tokens":{"get":{"summary":"Interactive Web Portal for Token Management","operationId":"get_token_management_ui_admin_tokens_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/api/v1/demo/examples":{"get":{"tags":["Public examples"],"summary":"Examples","operationId":"examples_api_v1_demo_examples_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/demo/address":{"post":{"tags":["Public examples"],"summary":"Demo","operationId":"demo_api_v1_demo_address_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemoRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/NormalizedRecord"},"type":"array","title":"Response Demo Api V1 Demo Address Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/stats":{"get":{"tags":["Token Administration"],"summary":"Get global API usage statistics","operationId":"get_admin_stats_api_v1_admin_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminStatsResponse"}}}}},"security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/api/v1/admin/monitoring":{"get":{"tags":["Token Administration"],"summary":"Enterprise time-series monitoring and analytics","operationId":"get_monitoring_data_endpoint_api_v1_admin_monitoring_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"timeframe","in":"query","required":false,"schema":{"type":"string","default":"24h","title":"Timeframe"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Monitoring Data Endpoint Api V1 Admin Monitoring Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/tokens":{"get":{"tags":["Token Administration"],"summary":"List all issued API tokens","operationId":"list_tokens_api_v1_admin_tokens_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenListApiResponse"}}}}},"security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}]},"post":{"tags":["Token Administration"],"summary":"Issue a new API token","operationId":"create_token_api_v1_admin_tokens_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenCreateApiRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenCreateApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/api/v1/admin/tokens/{token_id}/revoke":{"put":{"tags":["Token Administration"],"summary":"Deactivate (revoke) an API token","operationId":"revoke_token_put_api_v1_admin_tokens__token_id__revoke_put","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Revoke Token Put Api V1 Admin Tokens  Token Id  Revoke Put"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/tokens/{token_id}/activate":{"put":{"tags":["Token Administration"],"summary":"Restore (activate) an API token","operationId":"activate_token_put_api_v1_admin_tokens__token_id__activate_put","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Activate Token Put Api V1 Admin Tokens  Token Id  Activate Put"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/tokens/{token_id}":{"delete":{"tags":["Token Administration"],"summary":"Permanently delete an API token from database","operationId":"delete_token_endpoint_api_v1_admin_tokens__token_id__delete","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Delete Token Endpoint Api V1 Admin Tokens  Token Id  Delete"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/clean/address":{"post":{"tags":["Address normalization"],"summary":"Normalize 1–50 address strings","operationId":"clean_address_api_v1_clean_address_post","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AddressCleanRequest"},{"items":{"type":"string","maxLength":4096,"minLength":0},"type":"array","maxItems":50,"minItems":1},{"$ref":"#/components/schemas/NormalizedRecord"}],"title":"Payload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/NormalizedRecord"},"type":"array","title":"Response Clean Address Api V1 Clean Address Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/api/v1/clean/batch":{"post":{"tags":["Batch Processing"],"summary":"Submit CSV or Excel file for background address normalization","operationId":"submit_batch_file_api_v1_clean_batch_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_submit_batch_file_api_v1_clean_batch_post"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchJobCreateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/api/v1/clean/batch-list":{"post":{"tags":["Batch Processing"],"summary":"Submit JSON array of addresses for background normalization","operationId":"submit_batch_list_api_v1_clean_batch_list_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchAddressListRequest"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchJobCreateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/api/v1/jobs/{job_id}":{"get":{"tags":["Batch Processing"],"summary":"Get status and progress of a batch normalization job","operationId":"get_job_status_api_v1_jobs__job_id__get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchJobStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs/{job_id}/result":{"get":{"tags":["Batch Processing"],"summary":"Download the completed normalized Excel or CSV file","operationId":"download_job_result_api_v1_jobs__job_id__result_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/updater/status":{"get":{"tags":["Updater"],"summary":"Status","operationId":"status_api_v1_admin_updater_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/api/v1/admin/updater/run":{"post":{"tags":["Updater"],"summary":"Run","operationId":"run_api_v1_admin_updater_run_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunRequest"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/api/v1/admin/updater/logs":{"get":{"tags":["Updater"],"summary":"Logs","operationId":"logs_api_v1_admin_updater_logs_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/api/v1/admin/updater/archives":{"delete":{"tags":["Updater"],"summary":"Archives","operationId":"archives_api_v1_admin_updater_archives_delete","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}]}},"/api/v1/admin/updater/backups":{"delete":{"tags":["Updater"],"summary":"Backups","operationId":"backups_api_v1_admin_updater_backups_delete","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}]}}},"components":{"schemas":{"AddressCleanRequest":{"properties":{"address":{"anyOf":[{"type":"string","maxLength":4096,"minLength":0},{"type":"null"}],"title":"Address"},"addresses":{"anyOf":[{"items":{"type":"string","maxLength":4096,"minLength":0},"type":"array","maxItems":50,"minItems":1},{"type":"null"}],"title":"Addresses"},"allow_llm":{"type":"boolean","title":"Allow Llm","description":"Разрешить отправку неформатных адресов в LLM. Если False, мусорные токены будут игнорироваться быстрым парсером.","default":true}},"additionalProperties":false,"type":"object","title":"AddressCleanRequest"},"AdminStatsResponse":{"properties":{"total_tokens":{"type":"integer","title":"Total Tokens"},"active_tokens":{"type":"integer","title":"Active Tokens"},"total_requests":{"type":"integer","title":"Total Requests"},"total_addresses":{"type":"integer","title":"Total Addresses"},"requests_24h":{"type":"integer","title":"Requests 24H"},"addresses_24h":{"type":"integer","title":"Addresses 24H"},"recent_events":{"items":{"$ref":"#/components/schemas/UsageEventSchema"},"type":"array","title":"Recent Events"},"recent_errors":{"items":{"$ref":"#/components/schemas/ErrorEventSchema"},"type":"array","title":"Recent Errors"}},"type":"object","required":["total_tokens","active_tokens","total_requests","total_addresses","requests_24h","addresses_24h","recent_events","recent_errors"],"title":"AdminStatsResponse"},"BatchAddressListRequest":{"properties":{"addresses":{"items":{"type":"string","maxLength":4096,"minLength":0},"type":"array","maxItems":5000,"minItems":1,"title":"Addresses"},"filename":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Filename","description":"Output filename","default":"batch_addresses.xlsx"}},"additionalProperties":false,"type":"object","required":["addresses"],"title":"BatchAddressListRequest"},"BatchJobCreateResponse":{"properties":{"job_id":{"type":"string","title":"Job Id","description":"Unique batch job identifier"},"status":{"type":"string","title":"Status","description":"Initial job status (queued, processing)","default":"queued"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename","description":"Uploaded file name"},"total_rows":{"type":"integer","title":"Total Rows","description":"Detected number of records to process"},"created_at":{"type":"string","title":"Created At","description":"ISO creation timestamp"}},"type":"object","required":["job_id","total_rows","created_at"],"title":"BatchJobCreateResponse"},"BatchJobStatusResponse":{"properties":{"job_id":{"type":"string","title":"Job Id","description":"Batch job identifier"},"status":{"type":"string","title":"Status","description":"Current status: queued, processing, completed, failed"},"progress_pct":{"type":"number","title":"Progress Pct","description":"Percentage complete (0.0 to 100.0)"},"processed_rows":{"type":"integer","title":"Processed Rows","description":"Number of rows processed so far"},"total_rows":{"type":"integer","title":"Total Rows","description":"Total rows in batch"},"created_at":{"type":"string","title":"Created At","description":"Job start time"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At","description":"Job completion time"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if failed"},"result_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result Url","description":"Download URL if completed"}},"type":"object","required":["job_id","status","progress_pct","processed_rows","total_rows","created_at"],"title":"BatchJobStatusResponse"},"Body_submit_batch_file_api_v1_clean_batch_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_submit_batch_file_api_v1_clean_batch_post"},"DemoRequest":{"properties":{"example_id":{"anyOf":[{"type":"string","enum":["house","partial","street","city"]},{"type":"null"}],"title":"Example Id"},"address":{"anyOf":[{"type":"string","maxLength":4096,"minLength":0},{"type":"null"}],"title":"Address"},"allow_llm":{"type":"boolean","title":"Allow Llm","default":false}},"additionalProperties":false,"type":"object","title":"DemoRequest"},"ErrorEventSchema":{"properties":{"timestamp":{"type":"string","title":"Timestamp"},"endpoint":{"type":"string","title":"Endpoint"},"status_code":{"type":"integer","title":"Status Code"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"}},"type":"object","required":["timestamp","endpoint","status_code","error_message"],"title":"ErrorEventSchema"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"NormalizedRecord":{"properties":{"source":{"type":"string","title":"Source"},"result":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result"},"quality":{"$ref":"#/components/schemas/QualityDiagnostic"}},"additionalProperties":true,"type":"object","required":["source","quality"],"title":"NormalizedRecord"},"QualityDiagnostic":{"properties":{"status":{"type":"string","title":"Status"},"match_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Match Level"},"unverified_components":{"items":{"type":"string"},"type":"array","title":"Unverified Components"},"issues":{"items":{},"type":"array","title":"Issues"}},"additionalProperties":true,"type":"object","required":["status"],"title":"QualityDiagnostic"},"RunRequest":{"properties":{"mode":{"type":"string","enum":["prepare","promote","rollback"],"title":"Mode"}},"type":"object","required":["mode"],"title":"RunRequest"},"TokenCreateApiRequest":{"properties":{"client_name":{"type":"string","maxLength":120,"minLength":2,"pattern":".*\\S.*","title":"Client Name","description":"Client or organization name"},"days_valid":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Days Valid","description":"Validity period in days (1–365)","default":30},"scopes":{"items":{"type":"string","enum":["clean:single","clean:batch"]},"type":"array","maxItems":2,"minItems":1,"title":"Scopes","description":"Client permissions","default":["clean:single","clean:batch"]},"rate_limit_rpm":{"type":"integer","maximum":6000.0,"minimum":1.0,"title":"Rate Limit Rpm","description":"Allowed requests per minute","default":60},"max_batch_size":{"type":"integer","maximum":5000.0,"minimum":1.0,"title":"Max Batch Size","description":"Max addresses allowed in one batch file","default":5000},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description","description":"Note or description"}},"type":"object","required":["client_name"],"title":"TokenCreateApiRequest"},"TokenCreateApiResponse":{"properties":{"token_id":{"type":"string","title":"Token Id"},"client_name":{"type":"string","title":"Client Name"},"token_prefix":{"type":"string","title":"Token Prefix"},"raw_token":{"type":"string","title":"Raw Token"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"rate_limit_rpm":{"type":"integer","title":"Rate Limit Rpm"},"max_batch_size":{"type":"integer","title":"Max Batch Size"},"created_at":{"type":"string","title":"Created At"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","required":["token_id","client_name","token_prefix","raw_token","scopes","rate_limit_rpm","max_batch_size","created_at","expires_at"],"title":"TokenCreateApiResponse"},"TokenInfoSchema":{"properties":{"token_id":{"type":"string","title":"Token Id"},"client_name":{"type":"string","title":"Client Name"},"token_prefix":{"type":"string","title":"Token Prefix"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"rate_limit_rpm":{"type":"integer","title":"Rate Limit Rpm"},"max_batch_size":{"type":"integer","title":"Max Batch Size"},"is_active":{"type":"boolean","title":"Is Active"},"created_at":{"type":"string","title":"Created At"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"last_used_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used At"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"request_count":{"type":"integer","title":"Request Count","default":0},"addresses_count":{"type":"integer","title":"Addresses Count","default":0}},"type":"object","required":["token_id","client_name","token_prefix","scopes","rate_limit_rpm","max_batch_size","is_active","created_at","expires_at","last_used_at","description"],"title":"TokenInfoSchema"},"TokenListApiResponse":{"properties":{"tokens":{"items":{"$ref":"#/components/schemas/TokenInfoSchema"},"type":"array","title":"Tokens"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["tokens","total"],"title":"TokenListApiResponse"},"UsageEventSchema":{"properties":{"id":{"type":"integer","title":"Id"},"token_id":{"type":"string","title":"Token Id"},"client_name":{"type":"string","title":"Client Name"},"token_prefix":{"type":"string","title":"Token Prefix"},"endpoint":{"type":"string","title":"Endpoint"},"addresses_count":{"type":"integer","title":"Addresses Count"},"status_code":{"type":"integer","title":"Status Code"},"timestamp":{"type":"string","title":"Timestamp"}},"type":"object","required":["id","token_id","client_name","token_prefix","endpoint","addresses_count","status_code","timestamp"],"title":"UsageEventSchema"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"},"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}}}}