{ "openapi": "3.0.3", "info": { "title": "Profundis Teams scoped service API", "version": "2026-10-30", "description": "Organization service-key API. Separate from personal /api/v2/common and browser-session APIs. Search and asset jobs are asynchronous; continuous monitoring uses the recon stream. Credit ceilings and idempotency apply at admission." }, "servers": [ { "url": "https://api.profundis.io", "description": "Production" } ], "security": [ { "ServiceBearer": [] } ], "tags": [ { "name": "Identity" }, { "name": "Search and jobs" }, { "name": "Asset tools" }, { "name": "Exports" }, { "name": "Cases and reports" }, { "name": "Monitoring" }, { "name": "Webhooks" } ], "paths": { "/api/v2/service/whoami": { "get": { "tags": [ "Identity" ], "summary": "Inspect the current service key", "operationId": "get_api_v2_service_whoami", "description": "Free introspection. Use organization_id, scopes and clients to select the explicit context. The integration ceiling is not a guarantee of organization or client budget.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Whoami" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/search/{engine}": { "post": { "tags": [ "Search and jobs" ], "summary": "Start a dataset or unified search", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_search_engine", "x-required-scope": "search:read", "description": "search:read. Granular engines use SearchQuery; unified uses UnifiedQuery; unified-more uses UnifiedMoreQuery. Jobs reserve credits once and can be polled without a new search.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "engine", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "hosts", "dns", "vhosts", "whois", "unified", "unified-more" ] } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 120 }, "description": "Reuse this key with the identical request after an uncertain outcome." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SearchQuery" }, { "$ref": "#/components/schemas/UnifiedQuery" }, { "$ref": "#/components/schemas/UnifiedMoreQuery" } ] }, "examples": { "hosts": { "value": { "raw_query": "host:example.com", "page": 1, "results_per_page": 10 } }, "dns": { "value": { "raw_query": "host:example.com", "page": 1, "results_per_page": 10 } }, "vhosts": { "value": { "raw_query": "san:example.com", "page": 1, "results_per_page": 10 } }, "whois": { "value": { "raw_query": "domain:example.com", "page": 1, "results_per_page": 10 } }, "unified": { "value": { "raw_query": "example.com", "per_type_limit": 1 } } } } } }, "responses": { "202": { "description": "Accepted as an asynchronous job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobSubmission" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/batches": { "post": { "tags": [ "Search and jobs" ], "summary": "Submit or quote a bounded search batch", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_batches", "x-required-scope": "search:read", "description": "Use dry_run=true for a free quote (200 BatchQuote, no reservation or Idempotency-Key). Without dry_run, Idempotency-Key is required and the maximum is reserved atomically.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 16, "maxLength": 120 }, "description": "Reuse this key with the identical request after an uncertain outcome." }, { "name": "dry_run", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "true quotes without enqueue or credit reservation" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRequest" } } } }, "responses": { "200": { "description": "Free batch quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchQuote" } } } }, "202": { "description": "Accepted as an asynchronous job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchView" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Search and jobs" ], "summary": "List accessible batches", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_batches", "x-required-scope": "search:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BatchView" } } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/batches/{batch_id}": { "get": { "tags": [ "Search and jobs" ], "summary": "Read batch and item states", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_batches_batch_id", "x-required-scope": "search:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchView" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/batches/{batch_id}/cancel": { "post": { "tags": [ "Search and jobs" ], "summary": "Cancel unfinished batch items", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_batches_batch_id_cancel", "x-required-scope": "search:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Completed without a response body" }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/batches/{batch_id}/retry": { "post": { "tags": [ "Search and jobs" ], "summary": "Retry selected failed or cancelled items", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_batches_batch_id_retry", "x-required-scope": "search:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 120 }, "description": "Reuse this key with the identical request after an uncertain outcome." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRetry" } } } }, "responses": { "202": { "description": "Accepted as an asynchronous job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchView" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/jobs": { "get": { "tags": [ "Search and jobs" ], "summary": "List accessible jobs", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_jobs", "x-required-scope": [ "search:read", "tools:execute", "exports:create", "reports:render", "watches:write" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/jobs/{job_id}": { "get": { "tags": [ "Search and jobs" ], "summary": "Read job state", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_jobs_job_id", "x-required-scope": [ "search:read", "tools:execute", "exports:create", "reports:render", "watches:write" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/jobs/{job_id}/result": { "get": { "tags": [ "Search and jobs" ], "summary": "Read completed job result", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_jobs_job_id_result", "x-required-scope": [ "search:read", "tools:execute", "exports:create", "reports:render", "watches:write" ], "description": "Reading a completed result never launches another job or charges search credits.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/jobs/{job_id}/cancel": { "post": { "tags": [ "Search and jobs" ], "summary": "Cancel a manageable unfinished job", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_jobs_job_id_cancel", "x-required-scope": [ "search:read", "tools:execute", "exports:create", "reports:render", "watches:write" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Completed without a response body" }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/saved-queries": { "get": { "tags": [ "Search and jobs" ], "summary": "List saved query recipes", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_saved_queries", "x-required-scope": "search:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/saved-queries/{query_id}": { "get": { "tags": [ "Search and jobs" ], "summary": "Read a saved query recipe", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_saved_queries_query_id", "x-required-scope": "search:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "query_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/tools/{tool}": { "post": { "tags": [ "Asset tools" ], "summary": "Run a bounded asset tool", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_tools_tool", "x-required-scope": "tools:execute", "description": "Supported tools: domain, ip, network, subdomains, favicon-extract, favicon-search, favicon-widen, pivot, pivot-multi, pivot-explore, analytics, pipeline, portfolio. Check current pricing or supply max_credits where supported.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "tool", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "domain", "ip", "network", "subdomains", "favicon-extract", "favicon-search", "favicon-widen", "pivot", "pivot-multi", "pivot-explore", "analytics", "pipeline", "portfolio" ] } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 120 }, "description": "Reuse this key with the identical request after an uncertain outcome." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Input depends on tool; see the Service API guide for each tool and its ceiling." } } } }, "responses": { "202": { "description": "Accepted as an asynchronous job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSubmission" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/pivot/pricing": { "get": { "tags": [ "Asset tools" ], "summary": "Read Pivot prices", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_pivot_pricing", "x-required-scope": "tools:execute", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/favicons/pricing": { "get": { "tags": [ "Asset tools" ], "summary": "Read favicon similarity prices", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_favicons_pricing", "x-required-scope": "tools:execute", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/favicons/{source_id}/bands/{band}/quote": { "get": { "tags": [ "Asset tools" ], "summary": "Quote a favicon band", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_favicons_source_id_bands_band_quote", "x-required-scope": "tools:execute", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "band", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/export-limits": { "get": { "tags": [ "Exports" ], "summary": "Read private export limits", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_export_limits", "x-required-scope": "exports:create", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/exports": { "get": { "tags": [ "Exports" ], "summary": "List private exports", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_exports", "x-required-scope": "exports:create", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Exports" ], "summary": "Start a bounded private export", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_exports", "x-required-scope": "exports:create", "description": "Maximum reservation is ceil(max_results / 100); actual charge uses exported rows.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 120 }, "description": "Reuse this key with the identical request after an uncertain outcome." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRequest" } } } }, "responses": { "202": { "description": "Accepted as an asynchronous job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/exports/{export_id}": { "get": { "tags": [ "Exports" ], "summary": "Read export state", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_exports_export_id", "x-required-scope": "exports:create", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "export_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Exports" ], "summary": "Cancel or delete a private export", "operationId": "delete_api_v2_service_organizations_organization_id_clients_client_id_exports_export_id", "x-required-scope": "exports:create", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "export_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Completed without a response body" }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/exports/{export_id}/download": { "get": { "tags": [ "Exports" ], "summary": "Download a completed private export", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_exports_export_id_download", "x-required-scope": "exports:create", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "export_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/cases": { "post": { "tags": [ "Cases and reports" ], "summary": "Create an internal or client-visible case", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_cases", "x-required-scope": "cases:write", "description": "Client-visible case or evidence writes additionally require cases:share. Machine writes do not publish reports.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 120 }, "description": "Reuse this key with the identical request after an uncertain outcome." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseCreate" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Cases and reports" ], "summary": "List cases", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_cases", "x-required-scope": "cases:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/cases/{case_id}": { "patch": { "tags": [ "Cases and reports" ], "summary": "Edit a case", "operationId": "patch_api_v2_service_organizations_organization_id_clients_client_id_cases_case_id", "x-required-scope": "cases:write", "description": "Client-visible case or evidence writes additionally require cases:share. Machine writes do not publish reports.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quote the exact current resource version." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseEdit" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Cases and reports" ], "summary": "Read a case", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_cases_case_id", "x-required-scope": "cases:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/cases/{case_id}/comments": { "post": { "tags": [ "Cases and reports" ], "summary": "Add a case note", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_cases_case_id_comments", "x-required-scope": "cases:write", "description": "Client-visible case or evidence writes additionally require cases:share. Machine writes do not publish reports.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 120 }, "description": "Reuse this key with the identical request after an uncertain outcome." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentCreate" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Cases and reports" ], "summary": "Read case comments", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_cases_case_id_comments", "x-required-scope": "cases:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/cases/{case_id}/evidence": { "post": { "tags": [ "Cases and reports" ], "summary": "Capture job or imported evidence", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_cases_case_id_evidence", "x-required-scope": "evidence:write", "description": "Client-visible case or evidence writes additionally require cases:share. Machine writes do not publish reports.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceCreate" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Cases and reports" ], "summary": "Read case evidence", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_cases_case_id_evidence", "x-required-scope": "cases:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/cases/{case_id}/evidence/{evidence_id}": { "patch": { "tags": [ "Cases and reports" ], "summary": "Annotate evidence", "operationId": "patch_api_v2_service_organizations_organization_id_clients_client_id_cases_case_id_evidence_evidence_id", "x-required-scope": "evidence:write", "description": "Client-visible case or evidence writes additionally require cases:share. Machine writes do not publish reports.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "evidence_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quote the exact current resource version." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceAnnotation" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/cases/{case_id}/reports": { "post": { "tags": [ "Cases and reports" ], "summary": "Create a private report draft", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_cases_case_id_reports", "x-required-scope": "reports:render", "description": "Client-visible case or evidence writes additionally require cases:share. Machine writes do not publish reports.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 120 }, "description": "Reuse this key with the identical request after an uncertain outcome." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDefinition" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/reports/{report_id}": { "patch": { "tags": [ "Cases and reports" ], "summary": "Edit a report draft", "operationId": "patch_api_v2_service_organizations_organization_id_clients_client_id_reports_report_id", "x-required-scope": "reports:render", "description": "Client-visible case or evidence writes additionally require cases:share. Machine writes do not publish reports.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quote the exact current resource version." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDefinition" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/reports/{report_id}/render": { "post": { "tags": [ "Cases and reports" ], "summary": "Render a report revision", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_reports_report_id_render", "x-required-scope": "reports:render", "description": "Client-visible case or evidence writes additionally require cases:share. Machine writes do not publish reports.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quote the exact current resource version." } ], "responses": { "202": { "description": "Accepted as an asynchronous job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/cases/{case_id}/revisions": { "get": { "tags": [ "Cases and reports" ], "summary": "List case revisions", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_cases_case_id_revisions", "x-required-scope": "cases:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/cases/{case_id}/graph/auto": { "get": { "tags": [ "Cases and reports" ], "summary": "Read the saved automatic graph", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_cases_case_id_graph_auto", "x-required-scope": "cases:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/cases/{case_id}/follow-up-searches": { "get": { "tags": [ "Cases and reports" ], "summary": "Read prior case searches", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_cases_case_id_follow_up_searches", "x-required-scope": "cases:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/reports": { "get": { "tags": [ "Cases and reports" ], "summary": "List report drafts", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_reports", "x-required-scope": "reports:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/reports/{report_id}/versions": { "get": { "tags": [ "Cases and reports" ], "summary": "List immutable report versions", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_reports_report_id_versions", "x-required-scope": "reports:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/report-versions/{version_id}/download/{format}": { "get": { "tags": [ "Cases and reports" ], "summary": "Download an authorized report artifact", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_report_versions_version_id_download_format", "x-required-scope": "reports:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/watches/preview": { "post": { "tags": [ "Monitoring" ], "summary": "Quote and validate a monitor", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_watches_preview", "x-required-scope": "watches:write", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Retired monitor operation: monitors_replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "deprecated": true, "description": "Former scheduled monitoring. Configurations are retained but are not migrated automatically. Use /followups for continuous monitoring." } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/watches": { "post": { "tags": [ "Monitoring" ], "summary": "Create a monitor", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_watches", "x-required-scope": "watches:write", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 120 }, "description": "Reuse this key with the identical request after an uncertain outcome." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Retired monitor operation: monitors_replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "deprecated": true, "description": "Former scheduled monitoring. Configurations are retained but are not migrated automatically. Use /followups for continuous monitoring." }, "get": { "tags": [ "Monitoring" ], "summary": "List monitors", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_watches", "x-required-scope": "watches:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "deprecated": true, "description": "Former scheduled monitoring. Configurations are retained but are not migrated automatically. Use /followups for continuous monitoring." } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/watches/{watch_id}": { "patch": { "tags": [ "Monitoring" ], "summary": "Edit or pause a monitor", "operationId": "patch_api_v2_service_organizations_organization_id_clients_client_id_watches_watch_id", "x-required-scope": "watches:write", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "watch_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quote the exact current resource version." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Retired monitor operation: monitors_replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "deprecated": true, "description": "Former scheduled monitoring. Configurations are retained but are not migrated automatically. Use /followups for continuous monitoring." } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/watches/{watch_id}/run": { "post": { "tags": [ "Monitoring" ], "summary": "Run a monitor manually", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_watches_watch_id_run", "x-required-scope": "watches:write", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "watch_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 120 }, "description": "Reuse this key with the identical request after an uncertain outcome." } ], "responses": { "202": { "description": "Accepted as an asynchronous job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Retired monitor operation: monitors_replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "deprecated": true, "description": "Former scheduled monitoring. Configurations are retained but are not migrated automatically. Use /followups for continuous monitoring." } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/watches/{watch_id}/runs": { "get": { "tags": [ "Monitoring" ], "summary": "List monitor collections", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_watches_watch_id_runs", "x-required-scope": "watches:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "watch_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "deprecated": true, "description": "Former scheduled monitoring. Configurations are retained but are not migrated automatically. Use /followups for continuous monitoring." } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/changes": { "get": { "tags": [ "Monitoring" ], "summary": "List observed changes", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_changes", "x-required-scope": "watches:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/change-groups": { "get": { "tags": [ "Monitoring" ], "summary": "List change groups", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_change_groups", "x-required-scope": "watches:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/monitoring-summary": { "get": { "tags": [ "Monitoring" ], "summary": "Read monitoring counters", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_monitoring_summary", "x-required-scope": "watches:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/webhook-events/verify": { "post": { "tags": [ "Webhooks" ], "summary": "Verify a signed job webhook", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_webhook_events_verify", "x-required-scope": [ "search:read", "tools:execute", "exports:create", "reports:render", "watches:write" ], "description": "Does not create a job or charge credits. Submit the exact received body and signature; verify job ownership before reading its result.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookVerify" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/search/fields": { "get": { "tags": [ "Search and jobs" ], "summary": "Read search field metadata", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_search_fields", "x-required-scope": "search:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/search/count": { "post": { "tags": [ "Search and jobs" ], "summary": "Count bounded query suggestions", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_search_count", "x-required-scope": "search:read", "description": "Bounded assistance only. Counts are not a completed search or an exhaustive inventory.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/search/validate": { "post": { "tags": [ "Search and jobs" ], "summary": "Validate a query", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_search_validate", "x-required-scope": "search:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/pivot/saves": { "get": { "tags": [ "Asset tools" ], "summary": "List accessible saved pivots", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_pivot_saves", "x-required-scope": "tools:execute", "description": "Bound to the authorized organization/client and current integration. Another integration’s private saved pivot is not accessible. See the Pivot guide for operation-specific payloads and revision checks.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/pivot/saves/{pivot_id}": { "get": { "tags": [ "Asset tools" ], "summary": "Open a saved pivot", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_pivot_saves_pivot_id", "x-required-scope": "tools:execute", "description": "Bound to the authorized organization/client and current integration. Another integration’s private saved pivot is not accessible. See the Pivot guide for operation-specific payloads and revision checks.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "pivot_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Asset tools" ], "summary": "Update a saved pivot", "operationId": "patch_api_v2_service_organizations_organization_id_clients_client_id_pivot_saves_pivot_id", "x-required-scope": "tools:execute", "description": "Bound to the authorized organization/client and current integration. Another integration’s private saved pivot is not accessible. See the Pivot guide for operation-specific payloads and revision checks.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "pivot_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Asset tools" ], "summary": "Delete a saved pivot", "operationId": "delete_api_v2_service_organizations_organization_id_clients_client_id_pivot_saves_pivot_id", "x-required-scope": "tools:execute", "description": "Bound to the authorized organization/client and current integration. Another integration’s private saved pivot is not accessible. See the Pivot guide for operation-specific payloads and revision checks.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "pivot_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/pivot/saves/{pivot_id}/undo": { "post": { "tags": [ "Asset tools" ], "summary": "Undo a saved pivot edit", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_pivot_saves_pivot_id_undo", "x-required-scope": "tools:execute", "description": "Bound to the authorized organization/client and current integration. Another integration’s private saved pivot is not accessible. See the Pivot guide for operation-specific payloads and revision checks.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "pivot_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/pivot/saves/{pivot_id}/copy": { "post": { "tags": [ "Asset tools" ], "summary": "Copy a saved pivot", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_pivot_saves_pivot_id_copy", "x-required-scope": "tools:execute", "description": "Bound to the authorized organization/client and current integration. Another integration’s private saved pivot is not accessible. See the Pivot guide for operation-specific payloads and revision checks.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "pivot_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/pivot/saves/{pivot_id}/access": { "put": { "tags": [ "Asset tools" ], "summary": "Set saved pivot access", "operationId": "put_api_v2_service_organizations_organization_id_clients_client_id_pivot_saves_pivot_id_access", "x-required-scope": "tools:execute", "description": "Bound to the authorized organization/client and current integration. Another integration’s private saved pivot is not accessible. See the Pivot guide for operation-specific payloads and revision checks.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "pivot_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/pivot/saves/{pivot_id}/stix": { "get": { "tags": [ "Asset tools" ], "summary": "Export saved pivot STIX", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_pivot_saves_pivot_id_stix", "x-required-scope": "tools:execute", "description": "Bound to the authorized organization/client and current integration. Another integration’s private saved pivot is not accessible. See the Pivot guide for operation-specific payloads and revision checks.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "pivot_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/pivot/saves/{pivot_id}/evidence": { "post": { "tags": [ "Asset tools" ], "summary": "Capture saved pivot evidence", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_pivot_saves_pivot_id_evidence", "x-required-scope": "tools:execute", "description": "Bound to the authorized organization/client and current integration. Another integration’s private saved pivot is not accessible. See the Pivot guide for operation-specific payloads and revision checks.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "pivot_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/followups/": { "get": { "tags": [ "Monitoring" ], "summary": "List continuous monitors", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_followups", "x-required-scope": "watches:read", "description": "Reads only stored observations. Journal/events accept an after cursor and unread; assets accepts state and after. No recon search or charge is triggered.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Monitoring" ], "summary": "Create a continuous monitor", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_followups", "x-required-scope": "watches:write", "description": "Starts with live observations only. Does not launch archive queries or charge credits. A service key is not an email recipient; delivery must be inbox.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 120 }, "description": "Reuse this key with the identical request after an uncertain outcome." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowupInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/followups/journal": { "get": { "tags": [ "Monitoring" ], "summary": "Read the client activity journal", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_followups_journal", "x-required-scope": "watches:read", "description": "Reads only stored observations. Journal/events accept an after cursor and unread; assets accepts state and after. No recon search or charge is triggered.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/followups/capabilities": { "get": { "tags": [ "Monitoring" ], "summary": "Read monitoring capacity and source health", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_followups_capabilities", "x-required-scope": "watches:read", "description": "Reads only stored observations. Journal/events accept an after cursor and unread; assets accepts state and after. No recon search or charge is triggered.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/followups/{followup_id}": { "get": { "tags": [ "Monitoring" ], "summary": "Read a continuous monitor", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_followups_followup_id", "x-required-scope": "watches:read", "description": "Reads only stored observations. Journal/events accept an after cursor and unread; assets accepts state and after. No recon search or charge is triggered.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "followup_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/followups/{followup_id}/events": { "get": { "tags": [ "Monitoring" ], "summary": "Read monitor events", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_followups_followup_id_events", "x-required-scope": "watches:read", "description": "Reads only stored observations. Journal/events accept an after cursor and unread; assets accepts state and after. No recon search or charge is triggered.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "followup_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/followups/{followup_id}/assets": { "get": { "tags": [ "Monitoring" ], "summary": "Read scope and candidates", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_followups_followup_id_assets", "x-required-scope": "watches:read", "description": "Reads only stored observations. Journal/events accept an after cursor and unread; assets accepts state and after. No recon search or charge is triggered.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "followup_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/followups/{followup_id}/profile": { "get": { "tags": [ "Monitoring" ], "summary": "Read observed discovery signals", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_followups_followup_id_profile", "x-required-scope": "watches:read", "description": "Reads only stored observations. Journal/events accept an after cursor and unread; assets accepts state and after. No recon search or charge is triggered.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "followup_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/followups/{followup_id}/history": { "get": { "tags": [ "Monitoring" ], "summary": "Read prior historical checks", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_followups_followup_id_history", "x-required-scope": "watches:read", "description": "Reads only stored observations. Journal/events accept an after cursor and unread; assets accepts state and after. No recon search or charge is triggered.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "followup_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Monitoring" ], "summary": "Request a bounded historical signal check", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_followups_followup_id_history", "x-required-scope": "watches:write", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "followup_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signal": { "$ref": "#/components/schemas/FollowupPredicate" }, "version": { "type": "integer" } }, "required": [ "signal", "version" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Historical queries are disabled: archive_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/followups/{followup_id}/settings": { "get": { "tags": [ "Monitoring" ], "summary": "Read webhook settings", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_followups_followup_id_settings", "x-required-scope": "watches:read", "description": "Reads only stored observations. Journal/events accept an after cursor and unread; assets accepts state and after. No recon search or charge is triggered.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "followup_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Monitoring" ], "summary": "Configure a monitor webhook", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_followups_followup_id_settings", "x-required-scope": "watches:write", "description": "Destination validation and organization-wide webhook capacity apply. The signing secret is returned only at configuration; store it securely.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "followup_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "url", "enabled" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/followups/{followup_id}/deliveries": { "get": { "tags": [ "Monitoring" ], "summary": "Read delivery attempts", "operationId": "get_api_v2_service_organizations_organization_id_clients_client_id_followups_followup_id_deliveries", "x-required-scope": "watches:read", "description": "Reads only stored observations. Journal/events accept an after cursor and unread; assets accepts state and after. No recon search or charge is triggered.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "followup_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/followups/compile": { "post": { "tags": [ "Monitoring" ], "summary": "Compile a search rule", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_followups_compile", "x-required-scope": "watches:write", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string" }, "query": { "type": "string" } }, "required": [ "source", "query" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/followups/preview": { "post": { "tags": [ "Monitoring" ], "summary": "Request an optional bounded archive sample", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_followups_preview", "x-required-scope": "watches:write", "description": "Disabled at launch. A sample is not an exhaustive historical baseline.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowupInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Historical queries are disabled: archive_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/followups/{followup_id}/update": { "post": { "tags": [ "Monitoring" ], "summary": "Update or pause a continuous monitor", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_followups_followup_id_update", "x-required-scope": "watches:write", "description": "Supply the current version in the JSON body. Pausing stops monitoring; key revocation alone does not pause an organization-owned monitor.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "followup_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowupInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/followups/{followup_id}/preview-profile": { "post": { "tags": [ "Monitoring" ], "summary": "Preview discovery signals on collected data", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_followups_followup_id_preview_profile", "x-required-scope": "watches:write", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "followup_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowupInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/followups/{followup_id}/delete": { "post": { "tags": [ "Monitoring" ], "summary": "Delete a continuous monitor", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_followups_followup_id_delete", "x-required-scope": "watches:write", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "followup_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quote the exact current resource version." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/followups/{followup_id}/read": { "post": { "tags": [ "Monitoring" ], "summary": "Acknowledge events through a cursor", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_followups_followup_id_read", "x-required-scope": "watches:read", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "followup_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cursor": { "type": "string" } }, "required": [ "cursor" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/followups/{followup_id}/review": { "post": { "tags": [ "Monitoring" ], "summary": "Accept, exclude or restore a candidate", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_followups_followup_id_review", "x-required-scope": "watches:write", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "followup_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "string" }, "action": { "type": "string", "enum": [ "accept", "exclude", "restore" ] }, "version": { "type": "integer" } }, "required": [ "asset", "action", "version" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/followups/{followup_id}/archive": { "post": { "tags": [ "Monitoring" ], "summary": "Request a bounded baseline check", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_followups_followup_id_archive", "x-required-scope": "watches:write", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "followup_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer" } }, "required": [ "version" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Historical queries are disabled: archive_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/service/organizations/{organization_id}/clients/{client_id}/followups/{followup_id}/deliveries/{delivery_id}/retry": { "post": { "tags": [ "Monitoring" ], "summary": "Retry a failed delivery", "operationId": "post_api_v2_service_organizations_organization_id_clients_client_id_followups_followup_id_deliveries_delivery_id_retry", "x-required-scope": "watches:write", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use organization_id from whoami" }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use an id in whoami.clients" }, { "name": "followup_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "401": { "description": "Missing, invalid, expired or revoked key; client or required scope unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan or field restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or concurrent edit conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ServiceBearer": { "type": "http", "scheme": "bearer", "description": "Organization service key beginning pb2b_. Personal keys and browser cookies do not authenticate these routes." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "field_errors": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "Client": { "type": "object", "properties": { "id": { "type": "string", "description": "Client context UUID" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "Whoami": { "type": "object", "properties": { "organization_id": { "type": "string" }, "organization_name": { "type": "string" }, "service_identity_id": { "type": "string" }, "key_id": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "clients": { "type": "array", "items": { "$ref": "#/components/schemas/Client" } }, "credit_limit": { "type": "integer", "description": "Integration ceiling per credit period" }, "credits_used_this_period": { "type": "integer", "description": "Settled usage; excludes pending reservations" }, "expires_at": { "type": "string", "description": "RFC 3339", "format": "date-time" } }, "required": [ "organization_id", "service_identity_id", "key_id", "scopes", "clients", "credit_limit", "credits_used_this_period", "expires_at" ], "additionalProperties": false }, "Job": { "type": "object", "additionalProperties": true, "required": [ "id", "state", "kind" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "state": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] }, "failure_code": { "type": "string", "description": "Present on failure" }, "organization_id": { "type": "string" }, "client_id": { "type": "string" }, "service_identity_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "JobSubmission": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/Job" }, "reserved_credits": { "type": "integer", "description": "Maximum reserved at admission; unused credits are released" } }, "required": [ "job", "reserved_credits" ], "additionalProperties": false }, "ToolSubmission": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/Job" }, "reserved_credits": { "type": "integer", "description": "Present when the tool reserves credits" } }, "required": [ "job" ], "additionalProperties": false }, "SearchQuery": { "type": "object", "additionalProperties": false, "required": [ "raw_query" ], "properties": { "raw_query": { "type": "string", "description": "Use the field vocabulary of the selected dataset: host:, san:, or domain: as appropriate" }, "page": { "type": "integer", "description": "Starts at 1", "minimum": 1 }, "results_per_page": { "type": "integer", "description": "Allowed page sizes", "enum": [ 10, 30, 50 ] }, "time_frame": { "type": "string", "enum": [ "all_time", "last_24h", "last_7d", "last_30d", "this_year" ] }, "include": { "type": "string", "description": "all or comma-separated fields" }, "aggregate": { "type": "boolean" }, "order_by": { "type": "string" }, "direction": { "type": "string", "enum": [ "asc", "desc" ] }, "group": { "type": "string", "description": "Hosts-only grouping" }, "after": { "type": "string", "description": "Opaque grouping cursor" } } }, "UnifiedQuery": { "type": "object", "properties": { "raw_query": { "type": "string" }, "time_frame": { "type": "string" }, "per_type_limit": { "type": "integer", "description": "Results per targeted dataset; positive values are capped at 25", "minimum": 1 }, "stream": { "type": "boolean" }, "broad": { "type": "boolean" } }, "required": [ "raw_query" ], "additionalProperties": false }, "UnifiedMoreQuery": { "type": "object", "properties": { "raw_query": { "type": "string" }, "dataset": { "type": "string", "enum": [ "hosts", "dns", "vhosts", "whois" ] }, "page": { "type": "integer", "description": "At least 2", "minimum": 2 }, "time_frame": { "type": "string" }, "per_type_limit": { "type": "integer", "description": "Must match the initial unified search" } }, "required": [ "raw_query", "dataset", "page", "per_type_limit" ], "additionalProperties": false }, "SearchResult": { "type": "object", "description": "Stored result. Granular searches contain data, total and billing_context; unified searches contain results, per_type_status and billing_context. Result records vary by dataset.", "additionalProperties": true }, "BatchItemInput": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable item identifier, 1–80 letters, digits, dot, underscore or hyphen" }, "engine": { "type": "string", "enum": [ "hosts", "dns", "vhosts", "whois", "unified", "unified-more" ] }, "query": { "anyOf": [ { "$ref": "#/components/schemas/SearchQuery" }, { "$ref": "#/components/schemas/UnifiedQuery" }, { "$ref": "#/components/schemas/UnifiedMoreQuery" } ] } }, "required": [ "id", "engine", "query" ], "additionalProperties": false }, "BatchRequest": { "type": "object", "properties": { "max_credits": { "type": "integer", "description": "Hard ceiling for the whole batch", "minimum": 1 }, "items": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "$ref": "#/components/schemas/BatchItemInput" } } }, "required": [ "max_credits", "items" ], "additionalProperties": false }, "BatchQuote": { "type": "object", "properties": { "maximum": { "type": "integer", "description": "Quoted maximum, no reservation" }, "queries": { "type": "integer" } }, "required": [ "maximum", "queries" ], "additionalProperties": false }, "Batch": { "type": "object", "additionalProperties": true, "required": [ "id", "maximum" ], "properties": { "id": { "type": "string" }, "maximum": { "type": "integer" }, "authorized_maximum": { "type": "integer" }, "retry_of_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "BatchItem": { "type": "object", "additionalProperties": true, "required": [ "item_id", "job_id", "state" ], "properties": { "item_id": { "type": "string" }, "job_id": { "type": "string" }, "state": { "type": "string" }, "failure_code": { "type": "string" }, "maximum": { "type": "integer" }, "actual": { "type": "integer" }, "label": { "type": "string" } } }, "BatchView": { "type": "object", "properties": { "batch": { "$ref": "#/components/schemas/Batch" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/BatchItem" } }, "can_manage": { "type": "boolean" } }, "required": [ "batch", "items", "can_manage" ], "additionalProperties": false }, "BatchRetry": { "type": "object", "properties": { "items": { "type": "array", "minItems": 1, "items": { "type": "string", "description": "Failed or cancelled item_id" } }, "max_credits": { "type": "integer", "description": "New hard ceiling", "minimum": 1 } }, "required": [ "items", "max_credits" ], "additionalProperties": false }, "ExportRequest": { "type": "object", "properties": { "engine": { "type": "string", "enum": [ "hosts", "dns", "vhosts", "whois" ] }, "raw_query": { "type": "string" }, "time_frame": { "type": "string" }, "format": { "type": "string", "enum": [ "json", "csv", "txt" ] }, "max_results": { "type": "integer", "description": "Maximum output rows; reservation is ceil(max_results / 100)", "minimum": 1 }, "visibility": { "type": "string", "enum": [ "private", "organization" ] }, "case_id": { "type": "string", "description": "Optional engagement link" } }, "required": [ "engine", "raw_query", "format", "max_results" ], "additionalProperties": false }, "WatchRequest": { "type": "object", "properties": { "name": { "type": "string" }, "dataset": { "type": "string", "enum": [ "hosts", "dns", "vhosts", "whois" ] }, "query": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "paused" ] }, "scheduled": { "type": "boolean" }, "interval_hours": { "type": "integer", "description": "24 or 168", "enum": [ 24, 168 ] }, "max_pages": { "type": "integer", "minimum": 1, "maximum": 10 }, "credit_limit": { "type": "integer" }, "realtime": { "type": "boolean" } }, "required": [ "name", "dataset", "query", "state", "scheduled", "interval_hours", "max_pages", "credit_limit" ], "additionalProperties": false }, "CaseCreate": { "type": "object", "properties": { "title": { "type": "string" }, "visibility": { "type": "string", "description": "Defaults to internal", "enum": [ "internal", "client" ] }, "follow_up_of": { "type": "string", "description": "Optional prior case UUID" } }, "required": [ "title" ], "additionalProperties": false }, "CaseDocument": { "type": "object", "properties": { "summary": { "type": "string" }, "nodes": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "id", "type", "value", "visibility" ], "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "label": { "type": "string" }, "note": { "type": "string" }, "visibility": { "type": "string" }, "evidence_id": { "type": "string" }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false } } } }, "edges": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "id", "source", "target", "label", "visibility" ], "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "target": { "type": "string" }, "label": { "type": "string" }, "visibility": { "type": "string" }, "evidence_id": { "type": "string" } } } } }, "required": [ "summary", "nodes", "edges" ], "additionalProperties": false }, "CaseEdit": { "type": "object", "properties": { "title": { "type": "string" }, "state": { "type": "string" }, "visibility": { "type": "string", "enum": [ "internal", "client" ] }, "document": { "$ref": "#/components/schemas/CaseDocument" }, "base_version": { "type": "integer", "description": "Revision being edited; defaults to If-Match" } }, "required": [ "title", "state", "visibility", "document" ], "additionalProperties": false }, "CommentCreate": { "type": "object", "additionalProperties": true, "required": [ "body", "visibility" ], "properties": { "body": { "type": "string" }, "visibility": { "type": "string", "enum": [ "internal", "client" ] }, "evidence_id": { "type": "string" }, "graph_ref": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "node", "edge" ] }, "id": { "type": "string" } }, "required": [ "kind", "id" ], "additionalProperties": false } } }, "EvidenceCreate": { "type": "object", "additionalProperties": true, "required": [ "visibility" ], "properties": { "job_id": { "type": "string" }, "record_index": { "type": "integer", "minimum": 0 }, "imported": { "type": "object", "additionalProperties": true }, "visibility": { "type": "string", "enum": [ "internal", "client" ] }, "annotation": { "type": "string" }, "annotation_format": { "type": "string", "enum": [ "plain", "markdown" ] } }, "description": "Supply job_id and record_index, or imported JSON. Client-visible content additionally needs cases:share." }, "EvidenceAnnotation": { "type": "object", "properties": { "annotation": { "type": "string" }, "annotation_format": { "type": "string", "enum": [ "plain", "markdown" ] }, "visibility": { "type": "string", "enum": [ "internal", "client" ] }, "base_version": { "type": "integer", "description": "Revision being edited" } }, "required": [ "annotation", "visibility", "base_version" ], "additionalProperties": false }, "ReportDefinition": { "type": "object", "additionalProperties": true, "properties": { "title": { "type": "string" }, "summary": { "type": "string" }, "scope": { "type": "string" }, "recommendations": { "type": "string" }, "template": { "type": "string" }, "language": { "type": "string" }, "brand": { "type": "object", "additionalProperties": true }, "evidence_ids": { "type": "array", "items": { "type": "string" } }, "comment_ids": { "type": "array", "items": { "type": "string" } }, "section_order": { "type": "array", "items": { "type": "string" } }, "include_graph": { "type": "boolean" }, "audience": { "type": "string", "enum": [ "internal", "client" ] } } }, "WebhookVerify": { "type": "object", "properties": { "endpoint_id": { "type": "string" }, "event_id": { "type": "string" }, "signature": { "type": "string", "description": "Complete X-Profundis-Signature header" }, "body": { "type": "string", "description": "Exact incoming UTF-8 body" } }, "required": [ "endpoint_id", "event_id", "signature", "body" ], "additionalProperties": false }, "Record": { "type": "object", "additionalProperties": true, "description": "Client-scoped record. Fields depend on the resource; authorization is checked on every read." }, "FollowupPredicate": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "hosts", "dns", "vhosts", "whois" ] }, "field": { "type": "string" }, "op": { "type": "string", "enum": [ "eq", "suffix", "regex", "glob" ] }, "value": { "type": "string" } }, "required": [ "source", "field", "op", "value" ], "additionalProperties": false }, "FollowupDefinition": { "type": "object", "additionalProperties": false, "properties": { "seeds": { "type": "array", "items": { "type": "string", "description": "Domain or IP address" } }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "hosts", "dns", "vhosts", "whois" ] } }, "signals": { "type": "array", "items": { "$ref": "#/components/schemas/FollowupPredicate" } }, "ignored_signals": { "type": "array", "items": { "$ref": "#/components/schemas/FollowupPredicate" } }, "exclusions": { "type": "array", "items": { "type": "string" } }, "scenarios": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } }, "rule": { "$ref": "#/components/schemas/Record" } }, "required": [ "seeds", "sources", "signals", "exclusions", "scenarios" ] }, "FollowupInput": { "type": "object", "properties": { "name": { "type": "string" }, "definition": { "$ref": "#/components/schemas/FollowupDefinition" }, "state": { "type": "string", "enum": [ "active", "paused" ] }, "delivery": { "type": "string", "description": "Service keys must select inbox", "enum": [ "inbox" ] }, "notify_kinds": { "type": "array", "items": { "type": "string" } }, "version": { "type": "integer", "description": "Required current version for updates" } }, "required": [ "name", "definition", "state", "delivery", "notify_kinds" ], "additionalProperties": false } } } }