{ "openapi": "3.1.0", "info": { "title": "ELLIO Public API", "version": "1.0.0", "description": "Public API for ELLIO Platform\n\n## Authentication\n\nAll API endpoints require authentication using an API key. You can provide the key in one of two ways:\n\n1. **Header (Recommended):** Include your API key in the `X-API-Key` header\n2. **Query Parameter:** Include your API key as the `apikey` query parameter\n\n## API Key Permissions\n\nAPI keys have two permission levels:\n\n- **`read`** - Can view rulesets, rules, and business services data\n- **`read_write`** - Can perform all operations including creating, updating, and deleting rules\n\nEach endpoint's documentation specifies the minimum required permission level.\n\n## Available Services\n\n### IP Rulesets\nManage allowlists and blocklists of IP addresses and CIDR ranges with expiration support.\n\n### Common Business Services (CBS)\nAccess hierarchical IP range data from cloud providers, CDNs, and SaaS services. Browse by region\nor service, search by text or IP address, and identify which services an IP belongs to.\n\n## Error Responses\n\nError responses follow RFC 9457 Problem Details:\n\n```json\n{\"type\": \"/problems/authentication-required\", \"title\": \"Authentication Required\", \"status\": 401, \"detail\": \"No API key found in request\", \"instance\": \"/v1/edl/ip-rulesets/\", \"request_id\": \"61d9cf2a7fcf3d428cba7043efbe3342\"}\n```\n\nErrors emitted by the API gateway (authentication, access control, rate limiting,\nupstream failures) include a `request_id` extension member - include it when\ncontacting support.\n\nOne exception: the CTI lookup service's own errors (400 and 500 on the\n`/v1/cti/*` endpoints) use `{\"message\": \"...\", \"request_id\": \"...\"}`.\n\nCommon status codes:\n\n- **400 Bad Request** - Invalid parameters or request body\n- **401 Unauthorized** - Missing or invalid API key\n- **403 Forbidden** - Insufficient permissions or no active plan for the service\n- **404 Not Found** - The requested resource does not exist\n- **429 Too Many Requests** - Rate limit exceeded\n- **500 Internal Server Error** - Unexpected server error\n\n\n## Get an API key\n\nCreate keys at\n[platform.ellio.tech/dashboard/api-keys](https://platform.ellio.tech/dashboard/api-keys)\nwith **Create New API Key**:\n\n| Field | Notes |\n|---|---|\n| **Key Name** | A human-readable label. Make it specific (`splunk-prod-cti`, `ci-edl-rotator`). |\n| **Access Level** | `Read Only` covers CTI lookups and read access to the Blocklist platform. `Read & Write` also lets the key create, update, and delete rulesets, rules, and EDL Deployments. |\n| **Expiration** | `No expiration`, or a date at which the key expires automatically (midnight UTC). |\n\nThe platform shows the key value **once** - copy it into your secret\nstore immediately. ELLIO does not retain a plaintext copy; if you lose\nit, revoke the key and generate a new one.\n\n## For machines\n\nThis document is published at\n[/openapi/ellio-api.json](/openapi/ellio-api.json) and works as a tool\ndefinition for LLM agents and OpenAPI-to-MCP tooling. The prose\ndocumentation is available as [/llms.txt](/llms.txt) and\n[/llms-full.txt](/llms-full.txt)." }, "paths": { "/v1/edl/ip-rulesets/": { "get": { "operationId": "listRulesets", "summary": "List all IP rulesets", "parameters": [ { "in": "query", "name": "purpose", "schema": { "anyOf": [ { "enum": [ "blocklist", "allowlist" ], "type": "string" }, { "type": "null" } ], "description": "Filter rulesets by purpose (blocklist or allowlist)", "example": "blocklist", "title": "Purpose" }, "required": false, "description": "Filter rulesets by purpose (blocklist or allowlist)", "example": "blocklist" }, { "in": "query", "name": "page", "schema": { "default": 1, "description": "Page number (minimum 1)", "minimum": 1, "title": "Page", "type": "integer" }, "required": false, "description": "Page number (minimum 1)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagedRulesetSchema" }, "examples": { "rulesets": { "summary": "A blocklist and an allowlist", "value": { "items": [ { "id": "dc658778-3b64-4fe9-a3b6-ca1dc264f2fa", "name": "Threat Intelligence Feed", "purpose": "blocklist", "description": "IPs from threat intelligence sources", "total_rules": 1523, "active_rules": 1450, "created_at": "2026-01-15T10:30:00Z", "updated_at": "2026-06-28T09:12:44Z" }, { "id": "7f0e2a9c-51d4-4c8a-9b3e-2f6d8c1a5e70", "name": "Partner Allowlist", "purpose": "allowlist", "description": "Trusted partner infrastructure", "total_rules": 42, "active_rules": 42, "created_at": "2026-02-03T08:00:00Z", "updated_at": "2026-06-30T16:45:10Z" } ], "count": 2, "next": null, "prev": null } } } } } }, "400": { "description": "Bad Request - invalid parameters or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "validation_error": { "summary": "Request validation failed", "value": { "type": "/problems/validation-error", "title": "Validation Error", "status": 400, "detail": "Request validation failed", "instance": "/v1/edl/ip-rulesets/", "validation_errors": { "ip": [ "Invalid IP address or CIDR format" ] } } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key (rejected by the API gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "missing_key": { "summary": "No API key provided", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "No API key found in request", "instance": "/v1/edl/ip-rulesets/", "request_id": "61d9cf2a7fcf3d428cba7043efbe3342" } }, "invalid_key": { "summary": "Unknown or revoked API key", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Unauthorized", "instance": "/v1/edl/ip-rulesets/", "request_id": "5275cb5149a8a80a7d79ef6892066e0c" } } } } } }, "403": { "description": "Forbidden - insufficient API key permissions, no active plan for this service, or (with a request_id) rejected by the gateway access control.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "permission_denied": { "summary": "API key lacks the required permission", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "API key does not have 'read_write' permission for organization resources", "instance": "/v1/edl/ip-rulesets/" } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "/problems/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "API rate limit exceeded", "instance": "/v1/edl/ip-rulesets/", "request_id": "ca165c702f4dff31a01805e266a36e94" } } } } } }, "500": { "description": "Internal Server Error - an unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "internal_error": { "summary": "Unexpected server error", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request" } } } } } } }, "description": "\nRetrieve a paginated list of all active EDL IP rulesets for your organization.\nEach ruleset includes counts of total and active rules.\n\nUse cases:\n- Display all rulesets in a dashboard\n- Monitor ruleset sizes and expiration status\n- Select a ruleset for detailed inspection\n\n**Required Permission:** `read` or `read_write`\n**Required Plan:** Active EDL Management plan\n", "tags": [ "IP Rulesets" ], "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ] } }, "/v1/edl/ip-rulesets/{ruleset_id}": { "get": { "operationId": "getRuleset", "summary": "Get ruleset details", "parameters": [ { "in": "path", "name": "ruleset_id", "schema": { "format": "uuid", "title": "Ruleset Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RulesetSchema" }, "examples": { "ruleset": { "summary": "A blocklist ruleset", "value": { "id": "dc658778-3b64-4fe9-a3b6-ca1dc264f2fa", "name": "Threat Intelligence Feed", "purpose": "blocklist", "description": "IPs from threat intelligence sources", "total_rules": 1523, "active_rules": 1450, "created_at": "2026-01-15T10:30:00Z", "updated_at": "2026-06-28T09:12:44Z" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key (rejected by the API gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "missing_key": { "summary": "No API key provided", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "No API key found in request", "instance": "/v1/edl/ip-rulesets/", "request_id": "61d9cf2a7fcf3d428cba7043efbe3342" } }, "invalid_key": { "summary": "Unknown or revoked API key", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Unauthorized", "instance": "/v1/edl/ip-rulesets/", "request_id": "5275cb5149a8a80a7d79ef6892066e0c" } } } } } }, "403": { "description": "Forbidden - insufficient API key permissions, no active plan for this service, or (with a request_id) rejected by the gateway access control.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "permission_denied": { "summary": "API key lacks the required permission", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "API key does not have 'read_write' permission for organization resources", "instance": "/v1/edl/ip-rulesets/" } } } } } }, "404": { "description": "Not Found - the requested resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "/problems/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found", "instance": "/v1/edl/ip-rulesets/00000000-0000-0000-0000-000000000000" } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "/problems/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "API rate limit exceeded", "instance": "/v1/edl/ip-rulesets/", "request_id": "ca165c702f4dff31a01805e266a36e94" } } } } } }, "500": { "description": "Internal Server Error - an unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "internal_error": { "summary": "Unexpected server error", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request" } } } } } } }, "description": "\nRetrieve detailed information about a specific EDL IP ruleset by its ID.\nIncludes metadata and rule counts but not the actual rules.\n\nUse cases:\n- View ruleset configuration and metadata\n- Check rule counts before fetching rules\n- Verify ruleset exists before operations\n\n**Required Permission:** `read` or `read_write`\n**Required Plan:** Active EDL Management plan\n", "tags": [ "IP Rulesets" ], "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ] } }, "/v1/edl/ip-rulesets/{ruleset_id}/rules": { "get": { "operationId": "listRules", "summary": "List all rules in ruleset", "parameters": [ { "in": "path", "name": "ruleset_id", "schema": { "format": "uuid", "title": "Ruleset Id", "type": "string" }, "required": true }, { "in": "query", "name": "active_only", "schema": { "default": false, "description": "If true, only return active (non-expired) rules", "title": "Active Only", "type": "boolean" }, "required": false, "description": "If true, only return active (non-expired) rules" }, { "in": "query", "name": "page", "schema": { "default": 1, "description": "Page number (minimum 1)", "minimum": 1, "title": "Page", "type": "integer" }, "required": false, "description": "Page number (minimum 1)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagedRuleSchema" }, "examples": { "rules": { "summary": "First page of rules (single IP and CIDR entries)", "value": { "items": [ { "ip": "203.0.113.7", "name": "Malicious IP from threat intel", "expires_at": "2026-12-31T23:59:59Z", "created_at": "2026-06-01T10:30:00Z", "updated_at": "2026-06-01T10:30:00Z" }, { "ip": "198.51.100.0/24", "name": "Scanning subnet", "expires_at": null, "created_at": "2026-05-20T14:05:00Z", "updated_at": "2026-05-20T14:05:00Z" } ], "count": 1523, "next": "https://api.ellio.tech/v1/edl/ip-rulesets/dc658778-3b64-4fe9-a3b6-ca1dc264f2fa/rules?page=2", "prev": null } } } } } }, "400": { "description": "Bad Request - invalid parameters or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "validation_error": { "summary": "Request validation failed", "value": { "type": "/problems/validation-error", "title": "Validation Error", "status": 400, "detail": "Request validation failed", "instance": "/v1/edl/ip-rulesets/", "validation_errors": { "ip": [ "Invalid IP address or CIDR format" ] } } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key (rejected by the API gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "missing_key": { "summary": "No API key provided", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "No API key found in request", "instance": "/v1/edl/ip-rulesets/", "request_id": "61d9cf2a7fcf3d428cba7043efbe3342" } }, "invalid_key": { "summary": "Unknown or revoked API key", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Unauthorized", "instance": "/v1/edl/ip-rulesets/", "request_id": "5275cb5149a8a80a7d79ef6892066e0c" } } } } } }, "403": { "description": "Forbidden - insufficient API key permissions, no active plan for this service, or (with a request_id) rejected by the gateway access control.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "permission_denied": { "summary": "API key lacks the required permission", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "API key does not have 'read_write' permission for organization resources", "instance": "/v1/edl/ip-rulesets/" } } } } } }, "404": { "description": "Not Found - the requested resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "/problems/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found", "instance": "/v1/edl/ip-rulesets/00000000-0000-0000-0000-000000000000" } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "/problems/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "API rate limit exceeded", "instance": "/v1/edl/ip-rulesets/", "request_id": "ca165c702f4dff31a01805e266a36e94" } } } } } }, "500": { "description": "Internal Server Error - an unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "internal_error": { "summary": "Unexpected server error", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request" } } } } } } }, "description": "\nRetrieve all IP rules from a specific ruleset, including both active and expired rules.\n\nUse cases:\n- Export ruleset contents for backup\n- Audit all IPs in a security policy\n- Sync rules with external systems\n\n**Required Permission:** `read` or `read_write`\n**Required Plan:** Active EDL Management plan\n", "tags": [ "IP Rulesets" ], "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ] }, "post": { "operationId": "addRule", "summary": "Add IP to ruleset", "parameters": [ { "in": "path", "name": "ruleset_id", "schema": { "format": "uuid", "title": "Ruleset Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddRuleResponse" }, "examples": { "updated": { "summary": "Existing rule updated (conflict_resolution=update)", "value": { "action": "updated", "rule": { "ip": "203.0.113.7", "name": "Malicious IP from threat intel", "expires_at": "2026-12-31T23:59:59Z", "created_at": "2026-06-01T10:30:00Z", "updated_at": "2026-06-01T10:30:00Z" } } }, "skipped": { "summary": "Existing rule left unchanged (conflict_resolution=skip)", "value": { "action": "skipped", "rule": { "ip": "203.0.113.7", "name": "Malicious IP from threat intel", "expires_at": "2026-12-31T23:59:59Z", "created_at": "2026-06-01T10:30:00Z", "updated_at": "2026-06-01T10:30:00Z" } } } } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddRuleResponse" }, "examples": { "created": { "summary": "New rule created", "value": { "action": "created", "rule": { "ip": "203.0.113.7", "name": "Malicious IP from threat intel", "expires_at": "2026-12-31T23:59:59Z", "created_at": "2026-06-01T10:30:00Z", "updated_at": "2026-06-01T10:30:00Z" } } } } } } }, "400": { "description": "Bad Request - invalid parameters or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "validation_error": { "summary": "Request validation failed", "value": { "type": "/problems/validation-error", "title": "Validation Error", "status": 400, "detail": "Request validation failed", "instance": "/v1/edl/ip-rulesets/", "validation_errors": { "ip": [ "Invalid IP address or CIDR format" ] } } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key (rejected by the API gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "missing_key": { "summary": "No API key provided", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "No API key found in request", "instance": "/v1/edl/ip-rulesets/", "request_id": "61d9cf2a7fcf3d428cba7043efbe3342" } }, "invalid_key": { "summary": "Unknown or revoked API key", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Unauthorized", "instance": "/v1/edl/ip-rulesets/", "request_id": "5275cb5149a8a80a7d79ef6892066e0c" } } } } } }, "403": { "description": "Forbidden - insufficient API key permissions, no active plan for this service, or (with a request_id) rejected by the gateway access control.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "permission_denied": { "summary": "API key lacks the required permission", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "API key does not have 'read_write' permission for organization resources", "instance": "/v1/edl/ip-rulesets/" } } } } } }, "404": { "description": "Not Found - the requested resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "/problems/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found", "instance": "/v1/edl/ip-rulesets/00000000-0000-0000-0000-000000000000" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "/problems/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "API rate limit exceeded", "instance": "/v1/edl/ip-rulesets/", "request_id": "ca165c702f4dff31a01805e266a36e94" } } } } } }, "500": { "description": "Internal Server Error - an unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "internal_error": { "summary": "Unexpected server error", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request" } } } } } } }, "description": "\nAdd a single IP address or CIDR block to the ruleset with smart conflict resolution.\n\nConflict Resolution Modes:\n- `extend`: Keep the longer expiration date (default)\n- `override`: Replace existing rule completely\n- `skip`: Keep existing rule unchanged\n- `fail`: Return error if IP already exists\n\nUse cases:\n- Block a newly identified threat IP\n- Add IP from threat intelligence feed\n- Extend expiration of existing block\n\n**Required Permission:** `read_write`\n**Required Plan:** Active EDL Management plan\n", "tags": [ "IP Rulesets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddIPRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ] } }, "/v1/edl/ip-rulesets/{ruleset_id}/rules/rule": { "get": { "operationId": "getRule", "summary": "Get specific rule", "parameters": [ { "in": "path", "name": "ruleset_id", "schema": { "format": "uuid", "title": "Ruleset Id", "type": "string" }, "required": true }, { "in": "query", "name": "ip", "schema": { "description": "IP address or CIDR to retrieve", "example": "203.0.113.1", "title": "Ip", "type": "string" }, "required": true, "description": "IP address or CIDR to retrieve", "example": "203.0.113.1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleSchema" }, "examples": { "rule": { "summary": "A rule with expiration", "value": { "ip": "203.0.113.7", "name": "Malicious IP from threat intel", "expires_at": "2026-12-31T23:59:59Z", "created_at": "2026-06-01T10:30:00Z", "updated_at": "2026-06-01T10:30:00Z" } } } } } }, "400": { "description": "Bad Request - invalid parameters or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "validation_error": { "summary": "Request validation failed", "value": { "type": "/problems/validation-error", "title": "Validation Error", "status": 400, "detail": "Request validation failed", "instance": "/v1/edl/ip-rulesets/", "validation_errors": { "ip": [ "Invalid IP address or CIDR format" ] } } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key (rejected by the API gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "missing_key": { "summary": "No API key provided", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "No API key found in request", "instance": "/v1/edl/ip-rulesets/", "request_id": "61d9cf2a7fcf3d428cba7043efbe3342" } }, "invalid_key": { "summary": "Unknown or revoked API key", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Unauthorized", "instance": "/v1/edl/ip-rulesets/", "request_id": "5275cb5149a8a80a7d79ef6892066e0c" } } } } } }, "403": { "description": "Forbidden - insufficient API key permissions, no active plan for this service, or (with a request_id) rejected by the gateway access control.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "permission_denied": { "summary": "API key lacks the required permission", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "API key does not have 'read_write' permission for organization resources", "instance": "/v1/edl/ip-rulesets/" } } } } } }, "404": { "description": "Not Found - the requested resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "/problems/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found", "instance": "/v1/edl/ip-rulesets/00000000-0000-0000-0000-000000000000" } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "/problems/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "API rate limit exceeded", "instance": "/v1/edl/ip-rulesets/", "request_id": "ca165c702f4dff31a01805e266a36e94" } } } } } }, "500": { "description": "Internal Server Error - an unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "internal_error": { "summary": "Unexpected server error", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request" } } } } } } }, "description": "\nRetrieve details of a specific IP rule by IP address.\n\n**Required Permission:** `read` or `read_write`\n**Required Plan:** Active EDL Management plan\n", "tags": [ "IP Rulesets" ], "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ] }, "put": { "operationId": "updateRule", "summary": "Update rule", "parameters": [ { "in": "path", "name": "ruleset_id", "schema": { "format": "uuid", "title": "Ruleset Id", "type": "string" }, "required": true }, { "in": "query", "name": "ip", "schema": { "description": "IP address or CIDR to update", "example": "203.0.113.1", "title": "Ip", "type": "string" }, "required": true, "description": "IP address or CIDR to update", "example": "203.0.113.1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleSchema" }, "examples": { "updated": { "summary": "The updated rule", "value": { "ip": "203.0.113.7", "name": "Malicious IP from threat intel", "expires_at": "2026-12-31T23:59:59Z", "created_at": "2026-06-01T10:30:00Z", "updated_at": "2026-06-01T10:30:00Z" } } } } } }, "400": { "description": "Bad Request - invalid parameters or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "validation_error": { "summary": "Request validation failed", "value": { "type": "/problems/validation-error", "title": "Validation Error", "status": 400, "detail": "Request validation failed", "instance": "/v1/edl/ip-rulesets/", "validation_errors": { "ip": [ "Invalid IP address or CIDR format" ] } } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key (rejected by the API gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "missing_key": { "summary": "No API key provided", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "No API key found in request", "instance": "/v1/edl/ip-rulesets/", "request_id": "61d9cf2a7fcf3d428cba7043efbe3342" } }, "invalid_key": { "summary": "Unknown or revoked API key", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Unauthorized", "instance": "/v1/edl/ip-rulesets/", "request_id": "5275cb5149a8a80a7d79ef6892066e0c" } } } } } }, "403": { "description": "Forbidden - insufficient API key permissions, no active plan for this service, or (with a request_id) rejected by the gateway access control.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "permission_denied": { "summary": "API key lacks the required permission", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "API key does not have 'read_write' permission for organization resources", "instance": "/v1/edl/ip-rulesets/" } } } } } }, "404": { "description": "Not Found - the requested resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "/problems/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found", "instance": "/v1/edl/ip-rulesets/00000000-0000-0000-0000-000000000000" } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "/problems/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "API rate limit exceeded", "instance": "/v1/edl/ip-rulesets/", "request_id": "ca165c702f4dff31a01805e266a36e94" } } } } } }, "500": { "description": "Internal Server Error - an unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "internal_error": { "summary": "Unexpected server error", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request" } } } } } } }, "description": "\nUpdate an existing IP rule (idempotent).\n\n**Required Permission:** `read_write`\n**Required Plan:** Active EDL Management plan\n", "tags": [ "IP Rulesets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRuleRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ] }, "delete": { "operationId": "deleteRule", "summary": "Delete rule", "parameters": [ { "in": "path", "name": "ruleset_id", "schema": { "format": "uuid", "title": "Ruleset Id", "type": "string" }, "required": true }, { "in": "query", "name": "ip", "schema": { "description": "IP address or CIDR to delete", "example": "203.0.113.1", "title": "Ip", "type": "string" }, "required": true, "description": "IP address or CIDR to delete", "example": "203.0.113.1" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request - invalid parameters or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "validation_error": { "summary": "Request validation failed", "value": { "type": "/problems/validation-error", "title": "Validation Error", "status": 400, "detail": "Request validation failed", "instance": "/v1/edl/ip-rulesets/", "validation_errors": { "ip": [ "Invalid IP address or CIDR format" ] } } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key (rejected by the API gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "missing_key": { "summary": "No API key provided", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "No API key found in request", "instance": "/v1/edl/ip-rulesets/", "request_id": "61d9cf2a7fcf3d428cba7043efbe3342" } }, "invalid_key": { "summary": "Unknown or revoked API key", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Unauthorized", "instance": "/v1/edl/ip-rulesets/", "request_id": "5275cb5149a8a80a7d79ef6892066e0c" } } } } } }, "403": { "description": "Forbidden - insufficient API key permissions, no active plan for this service, or (with a request_id) rejected by the gateway access control.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "permission_denied": { "summary": "API key lacks the required permission", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "API key does not have 'read_write' permission for organization resources", "instance": "/v1/edl/ip-rulesets/" } } } } } }, "404": { "description": "Not Found - the requested resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "/problems/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found", "instance": "/v1/edl/ip-rulesets/00000000-0000-0000-0000-000000000000" } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "/problems/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "API rate limit exceeded", "instance": "/v1/edl/ip-rulesets/", "request_id": "ca165c702f4dff31a01805e266a36e94" } } } } } }, "500": { "description": "Internal Server Error - an unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "internal_error": { "summary": "Unexpected server error", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request" } } } } } } }, "description": "\nRemove an IP rule from the ruleset (idempotent).\n\n**Required Permission:** `read_write`\n**Required Plan:** Active EDL Management plan\n", "tags": [ "IP Rulesets" ], "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ] } }, "/v1/edl/ip-rulesets/{ruleset_id}/rules:expire": { "post": { "operationId": "expireRules", "summary": "Expire rules by time threshold", "parameters": [ { "in": "path", "name": "ruleset_id", "schema": { "format": "uuid", "title": "Ruleset Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExpireRulesResponse" }, "examples": { "expired": { "summary": "Rules expiring within 5 hours were expired now", "value": { "threshold": "5h", "cutoff_time": "2026-07-04T15:30:00Z", "expired_count": 150, "dry_run": false } } } } } }, "400": { "description": "Bad Request - invalid parameters or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "validation_error": { "summary": "Request validation failed", "value": { "type": "/problems/validation-error", "title": "Validation Error", "status": 400, "detail": "Request validation failed", "instance": "/v1/edl/ip-rulesets/", "validation_errors": { "ip": [ "Invalid IP address or CIDR format" ] } } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key (rejected by the API gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "missing_key": { "summary": "No API key provided", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "No API key found in request", "instance": "/v1/edl/ip-rulesets/", "request_id": "61d9cf2a7fcf3d428cba7043efbe3342" } }, "invalid_key": { "summary": "Unknown or revoked API key", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Unauthorized", "instance": "/v1/edl/ip-rulesets/", "request_id": "5275cb5149a8a80a7d79ef6892066e0c" } } } } } }, "403": { "description": "Forbidden - insufficient API key permissions, no active plan for this service, or (with a request_id) rejected by the gateway access control.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "permission_denied": { "summary": "API key lacks the required permission", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "API key does not have 'read_write' permission for organization resources", "instance": "/v1/edl/ip-rulesets/" } } } } } }, "404": { "description": "Not Found - the requested resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "/problems/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found", "instance": "/v1/edl/ip-rulesets/00000000-0000-0000-0000-000000000000" } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "/problems/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "API rate limit exceeded", "instance": "/v1/edl/ip-rulesets/", "request_id": "ca165c702f4dff31a01805e266a36e94" } } } } } }, "500": { "description": "Internal Server Error - an unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "internal_error": { "summary": "Unexpected server error", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request" } } } } } } }, "description": "\nImmediately expire rules that would expire within the specified time threshold.\n\nSets `expires_at = now` for all rules where `now <= expires_at < now + threshold`.\nRules are preserved for audit purposes but excluded from active queries.\n\nTime threshold formats:\n- Hours: `5h`, `5 hours`, `5hr`\n- Days: `10d`, `10 days`\n- Weeks: `2w`, `2 weeks`\n\nUse cases:\n- Expire rules about to expire within a maintenance window\n- Proactive cleanup before feed refresh\n- Clear short-lived rules before importing a new batch\n\n**Note:** Permanent rules (without expiration) and already expired rules are not affected.\n\n**Required Permission:** `read_write`\n**Required Plan:** Active EDL Management plan\n", "tags": [ "IP Rulesets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExpireRulesRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ] } }, "/v1/edl/ip-rulesets/{ruleset_id}/rules:batch": { "post": { "operationId": "batchRuleOperation", "summary": "Batch operations on multiple IPs", "parameters": [ { "in": "path", "name": "ruleset_id", "schema": { "format": "uuid", "title": "Ruleset Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchOperationResponse" }, "examples": { "batch_add": { "summary": "Batch add of 65 IPs", "value": { "action": "add", "summary": { "added": 50, "updated": 10, "skipped": 5, "failed": 0, "requested": 65 } } } } } } }, "400": { "description": "Bad Request - invalid parameters or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "validation_error": { "summary": "Request validation failed", "value": { "type": "/problems/validation-error", "title": "Validation Error", "status": 400, "detail": "Request validation failed", "instance": "/v1/edl/ip-rulesets/", "validation_errors": { "ip": [ "Invalid IP address or CIDR format" ] } } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key (rejected by the API gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "missing_key": { "summary": "No API key provided", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "No API key found in request", "instance": "/v1/edl/ip-rulesets/", "request_id": "61d9cf2a7fcf3d428cba7043efbe3342" } }, "invalid_key": { "summary": "Unknown or revoked API key", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Unauthorized", "instance": "/v1/edl/ip-rulesets/", "request_id": "5275cb5149a8a80a7d79ef6892066e0c" } } } } } }, "403": { "description": "Forbidden - insufficient API key permissions, no active plan for this service, or (with a request_id) rejected by the gateway access control.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "permission_denied": { "summary": "API key lacks the required permission", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "API key does not have 'read_write' permission for organization resources", "instance": "/v1/edl/ip-rulesets/" } } } } } }, "404": { "description": "Not Found - the requested resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "/problems/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found", "instance": "/v1/edl/ip-rulesets/00000000-0000-0000-0000-000000000000" } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "/problems/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "API rate limit exceeded", "instance": "/v1/edl/ip-rulesets/", "request_id": "ca165c702f4dff31a01805e266a36e94" } } } } } }, "500": { "description": "Internal Server Error - an unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "internal_error": { "summary": "Unexpected server error", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request" } } } } } } }, "description": "\nExecute batch operations on multiple IP rules in a single request.\nSupports adding, removing, or updating multiple IPs efficiently.\n\nOperations:\n- `add`: Add multiple IPs with conflict resolution\n- `remove`: Remove multiple IPs from ruleset\n- `update`: Update existing rules (expiration, names)\n\nUse cases:\n- Import threat intelligence feed with hundreds of IPs\n- Bulk remove expired or false positive blocks\n- Mass update expiration dates\n\n**Required Permission:** `read_write`\n**Required Plan:** Active EDL Management plan\n", "tags": [ "IP Rulesets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchOperationRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ] } }, "/v1/edl/ip-rulesets/{ruleset_id}/rules:check": { "post": { "operationId": "checkIpInRuleset", "summary": "Check IP in specific ruleset", "parameters": [ { "in": "path", "name": "ruleset_id", "schema": { "format": "uuid", "title": "Ruleset Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckIPInRulesetResponse" }, "examples": { "found": { "summary": "IP matches a CIDR rule in the ruleset", "value": { "ip": "198.51.100.24", "found": true, "rule_count": 1, "matching_rules": [ { "ip": "198.51.100.0/24", "name": "Scanning subnet", "expires_at": null, "created_at": "2026-05-20T14:05:00Z", "updated_at": "2026-05-20T14:05:00Z" } ] } }, "not_found": { "summary": "IP not present", "value": { "ip": "192.0.2.10", "found": false, "rule_count": 0, "matching_rules": [] } } } } } }, "400": { "description": "Bad Request - invalid parameters or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "validation_error": { "summary": "Request validation failed", "value": { "type": "/problems/validation-error", "title": "Validation Error", "status": 400, "detail": "Request validation failed", "instance": "/v1/edl/ip-rulesets/", "validation_errors": { "ip": [ "Invalid IP address or CIDR format" ] } } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key (rejected by the API gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "missing_key": { "summary": "No API key provided", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "No API key found in request", "instance": "/v1/edl/ip-rulesets/", "request_id": "61d9cf2a7fcf3d428cba7043efbe3342" } }, "invalid_key": { "summary": "Unknown or revoked API key", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Unauthorized", "instance": "/v1/edl/ip-rulesets/", "request_id": "5275cb5149a8a80a7d79ef6892066e0c" } } } } } }, "403": { "description": "Forbidden - insufficient API key permissions, no active plan for this service, or (with a request_id) rejected by the gateway access control.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "permission_denied": { "summary": "API key lacks the required permission", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "API key does not have 'read_write' permission for organization resources", "instance": "/v1/edl/ip-rulesets/" } } } } } }, "404": { "description": "Not Found - the requested resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "/problems/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found", "instance": "/v1/edl/ip-rulesets/00000000-0000-0000-0000-000000000000" } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "/problems/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "API rate limit exceeded", "instance": "/v1/edl/ip-rulesets/", "request_id": "ca165c702f4dff31a01805e266a36e94" } } } } } }, "500": { "description": "Internal Server Error - an unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "internal_error": { "summary": "Unexpected server error", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request" } } } } } } }, "description": "\nCheck if an IP address exists in a specific ruleset.\nReturns the matching rule if found, including CIDR blocks that contain the IP.\n\nThis endpoint is for checking within a SINGLE ruleset.\nTo check across all rulesets, use `/ip-rulesets/rules:check` instead.\n\nUse cases:\n- Verify if an IP is blocked in a particular policy\n- Find the specific rule affecting an IP\n- Check before adding to avoid duplicates\n\n**Required Permission:** `read` or `read_write`\n**Required Plan:** Active EDL Management plan\n", "tags": [ "IP Rulesets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckIPRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ] } }, "/v1/edl/ip-rulesets/rules:check": { "post": { "operationId": "checkIpAcrossRulesets", "summary": "Check IP across all rulesets", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckIPAcrossRulesetsResponse" }, "examples": { "found": { "summary": "IP found in one ruleset", "value": { "ip": "203.0.113.7", "found": true, "ruleset_count": 1, "total_rule_count": 1, "rulesets": [ { "ruleset_id": "dc658778-3b64-4fe9-a3b6-ca1dc264f2fa", "ruleset_name": "Threat Intelligence Feed", "rule_count": 1, "rules": [ { "ip": "203.0.113.7", "name": "Malicious IP from threat intel", "expires_at": "2026-12-31T23:59:59Z", "created_at": "2026-06-01T10:30:00Z", "updated_at": "2026-06-01T10:30:00Z" } ] } ] } } } } } }, "400": { "description": "Bad Request - invalid parameters or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "validation_error": { "summary": "Request validation failed", "value": { "type": "/problems/validation-error", "title": "Validation Error", "status": 400, "detail": "Request validation failed", "instance": "/v1/edl/ip-rulesets/", "validation_errors": { "ip": [ "Invalid IP address or CIDR format" ] } } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key (rejected by the API gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "missing_key": { "summary": "No API key provided", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "No API key found in request", "instance": "/v1/edl/ip-rulesets/", "request_id": "61d9cf2a7fcf3d428cba7043efbe3342" } }, "invalid_key": { "summary": "Unknown or revoked API key", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Unauthorized", "instance": "/v1/edl/ip-rulesets/", "request_id": "5275cb5149a8a80a7d79ef6892066e0c" } } } } } }, "403": { "description": "Forbidden - insufficient API key permissions, no active plan for this service, or (with a request_id) rejected by the gateway access control.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "permission_denied": { "summary": "API key lacks the required permission", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "API key does not have 'read_write' permission for organization resources", "instance": "/v1/edl/ip-rulesets/" } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "/problems/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "API rate limit exceeded", "instance": "/v1/edl/ip-rulesets/", "request_id": "ca165c702f4dff31a01805e266a36e94" } } } } } }, "500": { "description": "Internal Server Error - an unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "internal_error": { "summary": "Unexpected server error", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request" } } } } } } }, "description": "\nSearch for an IP address across all active rulesets in your organization.\nReturns all rulesets that contain the IP and the matching rules.\n\nThis endpoint searches across all your organization's rulesets.\nTo check within a SINGLE ruleset, use `/ip-rulesets/{ruleset_id}/rules:check` instead.\n\nUse cases:\n- Verify if an IP is blocked anywhere in your infrastructure\n- Find all security policies affecting a specific IP\n- Audit IP coverage across multiple rulesets\n- Identify redundant blocks across rulesets\n\n**Required Permission:** `read` or `read_write`\n**Required Plan:** Active EDL Management plan\n", "tags": [ "IP Rulesets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckIPRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ] } }, "/v1/cbs/lookup": { "get": { "operationId": "cbsLookupIp", "summary": "Classify an IP against Common Business Services", "parameters": [ { "in": "query", "name": "ip", "schema": { "description": "IPv4 or IPv6 address", "examples": [ "192.0.2.7", "2001:db8::1" ], "title": "Ip", "type": "string" }, "required": true, "description": "IPv4 or IPv6 address", "examples": [ "192.0.2.7", "2001:db8::1" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CBSLookupResponse" }, "examples": { "classified": { "summary": "IP belongs to a known business service", "value": { "ip": "8.8.8.8", "found": true, "cidr": "8.8.8.0/24", "labels": [ "Software as a Service (SaaS) > Google Workspace > Google Workspace" ], "cbs_ids": [ "/saas/google-workspace/google-workspace" ], "providers": [ "google" ], "types": [ "saas" ], "services": [ "workspace" ], "regions": [], "matches": [ { "provider": "google", "type": "saas", "service": "workspace" } ] } }, "not_found": { "summary": "IP is in no known range", "value": { "ip": "192.0.2.7", "found": false, "labels": [], "cbs_ids": [], "providers": [], "types": [], "services": [], "regions": [], "matches": [] } } } } } }, "400": { "description": "Bad Request - invalid parameters or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "validation_error": { "summary": "Request validation failed", "value": { "type": "/problems/validation-error", "title": "Validation Error", "status": 400, "detail": "Request validation failed", "instance": "/v1/edl/ip-rulesets/", "validation_errors": { "ip": [ "Invalid IP address or CIDR format" ] } } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key (rejected by the API gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "missing_key": { "summary": "No API key provided", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "No API key found in request", "instance": "/v1/edl/ip-rulesets/", "request_id": "61d9cf2a7fcf3d428cba7043efbe3342" } }, "invalid_key": { "summary": "Unknown or revoked API key", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Unauthorized", "instance": "/v1/edl/ip-rulesets/", "request_id": "5275cb5149a8a80a7d79ef6892066e0c" } } } } } }, "403": { "description": "Forbidden - insufficient API key permissions, no active plan for this service, or (with a request_id) rejected by the gateway access control.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "permission_denied": { "summary": "API key lacks the required permission", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "API key does not have 'read_write' permission for organization resources", "instance": "/v1/edl/ip-rulesets/" } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "/problems/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "API rate limit exceeded", "instance": "/v1/edl/ip-rulesets/", "request_id": "ca165c702f4dff31a01805e266a36e94" } } } } } }, "500": { "description": "Internal Server Error - an unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "internal_error": { "summary": "Unexpected server error", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request" } } } } } }, "502": { "description": "Bad Gateway - the upstream service did not respond", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "upstream_unavailable": { "summary": "Upstream service unavailable", "value": { "type": "/problems/bad-gateway", "title": "Bad Gateway", "status": 502, "detail": "An invalid response was received from the upstream server", "instance": "/v1/cbs/lookup", "request_id": "3f6c1a09be425d7702c1587fbb1f30d2" } } } } } } }, "description": "Returns the CBS classification of an IP: providers, services, regions, human `labels`, and stable `cbs_ids`, plus the matched `cidr`. `found` is false when the IP is in no known range.\n\n**Required:** active CTI or blocklist plan.", "tags": [ "CBS" ], "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ] }, "post": { "operationId": "cbsLookupBulk", "summary": "Classify many IPs (bulk enrichment)", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/CBSLookupResponse" }, "title": "Response", "type": "array" }, "examples": { "mixed": { "summary": "One classified IP, one unknown", "value": [ { "ip": "8.8.8.8", "found": true, "cidr": "8.8.8.0/24", "labels": [ "Software as a Service (SaaS) > Google Workspace > Google Workspace" ], "cbs_ids": [ "/saas/google-workspace/google-workspace" ], "providers": [ "google" ], "types": [ "saas" ], "services": [ "workspace" ], "regions": [], "matches": [ { "provider": "google", "type": "saas", "service": "workspace" } ] }, { "ip": "192.0.2.7", "found": false, "labels": [], "cbs_ids": [], "providers": [], "types": [], "services": [], "regions": [], "matches": [] } ] } } } } }, "400": { "description": "Bad Request - invalid parameters or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "validation_error": { "summary": "Request validation failed", "value": { "type": "/problems/validation-error", "title": "Validation Error", "status": 400, "detail": "Request validation failed", "instance": "/v1/edl/ip-rulesets/", "validation_errors": { "ip": [ "Invalid IP address or CIDR format" ] } } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key (rejected by the API gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "missing_key": { "summary": "No API key provided", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "No API key found in request", "instance": "/v1/edl/ip-rulesets/", "request_id": "61d9cf2a7fcf3d428cba7043efbe3342" } }, "invalid_key": { "summary": "Unknown or revoked API key", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Unauthorized", "instance": "/v1/edl/ip-rulesets/", "request_id": "5275cb5149a8a80a7d79ef6892066e0c" } } } } } }, "403": { "description": "Forbidden - insufficient API key permissions, no active plan for this service, or (with a request_id) rejected by the gateway access control.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "permission_denied": { "summary": "API key lacks the required permission", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "API key does not have 'read_write' permission for organization resources", "instance": "/v1/edl/ip-rulesets/" } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "/problems/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "API rate limit exceeded", "instance": "/v1/edl/ip-rulesets/", "request_id": "ca165c702f4dff31a01805e266a36e94" } } } } } }, "500": { "description": "Internal Server Error - an unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "internal_error": { "summary": "Unexpected server error", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request" } } } } } }, "502": { "description": "Bad Gateway - the upstream service did not respond", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "upstream_unavailable": { "summary": "Upstream service unavailable", "value": { "type": "/problems/bad-gateway", "title": "Bad Gateway", "status": 502, "detail": "An invalid response was received from the upstream server", "instance": "/v1/cbs/lookup", "request_id": "3f6c1a09be425d7702c1587fbb1f30d2" } } } } } } }, "description": "Classify up to 1024 IPs in one request. Returns a result per input IP (invalid IPs come back as `found: false`).\n\n**Required:** active CTI or blocklist plan.", "tags": [ "CBS" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CBSBulkLookupRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ] } }, "/v1/cbs/node": { "get": { "operationId": "cbsNode", "summary": "Get a CBS node by id (path)", "parameters": [ { "in": "query", "name": "id", "schema": { "default": "/", "description": "cbs_id (node path); omit for the root", "title": "Id", "type": "string" }, "required": false, "description": "cbs_id (node path); omit for the root" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CBSNodeDetailSchema" }, "examples": { "provider_node": { "summary": "A provider node with children and breadcrumb", "value": { "id": "/cloud/aws", "name": "Amazon Web Services (AWS)", "label": "Cloud Providers > Amazon Web Services (AWS)", "provider": "aws", "type": "cloud", "service": null, "region": null, "direction": null, "tooltip": "", "description": "", "references": [], "metadata": { "description": "AWS global cloud infrastructure IP ranges", "source": "https://ip-ranges.amazonaws.com/ip-ranges.json" }, "counts": { "ipv4_entries": 7819, "ipv6_entries": 2922, "ipv4_addresses": "102425278", "ipv6_addresses": "88101937038" }, "ancestors": [ { "id": "/cloud", "name": "Cloud Providers", "type": "cloud" } ], "children": [ { "id": "/cloud/aws/by-service", "name": "By Service", "type": "cloud", "has_children": true }, { "id": "/cloud/aws/by-region", "name": "By Region", "type": "cloud", "has_children": true } ], "deprecated": false, "last_updated": "2026-07-03T22:54:25Z" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key (rejected by the API gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "missing_key": { "summary": "No API key provided", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "No API key found in request", "instance": "/v1/edl/ip-rulesets/", "request_id": "61d9cf2a7fcf3d428cba7043efbe3342" } }, "invalid_key": { "summary": "Unknown or revoked API key", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Unauthorized", "instance": "/v1/edl/ip-rulesets/", "request_id": "5275cb5149a8a80a7d79ef6892066e0c" } } } } } }, "403": { "description": "Forbidden - insufficient API key permissions, no active plan for this service, or (with a request_id) rejected by the gateway access control.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "permission_denied": { "summary": "API key lacks the required permission", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "API key does not have 'read_write' permission for organization resources", "instance": "/v1/edl/ip-rulesets/" } } } } } }, "404": { "description": "Not Found - the requested resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "/problems/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found", "instance": "/v1/edl/ip-rulesets/00000000-0000-0000-0000-000000000000" } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "/problems/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "API rate limit exceeded", "instance": "/v1/edl/ip-rulesets/", "request_id": "ca165c702f4dff31a01805e266a36e94" } } } } } }, "500": { "description": "Internal Server Error - an unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "internal_error": { "summary": "Unexpected server error", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request" } } } } } } }, "description": "Returns the node addressed by its `cbs_id` (a stable path) plus its `children` and `ancestors` -- navigate by following `children[].id`. Omit `id` (or pass `/`) for the root. A stale/unknown id returns `404`.\n\n**Required:** active CTI or blocklist plan.", "tags": [ "CBS" ], "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ] } }, "/v1/cbs/node/ranges": { "get": { "operationId": "cbsNodeRanges", "summary": "Get a node's IP ranges", "parameters": [ { "in": "query", "name": "id", "schema": { "description": "cbs_id (node path)", "title": "Id", "type": "string" }, "required": true, "description": "cbs_id (node path)" }, { "in": "query", "name": "page_token", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Token" }, "required": false }, { "in": "query", "name": "page_size", "schema": { "default": 10000, "maximum": 50000, "minimum": 1, "title": "Page Size", "type": "integer" }, "required": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CBSRangesResponse" }, "examples": { "first_page": { "summary": "First page of a node's CIDRs", "value": { "id": "/cdn/cloudflare", "ranges": [ "104.16.0.0/13", "172.64.0.0/13", "2606:4700::/32" ], "next_page_token": "1783108025:10000" } } } } } }, "400": { "description": "Bad Request - invalid parameters or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "validation_error": { "summary": "Request validation failed", "value": { "type": "/problems/validation-error", "title": "Validation Error", "status": 400, "detail": "Request validation failed", "instance": "/v1/edl/ip-rulesets/", "validation_errors": { "ip": [ "Invalid IP address or CIDR format" ] } } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key (rejected by the API gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "missing_key": { "summary": "No API key provided", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "No API key found in request", "instance": "/v1/edl/ip-rulesets/", "request_id": "61d9cf2a7fcf3d428cba7043efbe3342" } }, "invalid_key": { "summary": "Unknown or revoked API key", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Unauthorized", "instance": "/v1/edl/ip-rulesets/", "request_id": "5275cb5149a8a80a7d79ef6892066e0c" } } } } } }, "403": { "description": "Forbidden - insufficient API key permissions, no active plan for this service, or (with a request_id) rejected by the gateway access control.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "permission_denied": { "summary": "API key lacks the required permission", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "API key does not have 'read_write' permission for organization resources", "instance": "/v1/edl/ip-rulesets/" } } } } } }, "404": { "description": "Not Found - the requested resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "not_found": { "summary": "Resource not found", "value": { "type": "/problems/not-found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found", "instance": "/v1/edl/ip-rulesets/00000000-0000-0000-0000-000000000000" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "/problems/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "API rate limit exceeded", "instance": "/v1/edl/ip-rulesets/", "request_id": "ca165c702f4dff31a01805e266a36e94" } } } } } }, "500": { "description": "Internal Server Error - an unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "internal_error": { "summary": "Unexpected server error", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request" } } } } } } }, "description": "Every CIDR belonging to the node and its descendants, keyset-paginated: pass `next_page_token` back as `page_token` (an opaque cursor). If the underlying dataset rolls over mid-pagination the cursor goes stale and you get `409` -- restart from the first page; a malformed cursor is `400`. Use to build allow/deny lists from a CBS node.\n\n**Required:** active CTI or blocklist plan.", "tags": [ "CBS" ], "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ] } }, "/v1/cbs/search": { "get": { "operationId": "cbsSearch", "summary": "Search CBS nodes by name", "parameters": [ { "in": "query", "name": "q", "schema": { "description": "Search term", "minLength": 1, "title": "Q", "type": "string" }, "required": true, "description": "Search term" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CBSSearchResponse" }, "examples": { "by_name": { "summary": "Nodes matching a provider name", "value": { "query": "cloudflare", "count": 2, "results": [ { "id": "/cdn/cloudflare", "name": "Cloudflare", "label": "Content Delivery Networks (CDNs) > Cloudflare", "type": "cdn", "ancestors": [ { "id": "/cdn", "name": "Content Delivery Networks (CDNs)", "type": "cdn" } ] }, { "id": "/cdn/cloudflare/cloudflare", "name": "Cloudflare", "label": "Content Delivery Networks (CDNs) > Cloudflare > Cloudflare", "type": "cdn", "ancestors": [ { "id": "/cdn", "name": "Content Delivery Networks (CDNs)", "type": "cdn" }, { "id": "/cdn/cloudflare", "name": "Cloudflare", "type": "cdn" } ] } ] } } } } } }, "400": { "description": "Bad Request - invalid parameters or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "validation_error": { "summary": "Request validation failed", "value": { "type": "/problems/validation-error", "title": "Validation Error", "status": 400, "detail": "Request validation failed", "instance": "/v1/edl/ip-rulesets/", "validation_errors": { "ip": [ "Invalid IP address or CIDR format" ] } } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key (rejected by the API gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "missing_key": { "summary": "No API key provided", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "No API key found in request", "instance": "/v1/edl/ip-rulesets/", "request_id": "61d9cf2a7fcf3d428cba7043efbe3342" } }, "invalid_key": { "summary": "Unknown or revoked API key", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Unauthorized", "instance": "/v1/edl/ip-rulesets/", "request_id": "5275cb5149a8a80a7d79ef6892066e0c" } } } } } }, "403": { "description": "Forbidden - insufficient API key permissions, no active plan for this service, or (with a request_id) rejected by the gateway access control.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "permission_denied": { "summary": "API key lacks the required permission", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "API key does not have 'read_write' permission for organization resources", "instance": "/v1/edl/ip-rulesets/" } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "/problems/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "API rate limit exceeded", "instance": "/v1/edl/ip-rulesets/", "request_id": "ca165c702f4dff31a01805e266a36e94" } } } } } }, "500": { "description": "Internal Server Error - an unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "internal_error": { "summary": "Unexpected server error", "value": { "type": "/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing your request" } } } } } } }, "description": "Scored text search over node name/path/metadata. Each result carries its `cbs_id` and breadcrumb so you can jump to `/node`. (Search IPs with `/lookup`.)\n\n**Required:** active CTI or blocklist plan.", "tags": [ "CBS" ], "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ] } }, "/v1/cti/lookup/{ip}": { "get": { "operationId": "ctiLookupIp", "summary": "IP lookup", "parameters": [ { "in": "path", "name": "ip", "schema": { "title": "Ip", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CTIDocument" }, "examples": { "seen": { "summary": "IP observed in telemetry", "value": { "ip": "203.0.113.7", "seen": true, "classification": "malicious", "actor": "unknown", "rdns": "host-203-0-113-7.example.net", "first_seen": "2025-11-02", "last_seen": "2026-07-01", "spoofable": false, "tags": [ "Fast Scanner", "Telnet Scanner" ], "tag_ids": [ "fast_scanner", "telnet_scanner" ] } }, "unseen": { "summary": "IP never observed", "value": { "ip": "192.0.2.10", "seen": false } } } } } }, "400": { "description": "Bad Request - invalid parameters or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "examples": { "invalid_ip": { "summary": "Invalid IP address format", "value": { "message": "Invalid IP address format", "request_id": "f8ba4e4c9d21314fbb9a439e8d40ee6c" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key (rejected by the API gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "missing_key": { "summary": "No API key provided", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "No API key found in request", "instance": "/v1/edl/ip-rulesets/", "request_id": "61d9cf2a7fcf3d428cba7043efbe3342" } }, "invalid_key": { "summary": "Unknown or revoked API key", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Unauthorized", "instance": "/v1/edl/ip-rulesets/", "request_id": "5275cb5149a8a80a7d79ef6892066e0c" } } } } } }, "403": { "description": "Forbidden - the API key's organization has no access to this service", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "no_service_access": { "summary": "API key not entitled to this service", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You cannot consume this service", "instance": "/v1/cti/lookup/198.51.100.7", "request_id": "9ce7b54aae858952381bef3dfe3aa207" } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "/problems/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "API rate limit exceeded", "instance": "/v1/edl/ip-rulesets/", "request_id": "ca165c702f4dff31a01805e266a36e94" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "examples": { "internal_error": { "summary": "Unexpected server error", "value": { "message": "Internal server error", "request_id": "5d8f1a2e3b7c9e0a41cc0e5b7de210af" } } } } } } }, "description": "Get basic information about an IP address including seen status, tags, actor, and classification. Returns `seen: false` when the IP has not been observed.\n\n**Required:** active CTI plan.\n\nRate limit status is reported via the X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Limit-Month, and X-RateLimit-Remaining-Month response headers.", "tags": [ "CTI Lookup" ], "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ] } }, "/v1/cti/extended_lookup/{ip}": { "get": { "operationId": "ctiExtendedLookupIp", "summary": "Extended IP lookup", "parameters": [ { "in": "path", "name": "ip", "schema": { "title": "Ip", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CTIExtendedDocument" }, "examples": { "seen": { "summary": "IP observed, with fingerprints, ports, geo, and HTTP data", "value": { "ip": "203.0.113.7", "seen": true, "classification": "malicious", "actor": "unknown", "rdns": "host-203-0-113-7.example.net", "first_seen": "2025-11-02", "last_seen": "2026-07-01", "spoofable": false, "tags": [ "Fast Scanner", "Telnet Scanner" ], "tag_ids": [ "fast_scanner", "telnet_scanner" ], "cve": [ "CVE-2021-44228" ], "fingerprints": { "ja3": [ "19e29534fd49dd27d09234e639c4057e" ], "ja4": [ "t13i190800_9dc949149365_97f8aa674fd9" ], "muonfp": [ "62727:2-4-8-1-3:1460:7" ] }, "network": { "ports": [ 23, 2323, 8080 ], "spoofable_ports": [ 23 ], "non_spoofable_ports": [ 2323, 8080 ] }, "http": { "path": [ "/", "/.git/config" ], "user_agent": [ "Go-http-client/1.1" ] }, "src": { "geo": { "country": { "name": "Czechia", "code": "CZ" }, "continent": { "name": "Europe", "code": "EU" } } }, "dst": { "geo": { "country": { "name": [ "Czechia", "United States" ], "code": [ "CZ", "US" ] }, "continent": { "name": [ "Europe", "North America" ], "code": [ "EU", "NA" ] } } } } }, "unseen": { "summary": "IP never observed", "value": { "ip": "192.0.2.10", "seen": false } } } } } }, "400": { "description": "Bad Request - invalid parameters or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "examples": { "invalid_ip": { "summary": "Invalid IP address format", "value": { "message": "Invalid IP address format", "request_id": "f8ba4e4c9d21314fbb9a439e8d40ee6c" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key (rejected by the API gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "missing_key": { "summary": "No API key provided", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "No API key found in request", "instance": "/v1/edl/ip-rulesets/", "request_id": "61d9cf2a7fcf3d428cba7043efbe3342" } }, "invalid_key": { "summary": "Unknown or revoked API key", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Unauthorized", "instance": "/v1/edl/ip-rulesets/", "request_id": "5275cb5149a8a80a7d79ef6892066e0c" } } } } } }, "403": { "description": "Forbidden - the API key's organization has no access to this service", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "no_service_access": { "summary": "API key not entitled to this service", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You cannot consume this service", "instance": "/v1/cti/lookup/198.51.100.7", "request_id": "9ce7b54aae858952381bef3dfe3aa207" } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "/problems/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "API rate limit exceeded", "instance": "/v1/edl/ip-rulesets/", "request_id": "ca165c702f4dff31a01805e266a36e94" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "examples": { "internal_error": { "summary": "Unexpected server error", "value": { "message": "Internal server error", "request_id": "5d8f1a2e3b7c9e0a41cc0e5b7de210af" } } } } } } }, "description": "Get comprehensive information about an IP address including all basic info plus fingerprints, network ports, geo information, and HTTP data. Returns `seen: false` when the IP has not been observed.\n\n**Required:** active CTI plan.\n\nRate limit status is reported via the X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Limit-Month, and X-RateLimit-Remaining-Month response headers.", "tags": [ "CTI Lookup" ], "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ] } }, "/v1/cti/bulk_lookup": { "post": { "operationId": "ctiBulkLookup", "summary": "Bulk IP lookup", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CTIBulkLookupResponse" }, "examples": { "mixed": { "summary": "Two valid IPs (one seen) and one invalid entry", "value": { "results": { "203.0.113.7": { "seen": true, "spoofable": false }, "192.0.2.10": { "seen": false } }, "count": 2, "seen_ips": 1, "invalid": [ "999.11.1.1" ] } } } } } }, "400": { "description": "Bad Request - invalid parameters or request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "examples": { "invalid_ip": { "summary": "Invalid IP address format", "value": { "message": "Invalid IP address format", "request_id": "f8ba4e4c9d21314fbb9a439e8d40ee6c" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key (rejected by the API gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "missing_key": { "summary": "No API key provided", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "No API key found in request", "instance": "/v1/edl/ip-rulesets/", "request_id": "61d9cf2a7fcf3d428cba7043efbe3342" } }, "invalid_key": { "summary": "Unknown or revoked API key", "value": { "type": "/problems/authentication-required", "title": "Authentication Required", "status": 401, "detail": "Unauthorized", "instance": "/v1/edl/ip-rulesets/", "request_id": "5275cb5149a8a80a7d79ef6892066e0c" } } } } } }, "403": { "description": "Forbidden - the API key's organization has no access to this service", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "no_service_access": { "summary": "API key not entitled to this service", "value": { "type": "/problems/permission-denied", "title": "Permission Denied", "status": 403, "detail": "You cannot consume this service", "instance": "/v1/cti/lookup/198.51.100.7", "request_id": "9ce7b54aae858952381bef3dfe3aa207" } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "examples": { "rate_limited": { "summary": "Rate limit exceeded", "value": { "type": "/problems/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "API rate limit exceeded", "instance": "/v1/edl/ip-rulesets/", "request_id": "ca165c702f4dff31a01805e266a36e94" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "examples": { "internal_error": { "summary": "Unexpected server error", "value": { "message": "Internal server error", "request_id": "5d8f1a2e3b7c9e0a41cc0e5b7de210af" } } } } } } }, "description": "Get minimal information (seen and spoofable status only) for multiple IP addresses in a single request.\n\n**Required:** active CTI plan.\n\nRate limit status is reported via the X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Limit-Month, and X-RateLimit-Remaining-Month response headers.", "tags": [ "CTI Lookup" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CTIBulkLookupRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ] } } }, "components": { "schemas": { "CheckIPAcrossRulesetsResponse": { "description": "Response for checking IP across all rulesets", "properties": { "ip": { "examples": [ "203.0.113.5" ], "title": "Ip", "type": "string" }, "found": { "examples": [ true, false ], "title": "Found", "type": "boolean" }, "ruleset_count": { "description": "Number of rulesets containing the IP", "examples": [ 2, 0 ], "title": "Ruleset Count", "type": "integer" }, "total_rule_count": { "description": "Total number of matching rules across all rulesets", "examples": [ 5, 0 ], "title": "Total Rule Count", "type": "integer" }, "rulesets": { "examples": [ [] ], "items": { "$ref": "#/components/schemas/RulesetMatch" }, "title": "Rulesets", "type": "array" } }, "required": [ "ip", "found", "ruleset_count", "total_rule_count", "rulesets" ], "title": "CheckIPAcrossRulesetsResponse", "type": "object" }, "RuleSchema": { "description": "IP Rule response schema", "properties": { "ip": { "examples": [ "203.0.113.1", "198.51.100.0/24" ], "title": "Ip", "type": "string" }, "name": { "examples": [ "Malicious IP from threat intel", "" ], "title": "Name", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "examples": [ "2026-12-31T23:59:59Z", null ], "title": "Expires At" }, "created_at": { "examples": [ "2024-01-15T10:30:00Z" ], "format": "date-time", "title": "Created At", "type": "string" }, "updated_at": { "examples": [ "2024-01-15T10:30:00Z" ], "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "ip", "name", "created_at", "updated_at" ], "title": "RuleSchema", "type": "object" }, "RulesetMatch": { "description": "Ruleset match information for cross-ruleset check", "properties": { "ruleset_id": { "examples": [ "dc658778-3b64-4fe9-a3b6-ca1dc264f2fa" ], "title": "Ruleset Id", "type": "string" }, "ruleset_name": { "examples": [ "Threat Intelligence Feed" ], "title": "Ruleset Name", "type": "string" }, "rule_count": { "description": "Number of matching rules in this ruleset", "examples": [ 3, 1 ], "title": "Rule Count", "type": "integer" }, "rules": { "examples": [ [] ], "items": { "$ref": "#/components/schemas/RuleSchema" }, "title": "Rules", "type": "array" } }, "required": [ "ruleset_id", "ruleset_name", "rule_count", "rules" ], "title": "RulesetMatch", "type": "object" }, "ProblemDetail": { "description": "RFC 9457 Problem Details schema", "properties": { "type": { "title": "Type", "type": "string" }, "title": { "title": "Title", "type": "string" }, "status": { "title": "Status", "type": "integer" }, "detail": { "title": "Detail", "type": "string" }, "instance": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instance" }, "validation_errors": { "anyOf": [ { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object" }, { "type": "null" } ], "title": "Validation Errors" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request identifier, present on errors emitted by the API gateway (authentication, access control, rate limiting, upstream failures). Include it when contacting support.", "title": "Request Id" } }, "required": [ "type", "title", "status", "detail" ], "title": "ProblemDetail", "type": "object" }, "CheckIPRequest": { "description": "Request to check if an IP exists in ruleset(s)", "properties": { "ip": { "description": "IPv4/IPv6 address or CIDR to check", "examples": [ "203.0.113.1", "203.0.113.0/24", "2001:db8::1", "2001:db8::/64" ], "minLength": 1, "oneOf": [ { "format": "ipv4", "type": "string" }, { "format": "ipv6", "type": "string" }, { "pattern": "^(?:\\d{1,3}\\.){3}\\d{1,3}/(?:[0-9]|[1-2][0-9]|3[0-2])$", "type": "string" }, { "pattern": "^[0-9A-Fa-f:]+/(?:\\d|[1-9]\\d|1[01]\\d|12[0-8])$", "type": "string" } ], "title": "Ip", "type": "string" } }, "required": [ "ip" ], "title": "CheckIPRequest", "type": "object" }, "CheckIPInRulesetResponse": { "description": "Response for checking IP in a specific ruleset", "properties": { "ip": { "examples": [ "203.0.113.5" ], "title": "Ip", "type": "string" }, "found": { "examples": [ true, false ], "title": "Found", "type": "boolean" }, "rule_count": { "description": "Number of matching rules", "examples": [ 2, 0 ], "title": "Rule Count", "type": "integer" }, "matching_rules": { "examples": [ [] ], "items": { "$ref": "#/components/schemas/RuleSchema" }, "title": "Matching Rules", "type": "array" } }, "required": [ "ip", "found", "rule_count", "matching_rules" ], "title": "CheckIPInRulesetResponse", "type": "object" }, "Input": { "properties": { "page": { "default": 1, "description": "Page number (minimum 1)", "minimum": 1, "title": "Page", "type": "integer" } }, "title": "Input", "type": "object" }, "PagedRuleSchema": { "properties": { "items": { "items": { "$ref": "#/components/schemas/RuleSchema" }, "title": "Items", "type": "array" }, "count": { "title": "Count", "type": "integer" }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next" }, "prev": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prev" } }, "required": [ "items", "count" ], "title": "PagedRuleSchema", "type": "object" }, "AddRuleResponse": { "description": "Response for adding a single IP rule", "properties": { "action": { "description": "Action taken: created (new rule), updated (modified existing), skipped (no change)", "enum": [ "created", "updated", "skipped" ], "examples": [ "created", "updated", "skipped" ], "title": "Action", "type": "string" }, "rule": { "$ref": "#/components/schemas/RuleSchema", "description": "The IP rule" } }, "required": [ "action", "rule" ], "title": "AddRuleResponse", "type": "object" }, "AddIPRequest": { "description": "Request to add a single IP to a ruleset", "examples": [ { "conflict_resolution": "extend", "expires_in_days": 30, "ip": "203.0.113.1", "name": "Malicious IP from threat intel" }, { "conflict_resolution": "override", "expires_at": "2026-12-31T23:59:59Z", "ip": "198.51.100.0/24", "name": "Botnet C2 network" }, { "conflict_resolution": "fail", "ip": "2001:db8::1", "name": "Permanent block" } ], "not": { "allOf": [ { "required": [ "expires_in_days" ] }, { "required": [ "expires_at" ] } ] }, "properties": { "expires_in_days": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "description": "Number of days until expiration (mutually exclusive with expires_at)", "examples": [ 30, 7, 90 ], "title": "Expires In Days" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Explicit expiration date in UTC (mutually exclusive with expires_in_days)", "examples": [ "2026-12-31T23:59:59Z" ], "title": "Expires At" }, "ip": { "description": "IPv4/IPv6 address or CIDR", "examples": [ "203.0.113.1", "2001:db8::1", "198.51.100.0/24", "2001:db8::/64" ], "minLength": 1, "oneOf": [ { "format": "ipv4", "type": "string" }, { "format": "ipv6", "type": "string" }, { "pattern": "^(?:\\d{1,3}\\.){3}\\d{1,3}/(?:[0-9]|[1-2][0-9]|3[0-2])$", "type": "string" }, { "pattern": "^[0-9A-Fa-f:]+/(?:\\d|[1-9]\\d|1[01]\\d|12[0-8])$", "type": "string" } ], "title": "Ip", "type": "string" }, "name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": "", "description": "Optional descriptive name for the IP rule", "examples": [ "Malicious IP from threat intel", "Botnet C2 server" ], "title": "Name" }, "conflict_resolution": { "default": "extend", "description": "How to handle conflicts with existing IPs:\n- extend: Keep the longer expiration date\n- override: Replace existing rule completely\n- skip: Keep existing rule unchanged\n- fail: Return error if IP already exists", "enum": [ "extend", "override", "skip", "fail" ], "examples": [ "extend", "override", "skip", "fail" ], "title": "Conflict Resolution", "type": "string" } }, "required": [ "ip" ], "title": "AddIPRequest", "type": "object" }, "UpdateRuleRequest": { "description": "Request to update an existing rule", "examples": [ { "expires_in_days": 90, "name": "Updated threat description" }, { "expires_at": "2027-06-30T23:59:59Z" }, { "name": "False positive - now verified safe" } ], "not": { "allOf": [ { "required": [ "expires_in_days" ] }, { "required": [ "expires_at" ] } ] }, "properties": { "expires_in_days": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "description": "Number of days until expiration (mutually exclusive with expires_at)", "examples": [ 30, 7, 90 ], "title": "Expires In Days" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Explicit expiration date in UTC (mutually exclusive with expires_in_days)", "examples": [ "2026-12-31T23:59:59Z" ], "title": "Expires At" }, "name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "examples": [ "Updated threat description" ], "title": "Name" } }, "title": "UpdateRuleRequest", "type": "object" }, "BatchOperationResponse": { "description": "Response for batch operations", "properties": { "action": { "examples": [ "add", "remove", "update" ], "title": "Action", "type": "string" }, "summary": { "$ref": "#/components/schemas/BatchOperationSummary" }, "details": { "anyOf": [ { "items": { "type": "object" }, "type": "array" }, { "type": "null" } ], "examples": [ [] ], "title": "Details" } }, "required": [ "action", "summary" ], "title": "BatchOperationResponse", "type": "object" }, "BatchOperationSummary": { "description": "Summary of batch operation results", "properties": { "added": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "examples": [ 50 ], "title": "Added" }, "updated": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "examples": [ 10 ], "title": "Updated" }, "removed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "examples": [ 25 ], "title": "Removed" }, "skipped": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "examples": [ 5 ], "title": "Skipped" }, "failed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "examples": [ 0 ], "title": "Failed" }, "requested": { "examples": [ 100 ], "title": "Requested", "type": "integer" } }, "required": [ "requested" ], "title": "BatchOperationSummary", "type": "object" }, "BatchOperationRequest": { "description": "Request for batch operations on multiple IPs", "examples": [ { "action": "add", "conflict_resolution": "extend", "expires_in_days": 30, "ips": [ "203.0.113.1", "203.0.113.2", "203.0.113.3" ], "name": "Threat actor IPs" }, { "action": "remove", "ips": [ "203.0.113.1", "203.0.113.2" ] }, { "action": "update", "expires_in_days": 90, "ips": [ "203.0.113.1" ], "name": "Updated threat description" } ], "not": { "allOf": [ { "required": [ "expires_in_days" ] }, { "required": [ "expires_at" ] } ] }, "properties": { "expires_in_days": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "description": "Number of days until expiration (mutually exclusive with expires_at)", "examples": [ 30, 7, 90 ], "title": "Expires In Days" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Explicit expiration date in UTC (mutually exclusive with expires_in_days)", "examples": [ "2026-12-31T23:59:59Z" ], "title": "Expires At" }, "action": { "description": "Batch operation type", "enum": [ "add", "remove", "update" ], "examples": [ "add", "remove", "update" ], "title": "Action", "type": "string" }, "ips": { "description": "List of IPv4/IPv6 addresses or CIDRs", "examples": [ [ "203.0.113.1", "198.51.100.0/24", "2001:db8::1" ] ], "items": { "type": "string" }, "maxItems": 1000000, "minItems": 1, "title": "Ips", "type": "array" }, "name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Common name for all IPs (applies to add/update operations)", "examples": [ "Threat actor IPs" ], "title": "Name" }, "conflict_resolution": { "anyOf": [ { "enum": [ "extend", "override", "skip", "fail" ], "type": "string" }, { "type": "null" } ], "default": "extend", "description": "Conflict resolution strategy for add operations", "examples": [ "extend" ], "title": "Conflict Resolution" }, "verbose": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "description": "Return detailed information about each operation", "examples": [ true, false ], "title": "Verbose" } }, "required": [ "action", "ips" ], "title": "BatchOperationRequest", "type": "object" }, "ExpireRulesResponse": { "description": "Response for expire rules operation", "properties": { "threshold": { "description": "The threshold that was applied", "examples": [ "5h" ], "title": "Threshold", "type": "string" }, "cutoff_time": { "description": "Rules with expires_at in range [now, cutoff_time) were affected", "examples": [ "2024-01-15T15:30:00Z" ], "format": "date-time", "title": "Cutoff Time", "type": "string" }, "expired_count": { "description": "Number of rules expired (0 if dry_run)", "examples": [ 150 ], "title": "Expired Count", "type": "integer" }, "dry_run": { "description": "Whether this was a dry run", "examples": [ false ], "title": "Dry Run", "type": "boolean" } }, "required": [ "threshold", "cutoff_time", "expired_count", "dry_run" ], "title": "ExpireRulesResponse", "type": "object" }, "ExpireRulesRequest": { "description": "Request to expire rules within a time threshold.\n\nAccepts human-readable time formats:\n- \"5h\", \"5 hours\", \"5hr\"\n- \"10d\", \"10 days\"\n- \"2w\", \"2 weeks\"\n\nAll rules with expires_at < now + threshold will be expired.", "examples": [ { "dry_run": true, "threshold": "5h" }, { "dry_run": false, "threshold": "10 days" }, { "threshold": "2 weeks" } ], "properties": { "threshold": { "description": "Time threshold in human-readable format. Rules expiring before (now + threshold) will be deleted. Examples: '5h', '10 days', '2 weeks', '1 day 5 hours'", "examples": [ "5h", "10 days", "2 weeks" ], "title": "Threshold", "type": "string" }, "dry_run": { "default": false, "description": "If true, return count of rules that would be expired without deleting", "examples": [ true, false ], "title": "Dry Run", "type": "boolean" } }, "required": [ "threshold" ], "title": "ExpireRulesRequest", "type": "object" }, "PagedRulesetSchema": { "properties": { "items": { "items": { "$ref": "#/components/schemas/RulesetSchema" }, "title": "Items", "type": "array" }, "count": { "title": "Count", "type": "integer" }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next" }, "prev": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prev" } }, "required": [ "items", "count" ], "title": "PagedRulesetSchema", "type": "object" }, "RulesetSchema": { "description": "Ruleset response schema", "properties": { "id": { "examples": [ "dc658778-3b64-4fe9-a3b6-ca1dc264f2fa" ], "format": "uuid", "title": "Id", "type": "string" }, "name": { "examples": [ "Threat Intelligence Feed", "Global Blocklist" ], "title": "Name", "type": "string" }, "purpose": { "enum": [ "blocklist", "allowlist" ], "examples": [ "blocklist", "allowlist" ], "title": "Purpose", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "IPs from threat intelligence sources", null ], "title": "Description" }, "total_rules": { "description": "Total number of rules in ruleset", "examples": [ 1523 ], "title": "Total Rules", "type": "integer" }, "active_rules": { "description": "Number of active (non-expired) rules", "examples": [ 1450 ], "title": "Active Rules", "type": "integer" }, "created_at": { "examples": [ "2024-01-15T10:30:00Z" ], "format": "date-time", "title": "Created At", "type": "string" }, "updated_at": { "examples": [ "2024-01-15T10:30:00Z" ], "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "name", "purpose", "total_rules", "active_rules", "created_at", "updated_at" ], "title": "RulesetSchema", "type": "object" }, "CBSLookupResponse": { "description": "IP -> CBS classification (served by the cbs-lookup edge service).", "properties": { "ip": { "title": "Ip", "type": "string" }, "found": { "title": "Found", "type": "boolean" }, "cidr": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cidr" }, "labels": { "default": [], "items": { "type": "string" }, "title": "Labels", "type": "array" }, "cbs_ids": { "default": [], "items": { "type": "string" }, "title": "Cbs Ids", "type": "array" }, "providers": { "default": [], "items": { "type": "string" }, "title": "Providers", "type": "array" }, "types": { "default": [], "items": { "type": "string" }, "title": "Types", "type": "array" }, "services": { "default": [], "items": { "type": "string" }, "title": "Services", "type": "array" }, "regions": { "default": [], "items": { "type": "string" }, "title": "Regions", "type": "array" }, "matches": { "default": [], "items": { "$ref": "#/components/schemas/CBSMatchSchema" }, "title": "Matches", "type": "array" } }, "required": [ "ip", "found" ], "title": "CBSLookupResponse", "type": "object" }, "CBSMatchSchema": { "description": "One structured (provider, type, service, region) classification for a CIDR.", "properties": { "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" }, "service": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service" }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Region" } }, "title": "CBSMatchSchema", "type": "object" }, "CBSBulkLookupRequest": { "properties": { "ips": { "items": { "type": "string" }, "title": "Ips", "type": "array" } }, "required": [ "ips" ], "title": "CBSBulkLookupRequest", "type": "object" }, "CBSBreadcrumbSchema": { "description": "An ancestor reference (breadcrumb). No `has_children` -- an ancestor\nalways has a child, so the flag would be meaningless here.", "properties": { "id": { "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" } }, "required": [ "id", "name" ], "title": "CBSBreadcrumbSchema", "type": "object" }, "CBSCountsSchema": { "properties": { "ipv4_entries": { "default": 0, "title": "Ipv4 Entries", "type": "integer" }, "ipv6_entries": { "default": 0, "title": "Ipv6 Entries", "type": "integer" }, "ipv4_addresses": { "default": "0", "title": "Ipv4 Addresses", "type": "string" }, "ipv6_addresses": { "default": "0", "title": "Ipv6 Addresses", "type": "string" } }, "title": "CBSCountsSchema", "type": "object" }, "CBSNodeDetailSchema": { "properties": { "id": { "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "label": { "title": "Label", "type": "string" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" }, "service": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service" }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Region" }, "direction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Direction" }, "tooltip": { "default": "", "title": "Tooltip", "type": "string" }, "description": { "default": "", "title": "Description", "type": "string" }, "references": { "default": [], "items": { "$ref": "#/components/schemas/CBSReferenceSchema" }, "title": "References", "type": "array" }, "metadata": { "default": {}, "title": "Metadata", "type": "object" }, "counts": { "$ref": "#/components/schemas/CBSCountsSchema" }, "ancestors": { "default": [], "items": { "$ref": "#/components/schemas/CBSBreadcrumbSchema" }, "title": "Ancestors", "type": "array" }, "children": { "default": [], "items": { "$ref": "#/components/schemas/CBSNodeRefSchema" }, "title": "Children", "type": "array" }, "deprecated": { "default": false, "title": "Deprecated", "type": "boolean" }, "last_updated": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Updated" } }, "required": [ "id", "name", "label", "counts" ], "title": "CBSNodeDetailSchema", "type": "object" }, "CBSNodeRefSchema": { "description": "A child reference: id + category + whether it can be drilled into.", "properties": { "id": { "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" }, "has_children": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Children" } }, "required": [ "id", "name" ], "title": "CBSNodeRefSchema", "type": "object" }, "CBSReferenceSchema": { "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" } }, "title": "CBSReferenceSchema", "type": "object" }, "CBSRangesResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "ranges": { "items": { "type": "string" }, "title": "Ranges", "type": "array" }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Page Token" } }, "required": [ "id", "ranges" ], "title": "CBSRangesResponse", "type": "object" }, "CBSSearchResponse": { "properties": { "query": { "title": "Query", "type": "string" }, "count": { "title": "Count", "type": "integer" }, "results": { "items": { "$ref": "#/components/schemas/CBSSearchResultSchema" }, "title": "Results", "type": "array" } }, "required": [ "query", "count", "results" ], "title": "CBSSearchResponse", "type": "object" }, "CBSSearchResultSchema": { "properties": { "id": { "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "label": { "title": "Label", "type": "string" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" }, "ancestors": { "default": [], "items": { "$ref": "#/components/schemas/CBSBreadcrumbSchema" }, "title": "Ancestors", "type": "array" } }, "required": [ "id", "name", "label" ], "title": "CBSSearchResultSchema", "type": "object" }, "CTIDocument": { "description": "Basic CTI information about an IP address.", "properties": { "ip": { "description": "The IP address being queried", "examples": [ "198.51.100.7" ], "title": "Ip", "type": "string" }, "seen": { "description": "Whether the IP has been observed in our telemetry", "examples": [ true ], "title": "Seen", "type": "boolean" }, "classification": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Classification of the IP (benign/malicious/unknown)", "examples": [ "malicious" ], "title": "Classification" }, "actor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Associated actor or organization, if known", "examples": [ "unknown" ], "title": "Actor" }, "rdns": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reverse DNS record for the IP address", "examples": [ "host-198-51-100-7.example.net" ], "title": "Rdns" }, "first_seen": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "First date when this IP was observed (YYYY-MM-DD)", "title": "First Seen" }, "last_seen": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Last date when this IP was observed (YYYY-MM-DD)", "title": "Last Seen" }, "spoofable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether traffic from this IP is spoofable; omitted when unknown", "examples": [ false ], "title": "Spoofable" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Human-readable tags describing the IP's behavior", "examples": [ [ "AWS Cloud", "Fast Scanner" ] ], "title": "Tags" }, "tag_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Machine-readable tag identifiers", "examples": [ [ "aws_cloud", "fast_scanner" ] ], "title": "Tag Ids" } }, "required": [ "ip", "seen" ], "title": "CTIDocument", "type": "object" }, "GatewayError": { "description": "Error emitted by the CTI IP lookup service (400/500 on /v1/cti/*).", "properties": { "message": { "description": "Human-readable error description", "examples": [ "No API key found in request" ], "title": "Message", "type": "string" }, "request_id": { "description": "Unique identifier for the request, useful for troubleshooting", "examples": [ "61d9cf2a7fcf3d428cba7043efbe3342" ], "title": "Request Id", "type": "string" } }, "required": [ "message", "request_id" ], "title": "GatewayError", "type": "object" }, "CTIContinentArrayInfo": { "properties": { "name": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Continent names", "examples": [ [ "Europe", "North America" ] ], "title": "Name" }, "code": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "ISO continent codes", "examples": [ [ "EU", "NA" ] ], "title": "Code" } }, "title": "CTIContinentArrayInfo", "type": "object" }, "CTIContinentInfo": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Continent name", "examples": [ "Asia" ], "title": "Name" }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO continent code", "examples": [ "AS" ], "title": "Code" } }, "title": "CTIContinentInfo", "type": "object" }, "CTICountryArrayInfo": { "properties": { "name": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Country names", "examples": [ [ "Czechia", "United States" ] ], "title": "Name" }, "code": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "ISO country codes", "examples": [ [ "CZ", "US" ] ], "title": "Code" } }, "title": "CTICountryArrayInfo", "type": "object" }, "CTICountryInfo": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Country name", "examples": [ "Singapore" ], "title": "Name" }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO country code", "examples": [ "SG" ], "title": "Code" } }, "title": "CTICountryInfo", "type": "object" }, "CTIDestinationGeo": { "properties": { "geo": { "anyOf": [ { "$ref": "#/components/schemas/CTIGeoArrayInfo" }, { "type": "null" } ], "description": "Geographical information about destinations" } }, "title": "CTIDestinationGeo", "type": "object" }, "CTIExtendedDocument": { "description": "Extended CTI information: basic document plus fingerprints, ports, geo, and HTTP data.", "properties": { "ip": { "description": "The IP address being queried", "examples": [ "198.51.100.7" ], "title": "Ip", "type": "string" }, "seen": { "description": "Whether the IP has been observed in our telemetry", "examples": [ true ], "title": "Seen", "type": "boolean" }, "classification": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Classification of the IP (benign/malicious/unknown)", "examples": [ "malicious" ], "title": "Classification" }, "actor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Associated actor or organization, if known", "examples": [ "unknown" ], "title": "Actor" }, "rdns": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reverse DNS record for the IP address", "examples": [ "host-198-51-100-7.example.net" ], "title": "Rdns" }, "first_seen": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "First date when this IP was observed (YYYY-MM-DD)", "title": "First Seen" }, "last_seen": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Last date when this IP was observed (YYYY-MM-DD)", "title": "Last Seen" }, "spoofable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether traffic from this IP is spoofable; omitted when unknown", "examples": [ false ], "title": "Spoofable" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Human-readable tags describing the IP's behavior", "examples": [ [ "AWS Cloud", "Fast Scanner" ] ], "title": "Tags" }, "tag_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Machine-readable tag identifiers", "examples": [ [ "aws_cloud", "fast_scanner" ] ], "title": "Tag Ids" }, "cve": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "CVE references associated with this IP's observed activity", "examples": [ [ "CVE-2021-44228", "CVE-2021-26084" ] ], "title": "Cve" }, "fingerprints": { "anyOf": [ { "$ref": "#/components/schemas/CTIFingerprints" }, { "type": "null" } ], "description": "TLS fingerprints observed from this IP" }, "network": { "anyOf": [ { "$ref": "#/components/schemas/CTINetwork" }, { "type": "null" } ], "description": "Network port information" }, "http": { "anyOf": [ { "$ref": "#/components/schemas/CTIHTTPInfo" }, { "type": "null" } ], "description": "HTTP request information" }, "src": { "anyOf": [ { "$ref": "#/components/schemas/CTISourceGeo" }, { "type": "null" } ], "description": "Source geographical information" }, "dst": { "anyOf": [ { "$ref": "#/components/schemas/CTIDestinationGeo" }, { "type": "null" } ], "description": "Destination geographical information" } }, "required": [ "ip", "seen" ], "title": "CTIExtendedDocument", "type": "object" }, "CTIFingerprints": { "description": "TLS and TCP fingerprints observed from an IP.", "properties": { "ja3": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "JA3 TLS fingerprints", "examples": [ [ "19e29534fd49dd27d09234e639c4057e" ] ], "title": "Ja3" }, "ja4": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "JA4 TLS fingerprints", "examples": [ [ "t13i190800_9dc949149365_97f8aa674fd9" ] ], "title": "Ja4" }, "muonfp": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "MuonFP fingerprints", "examples": [ [ "62727:2-4-8-1-3:1460:7" ] ], "title": "Muonfp" } }, "title": "CTIFingerprints", "type": "object" }, "CTIGeoArrayInfo": { "properties": { "country": { "anyOf": [ { "$ref": "#/components/schemas/CTICountryArrayInfo" }, { "type": "null" } ], "description": "Country information" }, "continent": { "anyOf": [ { "$ref": "#/components/schemas/CTIContinentArrayInfo" }, { "type": "null" } ], "description": "Continent information" } }, "title": "CTIGeoArrayInfo", "type": "object" }, "CTIGeoInfo": { "properties": { "country": { "anyOf": [ { "$ref": "#/components/schemas/CTICountryInfo" }, { "type": "null" } ], "description": "Country information" }, "continent": { "anyOf": [ { "$ref": "#/components/schemas/CTIContinentInfo" }, { "type": "null" } ], "description": "Continent information" } }, "title": "CTIGeoInfo", "type": "object" }, "CTIHTTPInfo": { "description": "HTTP request behavior observed from an IP.", "properties": { "path": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "HTTP paths requested by this IP", "examples": [ [ "/.git/config", "/info.php" ] ], "title": "Path" }, "user_agent": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "User-Agent strings seen from this IP", "examples": [ [ "Go-http-client/1.1" ] ], "title": "User Agent" } }, "title": "CTIHTTPInfo", "type": "object" }, "CTINetwork": { "description": "Network port information observed for an IP.", "properties": { "ports": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "description": "All observed network ports", "examples": [ [ 8080 ] ], "title": "Ports" }, "spoofable_ports": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "description": "Network ports that may be spoofable", "examples": [ [ 80 ] ], "title": "Spoofable Ports" }, "non_spoofable_ports": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "description": "Network ports verified as non-spoofable", "examples": [ [ 8080 ] ], "title": "Non Spoofable Ports" } }, "title": "CTINetwork", "type": "object" }, "CTISourceGeo": { "properties": { "geo": { "anyOf": [ { "$ref": "#/components/schemas/CTIGeoInfo" }, { "type": "null" } ], "description": "Geographical information about the source" } }, "title": "CTISourceGeo", "type": "object" }, "CTIBulkLookupResponse": { "properties": { "results": { "additionalProperties": { "$ref": "#/components/schemas/CTIMinimalDocument" }, "description": "Map of IP address to minimal document info", "title": "Results", "type": "object" }, "count": { "description": "Count of IPs processed", "examples": [ 2 ], "title": "Count", "type": "integer" }, "seen_ips": { "description": "Count of IPs that were found in our telemetry (seen=true)", "examples": [ 1 ], "title": "Seen Ips", "type": "integer" }, "invalid": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "IPs that failed validation or processing", "examples": [ [ "999.11.1.1" ] ], "title": "Invalid" } }, "required": [ "results", "count", "seen_ips" ], "title": "CTIBulkLookupResponse", "type": "object" }, "CTIMinimalDocument": { "description": "Minimal per-IP result in a bulk lookup response.", "properties": { "seen": { "description": "Whether the IP has been observed in our telemetry", "examples": [ true ], "title": "Seen", "type": "boolean" }, "spoofable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether traffic from this IP is spoofable; omitted when unknown", "examples": [ false ], "title": "Spoofable" } }, "required": [ "seen" ], "title": "CTIMinimalDocument", "type": "object" }, "CTIBulkLookupRequest": { "properties": { "ips": { "description": "IP addresses to look up", "examples": [ [ "198.51.100.7", "203.0.113.9" ] ], "items": { "type": "string" }, "title": "Ips", "type": "array" } }, "required": [ "ips" ], "title": "CTIBulkLookupRequest", "type": "object" } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "description": "API key for authentication. Include your API key in the X-API-Key header or as an 'apikey' query parameter. Obtain your API key from your organization settings in the ELLIO dashboard.", "in": "header", "name": "X-API-Key" }, "ApiKeyQuery": { "type": "apiKey", "in": "query", "name": "apikey", "description": "API key as the 'apikey' query parameter. Preferred by the in-browser playground (header auth fails the API's CORS preflight); non-browser clients should use the X-API-Key header." } } }, "servers": [ { "url": "https://api.ellio.tech", "description": "Production" } ], "tags": [ { "name": "CTI Lookup", "description": "Look up IPs against the ELLIO Deception Network - single, extended, and bulk." }, { "name": "CBS", "description": "Common Business Services: classify IPs against curated provider ranges, browse nodes, and search by name." }, { "name": "IP Rulesets", "description": "Manage rulesets and the rules inside them: CRUD, batch operations, expiry, and membership checks." } ], "x-tagGroups": [ { "name": "Threat Intelligence - CTI", "tags": [ "CTI Lookup" ] }, { "name": "Common Business Services - CBS", "tags": [ "CBS" ] }, { "name": "Blocklist Automation - EDL", "tags": [ "IP Rulesets" ] } ] }