{ "openapi": "3.1.0", "info": { "title": "ipdb API", "version": "0.3.0", "description": "Multi-source IP risk intelligence. Bearer API keys; 600 requests/minute/key by default. Unknown does not mean safe. Source trust is assigned by administrators; reporters cannot choose it." }, "security": [ { "bearerAuth": [] } ], "paths": { "/healthz": { "get": { "operationId": "get_healthz", "summary": "Database readiness", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/openapi.json": { "get": { "operationId": "get_openapi.json", "summary": "OpenAPI contract", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/asn/status": { "get": { "operationId": "get_v1_asn_status", "summary": "ASN dataset synchronization status", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ASNDataset" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/asn/sync": { "post": { "operationId": "post_v1_asn_sync", "summary": "Queue ASN snapshot synchronization (admin)", "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ASNDataset" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/asns/{asn}": { "get": { "operationId": "get_v1_asns_asn", "summary": "ASN metadata and stored active evidence counts", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ASNDetail" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "asn", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 4294967295 } } ] } }, "/v1/me": { "get": { "operationId": "get_v1_me", "summary": "Current API key identity", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Principal" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/stats": { "get": { "operationId": "get_v1_stats", "summary": "Global aggregates, 5-second cache; 14 UTC days and top 20 IPs", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stats" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/feed-presets": { "get": { "operationId": "get_v1_feed-presets", "summary": "Public feed catalog and licensing", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedPresets" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/feed-presets/{slug}/sources": { "post": { "operationId": "post_v1_feed-presets_slug_sources", "summary": "Add preset idempotently (admin); existing source returns 200", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Source" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Source" } } } } }, "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ] } }, "/v1/categories": { "get": { "operationId": "get_v1_categories", "summary": "List supported categories", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Categories" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sources": { "get": { "operationId": "get_v1_sources", "summary": "List sources (admin)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourcePage" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } ] }, "post": { "operationId": "post_v1_sources", "summary": "Create source (admin)", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Source" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceInput" } } } } } }, "/v1/sources/{id}": { "get": { "operationId": "get_v1_sources_id", "summary": "Get source (admin)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Source" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "put": { "operationId": "put_v1_sources_id", "summary": "Replace source configuration (admin)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Source" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceInput" } } } } } }, "/v1/keys": { "get": { "operationId": "get_v1_keys", "summary": "List key metadata (admin)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyPage" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } ] }, "post": { "operationId": "post_v1_keys", "summary": "Create key; token returned once (admin)", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedKey" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyInput" } } } } } }, "/v1/keys/{id}": { "delete": { "operationId": "delete_v1_keys_id", "summary": "Revoke key; preserve current key and last admin (admin)", "responses": { "204": { "description": "Success" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/sources/{id}/reports": { "post": { "operationId": "post_v1_sources_id_reports", "summary": "Report event (admin or bound reporter)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestResult" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportInput" } } } } } }, "/v1/sources/{id}/reports/batch": { "post": { "operationId": "post_v1_sources_id_reports_batch", "summary": "Atomic batch; duplicate events are ignored", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestResult" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } } } }, "/v1/reports/{id}": { "delete": { "operationId": "delete_v1_reports_id", "summary": "Retract event (admin or bound reporter)", "responses": { "204": { "description": "Success" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/ips/{ip}": { "get": { "operationId": "get_v1_ips_ip", "summary": "Calculate IP risk; no evidence means unknown", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reputation" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "ip", "required": true, "schema": { "type": "string" } } ] } }, "/v1/ips/{ip}/reports": { "get": { "operationId": "get_v1_ips_ip_reports", "summary": "Evidence history (admin or own-source reporter; readers forbidden)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportPage" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "ip", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } }, { "in": "query", "name": "source_id", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "category", "schema": { "type": "string", "enum": [ "spam", "brute_force", "malware", "scanner", "phishing", "botnet", "other" ] } }, { "in": "query", "name": "since", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "include_retracted", "schema": { "type": "boolean", "default": false } } ] } }, "/v1/sources/{id}/sync": { "post": { "operationId": "post_v1_sources_id_sync", "summary": "Queue feed sync; active job reused (admin)", "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncJob" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/sources/{id}/sync-jobs": { "get": { "operationId": "get_v1_sources_id_sync-jobs", "summary": "Source sync history (admin)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncJobPage" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } ] } }, "/v1/sync-jobs/{id}": { "get": { "operationId": "get_v1_sync-jobs_id", "summary": "Sync job status (admin)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncJob" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload exceeds 4 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/asns/{asn}/radar": { "get": { "summary": "Cloudflare Radar ASN Bot/Human traffic (7d, persistent 1h cache)", "parameters": [ { "name": "asn", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 4294967295 } } ], "responses": { "200": { "description": "status available with bot_percent, human_percent, start_time, end_time, cached_at, is_stale; otherwise not_configured, refreshing or unavailable" }, "401": { "description": "Unauthorized" } } } }, "/v1/ips/{ip}/summary": { "get": { "operationId": "get_ip_summary", "summary": "Compact IP lookup for ip.network", "description": "Bearer authentication. Reuses the persistent ASN Radar cache (1 hour). No active risk evidence yields risk_score=null. Unavailable or stale Radar data yields traffic=null. IPv4 and IPv6 supported.", "parameters": [ { "name": "ip", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Only ASN, IP risk score and ASN traffic percentages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpSummary" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "SourceInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "trust": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.5 }, "enabled": { "type": "boolean", "default": true }, "feed_url": { "anyOf": [ { "type": "string", "format": "uri", "description": "HTTPS public feed, port 443, no credentials or redirects" }, { "type": "null" } ] }, "sync_interval_seconds": { "type": "integer", "minimum": 60, "default": 3600 }, "feed_format": { "type": "string", "enum": [ "json", "ip_list" ], "default": "json" }, "feed_category": { "type": "string", "enum": [ "spam", "brute_force", "malware", "scanner", "phishing", "botnet", "other" ], "default": "other" }, "feed_severity": { "type": "integer", "minimum": 1, "maximum": 5, "default": 3 }, "feed_confidence": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.8 }, "feed_ttl_seconds": { "type": "integer", "minimum": 60, "maximum": 2678400, "default": 172800 }, "source_group": { "anyOf": [ { "type": "string", "maxLength": 100, "description": "Sources sharing an upstream use one strongest group contribution" }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false }, "Source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "trust": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.5 }, "enabled": { "type": "boolean", "default": true }, "feed_url": { "anyOf": [ { "type": "string", "format": "uri", "description": "HTTPS public feed, port 443, no credentials or redirects" }, { "type": "null" } ] }, "sync_interval_seconds": { "type": "integer", "minimum": 60, "default": 3600 }, "feed_format": { "type": "string", "enum": [ "json", "ip_list" ], "default": "json" }, "feed_category": { "type": "string", "enum": [ "spam", "brute_force", "malware", "scanner", "phishing", "botnet", "other" ], "default": "other" }, "feed_severity": { "type": "integer", "minimum": 1, "maximum": 5, "default": 3 }, "feed_confidence": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.8 }, "feed_ttl_seconds": { "type": "integer", "minimum": 60, "maximum": 2678400, "default": 172800 }, "source_group": { "anyOf": [ { "type": "string", "maxLength": 100, "description": "Sources sharing an upstream use one strongest group contribution" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid" }, "next_sync_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "preset_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "config_version": { "type": "integer" } }, "required": [ "name", "trust", "enabled", "feed_url", "sync_interval_seconds", "feed_format", "feed_category", "feed_severity", "feed_confidence", "feed_ttl_seconds", "source_group", "id", "next_sync_at", "created_at", "preset_slug", "config_version" ], "additionalProperties": false }, "ReportInput": { "type": "object", "properties": { "external_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Immutable event ID, unique within a source. Replays return the existing ID, without updating evidence." }, "ip": { "type": "string", "description": "Public IPv4 or IPv6 host address. IPv4-mapped IPv6 is normalized." }, "category": { "type": "string", "enum": [ "spam", "brute_force", "malware", "scanner", "phishing", "botnet", "other" ] }, "severity": { "type": "integer", "minimum": 1, "maximum": 5 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "observed_at": { "type": "string", "format": "date-time", "description": "Within the past 365 days; future timestamps are rejected" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "After observed_at, at most 365 days later; default observed_at + 90 days" }, { "type": "null" } ] }, "description": { "type": "string", "maxLength": 2000, "default": "" } }, "required": [ "external_id", "ip", "category", "severity", "confidence", "observed_at" ], "additionalProperties": false }, "Report": { "type": "object", "properties": { "external_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Immutable event ID, unique within a source. Replays return the existing ID, without updating evidence." }, "ip": { "type": "string", "description": "Public IPv4 or IPv6 host address. IPv4-mapped IPv6 is normalized." }, "category": { "type": "string", "enum": [ "spam", "brute_force", "malware", "scanner", "phishing", "botnet", "other" ] }, "severity": { "type": "integer", "minimum": 1, "maximum": 5 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "observed_at": { "type": "string", "format": "date-time", "description": "Within the past 365 days; future timestamps are rejected" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "After observed_at, at most 365 days later; default observed_at + 90 days" }, { "type": "null" } ] }, "description": { "type": "string", "maxLength": 2000, "default": "" }, "id": { "type": "string", "format": "uuid" }, "source_id": { "type": "string", "format": "uuid" }, "retracted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "feed_managed": { "type": "boolean" } }, "required": [ "external_id", "ip", "category", "severity", "confidence", "observed_at", "expires_at", "description", "id", "source_id", "retracted_at", "created_at", "feed_managed" ], "additionalProperties": false }, "Batch": { "type": "object", "properties": { "reports": { "type": "array", "items": { "$ref": "#/components/schemas/ReportInput" }, "minItems": 1, "maxItems": 1000 } }, "required": [ "reports" ], "additionalProperties": false }, "IngestResult": { "type": "object", "properties": { "accepted": { "type": "integer" }, "duplicates": { "type": "integer" }, "report_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "accepted", "duplicates", "report_ids" ], "additionalProperties": false }, "KeyInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "role": { "type": "string", "enum": [ "admin", "reader", "reporter" ] }, "source_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "name", "role" ], "additionalProperties": false }, "CreatedKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "token": { "type": "string" } }, "required": [ "id", "token" ], "additionalProperties": false }, "Key": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "type": "string" }, "source_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "role", "source_id", "revoked_at", "created_at" ], "additionalProperties": false }, "SyncJob": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed" ] }, "attempts": { "type": "integer" }, "available_at": { "type": "string", "format": "date-time" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "accepted": { "type": "integer" }, "duplicates": { "type": "integer" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "source_id", "status", "attempts", "available_at", "started_at", "finished_at", "accepted", "duplicates", "error", "created_at" ], "additionalProperties": false }, "Contribution": { "type": "object", "properties": { "source_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "trust": { "type": "number" }, "evidence": { "type": "number" }, "weighted_risk": { "type": "number" }, "source_group": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reports": { "type": "integer" } }, "required": [ "source_id", "name", "trust", "evidence", "weighted_risk", "source_group", "reports" ], "additionalProperties": false }, "ASNBrief": { "type": "object", "properties": { "number": { "type": "integer", "minimum": 1, "maximum": 4294967295 }, "organization": { "type": "string" }, "country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "number", "organization", "country_code" ], "additionalProperties": false }, "ASNInfo": { "type": "object", "properties": { "number": { "type": "integer", "minimum": 1, "maximum": 4294967295 }, "organization": { "type": "string" }, "country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "range_start": { "type": "string" }, "range_end": { "type": "string" }, "network": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "upstream_updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "provider": { "type": "string" }, "is_stale": { "type": "boolean" } }, "required": [ "number", "organization", "country_code", "range_start", "range_end", "network", "updated_at", "upstream_updated_at", "provider", "is_stale" ], "additionalProperties": false }, "ASNDataset": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "sync_interval_seconds": { "type": "integer" }, "next_sync_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed" ] }, "attempts": { "type": "integer" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "last_success_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "upstream_updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "range_count": { "type": "integer" }, "is_stale": { "type": "boolean" } }, "required": [ "enabled", "sync_interval_seconds", "next_sync_at", "status", "attempts", "started_at", "finished_at", "last_success_at", "upstream_updated_at", "last_error", "range_count", "is_stale" ], "additionalProperties": false }, "ASNStat": { "type": "object", "properties": { "number": { "type": "integer", "minimum": 1, "maximum": 4294967295 }, "organization": { "type": "string" }, "country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ips": { "type": "integer" }, "high_risk_ips": { "type": "integer" }, "active_reports": { "type": "integer" } }, "required": [ "number", "organization", "country_code", "ips", "high_risk_ips", "active_reports" ], "additionalProperties": false }, "ASNDetail": { "type": "object", "properties": { "number": { "type": "integer", "minimum": 1, "maximum": 4294967295 }, "organization": { "type": "string" }, "country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "range_count": { "type": "integer" }, "active_ips": { "type": "integer" }, "active_reports": { "type": "integer" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "number", "organization", "country_code", "range_count", "active_ips", "active_reports", "updated_at" ], "additionalProperties": false }, "Reputation": { "type": "object", "properties": { "asn": { "anyOf": [ { "$ref": "#/components/schemas/ASNInfo" }, { "type": "null" } ] }, "ip": { "type": "string" }, "risk_score": { "type": "integer", "minimum": 0, "maximum": 100 }, "level": { "type": "string", "enum": [ "unknown", "low", "medium", "high" ] }, "has_evidence": { "type": "boolean" }, "active_reports": { "type": "integer" }, "source_count": { "type": "integer" }, "last_seen": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "algorithm": { "type": "string" }, "calculated_at": { "type": "string", "format": "date-time" }, "contributions": { "type": "array", "items": { "$ref": "#/components/schemas/Contribution" } } }, "required": [ "asn", "ip", "risk_score", "level", "has_evidence", "active_reports", "source_count", "last_seen", "algorithm", "calculated_at", "contributions" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "additionalProperties": false }, "Health": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ], "additionalProperties": false }, "Categories": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "string" } } }, "required": [ "categories" ], "additionalProperties": false }, "SourcePage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "items", "limit", "offset" ], "additionalProperties": false }, "KeyPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Key" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "items", "limit", "offset" ], "additionalProperties": false }, "ReportPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Report" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "items", "limit", "offset" ], "additionalProperties": false }, "SyncJobPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SyncJob" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "items", "limit", "offset" ], "additionalProperties": false }, "Principal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "admin", "reader", "reporter" ] }, "source_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "id", "role", "source_id" ], "additionalProperties": false }, "FeedPreset": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "homepage": { "type": "string" }, "license": { "type": "string" }, "license_url": { "type": "string" }, "interval_seconds": { "type": "integer" }, "ttl_seconds": { "type": "integer" }, "trust": { "type": "number" }, "category": { "type": "string" }, "severity": { "type": "integer" }, "confidence": { "type": "number" } }, "required": [ "slug", "name", "url", "homepage", "license", "license_url", "interval_seconds", "ttl_seconds", "trust", "category", "severity", "confidence" ], "additionalProperties": false }, "FeedPresets": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FeedPreset" } } }, "required": [ "items" ], "additionalProperties": false }, "StatTotals": { "type": "object", "properties": { "reports": { "type": "integer" }, "active_reports": { "type": "integer" }, "ips": { "type": "integer" }, "high_risk_ips": { "type": "integer" }, "sources": { "type": "integer" }, "enabled_sources": { "type": "integer" }, "reports_24h": { "type": "integer" }, "pending_syncs": { "type": "integer" } }, "required": [ "reports", "active_reports", "ips", "high_risk_ips", "sources", "enabled_sources", "reports_24h", "pending_syncs" ], "additionalProperties": false }, "RankedIP": { "type": "object", "properties": { "asn": { "anyOf": [ { "$ref": "#/components/schemas/ASNBrief" }, { "type": "null" } ] }, "ip": { "type": "string" }, "risk_score": { "type": "integer" }, "active_reports": { "type": "integer" }, "source_count": { "type": "integer" }, "last_seen": { "type": "string", "format": "date-time" } }, "required": [ "asn", "ip", "risk_score", "active_reports", "source_count", "last_seen" ], "additionalProperties": false }, "CategoryCount": { "type": "object", "properties": { "category": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "category", "count" ], "additionalProperties": false }, "DailyCount": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "count": { "type": "integer" } }, "required": [ "date", "count" ], "additionalProperties": false }, "SourceHealth": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "trust": { "type": "number" }, "enabled": { "type": "boolean" }, "feed_format": { "type": "string" }, "preset_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "next_sync_at": { "type": "string", "format": "date-time" }, "sync_interval_seconds": { "type": "integer" }, "active_reports": { "type": "integer" }, "sync_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_sync_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "sync_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "trust", "enabled", "feed_format", "preset_slug", "next_sync_at", "sync_interval_seconds", "active_reports", "sync_status", "last_sync_at", "sync_error" ], "additionalProperties": false }, "Stats": { "type": "object", "properties": { "top_asns": { "type": "array", "items": { "$ref": "#/components/schemas/ASNStat" } }, "asn_dataset": { "$ref": "#/components/schemas/ASNDataset" }, "as_of": { "type": "string", "format": "date-time" }, "algorithm": { "type": "string" }, "totals": { "$ref": "#/components/schemas/StatTotals" }, "top_ips": { "type": "array", "items": { "$ref": "#/components/schemas/RankedIP" } }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryCount" } }, "daily": { "type": "array", "items": { "$ref": "#/components/schemas/DailyCount" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SourceHealth" }, "maxItems": 100 } }, "required": [ "top_asns", "asn_dataset", "as_of", "algorithm", "totals", "top_ips", "categories", "daily", "sources" ], "additionalProperties": false }, "IpSummary": { "type": "object", "additionalProperties": false, "properties": { "asn": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "number": { "type": "integer", "minimum": 1, "maximum": 4294967295 }, "organization": { "type": "string" }, "country_code": { "type": [ "string", "null" ] }, "network": { "type": "string" } }, "required": [ "number", "organization", "country_code", "network" ] }, "risk_score": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100, "description": "IP risk score; null when no active evidence exists." }, "traffic": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "bot_percent": { "type": "number", "minimum": 0, "maximum": 100 }, "human_percent": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "bot_percent", "human_percent" ], "description": "ASN HTTP traffic over the past 7 days; null when unavailable or cache is stale. Percentages use 0..100." } }, "required": [ "asn", "risk_score", "traffic" ] } } } }