{ "openapi": "3.1.0", "info": { "title": "Prophet Public API", "version": "1.0.0", "description": "Public REST, Search, and control-plane endpoints for Prophet — autonomous network breach detection and attribution delivered as a service.", "termsOfService": "https://prophetic.ai/trust/terms", "contact": { "name": "Prophetic AI", "url": "https://prophetic.ai", "email": "hello@prophetic.ai" } }, "servers": [ { "url": "https://app.prophet.io" } ], "externalDocs": { "description": "Prophet API documentation", "url": "https://docs.prophet.io" }, "tags": [ { "name": "OAuth2", "description": "Issue JWT access tokens, register collectors, and run device authorization.", "externalDocs": { "url": "https://docs.prophet.io/#api-oauth2" } }, { "name": "Deployments", "description": "Create and manage child tenant deployments for MSP parent accounts.", "externalDocs": { "url": "https://docs.prophet.io/#api-deployments" } }, { "name": "Nodes", "description": "Provision units, inspect node health, trigger updates, and pull diagnostics.", "externalDocs": { "url": "https://docs.prophet.io/#api-nodes" } }, { "name": "Profiles", "description": "Reusable collector capture configuration for fleets and child deployments.", "externalDocs": { "url": "https://docs.prophet.io/#api-profiles" } }, { "name": "Collector", "description": "Download binaries and install or uninstall the Prophet collector.", "externalDocs": { "url": "https://docs.prophet.io/#api-collector" } }, { "name": "Search", "description": "Query flow records, request timeseries buckets, and run terms aggregations over flow data.", "externalDocs": { "url": "https://docs.prophet.io/#api-flows" } }, { "name": "Investigations", "description": "Read the finished investigations Prophet produces when breach signal appears — verdict, key findings, provenance lineage across access, execution, and network, and recommended actions. One question is left for a human: was this authorized?", "externalDocs": { "url": "https://docs.prophet.io/#api-investigations" } }, { "name": "Explore", "description": "External-organization communication shape: which external services a network sends traffic to, and the texture of each relationship (when, rhythm, transfer, who, how). Communication shape is what Prophet models to detect breaches — these endpoints expose the same view of your network for exploration.", "externalDocs": { "url": "https://docs.prophet.io/#api-explore" } }, { "name": "Events", "description": "Fetch event topics and records from Prophet plugin activity.", "externalDocs": { "url": "https://docs.prophet.io/#api-events" } }, { "name": "Automation", "description": "List, set, and delete automations scoped to a tenant or child tenant.", "externalDocs": { "url": "https://docs.prophet.io/#api-automation" } } ], "paths": { "/rest/oauth2/token/1.0": { "post": { "operationId": "oauthToken", "tags": [ "OAuth2" ], "summary": "Exchange API credentials", "description": "Returns a JWT bearer token from a client ID and client secret.", "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string", "description": "OAuth2 API credential client ID." }, "client_secret": { "type": "string", "description": "OAuth2 API credential secret." } }, "required": [ "client_id", "client_secret" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "description": "JWT bearer token." }, "expires_in": { "type": "number", "description": "Lifetime in seconds." }, "expires_at": { "type": "number", "description": "Unix timestamp when the token expires." }, "token_type": { "type": "string", "description": "Usually Bearer." } }, "additionalProperties": true } } } }, "401": { "description": "Client credentials are missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_credentials" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "public", "x-prophet-auth": "client credentials", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-oauth-token" } }, "/rest/oauth2/register/1.0": { "post": { "operationId": "oauthRegister", "tags": [ "OAuth2" ], "summary": "Register legacy node", "description": "Registers a first-generation node by machine ID and hostname.", "security": [ { "bearerAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "machine_id": { "type": "string", "description": "Stable node machine identifier." }, "hostname": { "type": "string", "description": "Host name to store on the legacy node record." } }, "required": [ "machine_id", "hostname" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "node_id": { "type": "string", "description": "Existing or newly-created legacy node ID." } }, "additionalProperties": true } } } }, "400": { "description": "machine_id or hostname is missing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "missing_required_fields" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.ingest", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "legacy", "x-docs-url": "https://docs.prophet.io/#api-oauth-register" } }, "/rest/oauth2/device/1.0": { "post": { "operationId": "oauthDeviceStart", "tags": [ "OAuth2" ], "summary": "Start device authorization", "description": "Creates a pending device authorization request for a machine ID or node ID.", "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "machine_id": { "type": "string", "description": "Machine identifier. Required unless node_id is supplied." }, "node_id": { "type": "string", "description": "Node identifier alias. Used as machine_id when supplied." }, "hostname": { "type": "string", "description": "Host name shown during approval." } }, "required": [ "hostname" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "device_code": { "type": "string", "description": "Opaque code the device polls with." }, "auth_url": { "type": "string", "description": "Full per-device approval URL on the Prophet console. Present or open it for an operator." }, "poll_interval": { "type": "number", "description": "Seconds to wait between poll requests." }, "expires_in": { "type": "number", "description": "Seconds until this device authorization expires." } }, "additionalProperties": true } } } }, "400": { "description": "machine_id/node_id or hostname is missing. Body is {\"error\":\"machine_id and hostname are required\"}.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "public", "x-prophet-auth": "none", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-oauth-device-start" } }, "/rest/oauth2/device/approve/1.0": { "get": { "operationId": "oauthDeviceInfo", "tags": [ "OAuth2" ], "summary": "Get device approval info", "description": "Reads pending device details for an approval screen.", "security": [], "parameters": [ { "name": "device_code", "in": "query", "required": true, "description": "Device code returned by the start request.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "device_code": { "type": "string", "description": "Device authorization code." }, "node_id": { "type": [ "string", "null" ], "description": "Node ID when present." }, "hostname": { "type": "string", "description": "Device hostname." }, "status": { "type": "string", "description": "Pending, approved, denied, or expired status." }, "createdAt": { "type": "string", "description": "Creation timestamp." }, "expiresAt": { "type": "string", "description": "Expiration timestamp." } }, "additionalProperties": true } } } }, "400": { "description": "device_code is missing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "missing_required_fields" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "404": { "description": "Device code not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "not_found" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "public", "x-prophet-auth": "none", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-oauth-device-info" }, "post": { "operationId": "oauthDeviceApprove", "tags": [ "OAuth2" ], "summary": "Approve or deny device", "description": "Approves a pending device for the authenticated customer or denies the request.", "security": [ { "bearerAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "device_code": { "type": "string", "description": "Device code to approve or deny." }, "action": { "type": [ "string", "null" ], "description": "When action is deny the code is denied; otherwise it is approved." } }, "required": [ "device_code" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Result of the action." } }, "additionalProperties": true } } } }, "400": { "description": "device_code is missing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "missing_required_fields" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "any valid token", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-oauth-device-approve" } }, "/rest/oauth2/device/poll/1.0": { "post": { "operationId": "oauthDevicePoll", "tags": [ "OAuth2" ], "summary": "Poll device authorization", "description": "Returns the current state of a device authorization request.", "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "device_code": { "type": "string", "description": "Device code returned by the start request." } }, "required": [ "device_code" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Current device authorization status. Unknown device codes return status expired, not an error." }, "access_key": { "type": [ "string", "null" ], "description": "Present once approved. A long-lived client credential in client_id.client_secret form — exchange it at /rest/oauth2/token/1.0 for bearer tokens. It is not itself a bearer token." }, "node_id": { "type": [ "string", "null" ], "description": "Node identifier bound to the approval, when present." } }, "additionalProperties": true } } } }, "400": { "description": "device_code is missing. Body is {\"error\":\"device_code is required\"}.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "public", "x-prophet-auth": "none", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-oauth-device-poll" } }, "/rest/deployments/1.0": { "get": { "operationId": "deploymentsList", "tags": [ "Deployments" ], "summary": "List child deployments", "description": "Lists child tenants for the authenticated parent MSP.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "parent_id", "in": "query", "required": false, "description": "Parent MSP customer_id. Defaults to the authenticated customer_id.", "schema": { "type": "string" }, "example": "acme_msp" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always \"success\" on 200." }, "parent.customer_id": { "type": "string", "description": "The parent deployment customer_id used for the query." }, "parent.name": { "type": [ "string", "null" ], "description": "Display name for the parent deployment." }, "parent.handle": { "type": [ "string", "null" ], "description": "Parent URL-safe handle." }, "deployments[]": { "type": "array", "items": { "type": "object" }, "description": "Child deployments owned by the parent." }, "count": { "type": "number", "description": "Number of child deployments returned." } }, "additionalProperties": true } } } }, "403": { "description": "The bearer token customer is not the requested parent MSP.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "unauthorized" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.deployment_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-deployments-list", "x-python-sdk": { "method": "prophet.deployments.list(parent_id: str | None = None) -> list[Deployment]", "docsUrl": "https://docs.prophet.io/#api-deployments-list" } }, "post": { "operationId": "deploymentsCreate", "tags": [ "Deployments" ], "summary": "Create child deployment", "description": "Creates a child deployment under the authenticated parent MSP.", "security": [ { "bearerAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the child deployment.", "example": "Acme Corp" }, "handle": { "type": "string", "description": "URL-safe identifier. The controller slugifies it to lowercase with underscores.", "example": "acme_corp" }, "parent_id": { "type": "string", "description": "Parent MSP customer_id. Must match the authenticated parent customer.", "example": "acme_msp" }, "subdomain": { "type": "string", "description": "Optional custom subdomain label for the child deployment.", "example": "acme" } }, "required": [ "name", "handle", "parent_id" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always \"success\" on 201." }, "deployment.customer.customer_id": { "type": "string", "description": "Created child deployment customer_id." }, "deployment.customer.name": { "type": [ "string", "null" ], "description": "Created child deployment display name." }, "deployment.customer.handle": { "type": [ "string", "null" ], "description": "Slugified child handle." }, "deployment.customer.type": { "type": "string", "description": "Set to \"child\"." }, "deployment.customer.parent": { "type": "string", "description": "Parent MSP customer_id." }, "deployment.customer.org_code": { "type": [ "string", "null" ], "description": "Organization code from the identity provider." }, "deployment.org": { "type": "object", "additionalProperties": true, "description": "Identity-provider organization summary returned by the create call." } }, "additionalProperties": true } } } }, "400": { "description": "name, handle, or parent_id is missing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "missing_required_fields" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "The bearer token customer cannot create children under this parent_id, or the caller is not provisioned as a parent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "unauthorized" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.deployment_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-deployments-create", "x-python-sdk": { "method": "prophet.deployments.create(name: str, handle: str, parent_id: str | None = None) -> Deployment", "docsUrl": "https://docs.prophet.io/#api-deployments-create" } }, "delete": { "operationId": "deploymentsDelete", "tags": [ "Deployments" ], "summary": "Delete child deployment", "description": "Deletes a child deployment and its backing organization records.", "security": [ { "bearerAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "description": "Child deployment customer_id to delete.", "example": "acme_msp-d7890e123" }, "parent_id": { "type": "string", "description": "Parent MSP customer_id. Must own the child deployment.", "example": "acme_msp" } }, "required": [ "customer_id", "parent_id" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always \"success\" on 200." }, "message": { "type": "string", "description": "Human-readable deletion confirmation." }, "deleted.customer_id": { "type": "string", "description": "Deleted child deployment customer_id." }, "deleted.name": { "type": [ "string", "null" ], "description": "Deleted child deployment display name." }, "deleted.handle": { "type": [ "string", "null" ], "description": "Deleted child deployment handle." } }, "additionalProperties": true } } } }, "400": { "description": "customer_id or parent_id is missing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "missing_required_fields" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "The bearer token customer cannot manage the requested parent_id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "unauthorized" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "404": { "description": "The child deployment was not found or does not belong to the parent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "deployment_not_found" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.deployment_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-deployments-delete", "x-python-sdk": { "method": "prophet.deployments.delete(customer_id: str, parent_id: str | None = None) -> None", "docsUrl": "https://docs.prophet.io/#api-deployments-delete" } } }, "/rest/nodes/1.0": { "get": { "operationId": "nodesList", "tags": [ "Nodes" ], "summary": "List nodes", "description": "Lists gRPC-managed nodes for the authenticated customer and child deployments.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "services", "in": "query", "required": false, "description": "Include merged service configuration for each node.", "schema": { "type": "boolean" }, "example": "true" }, { "name": "hardware", "in": "query", "required": false, "description": "Include each node reported hardware block.", "schema": { "type": "boolean" }, "example": "true" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "nodes[]": { "type": "array", "items": { "type": "object" }, "description": "Tenant-scoped nodes for the caller and child deployments when the caller is a parent MSP." }, "nodes[].connection": { "type": "object", "additionalProperties": true, "description": "Derived control_plane and ingest connectivity booleans." }, "nodes[].network": { "type": "object", "additionalProperties": true, "description": "local_ip and public_ip reported by the node." }, "nodes[].health": { "type": "object", "additionalProperties": true, "description": "Last reported health status and timestamp." }, "nodes[].created_at / updated_at": { "type": "string", "description": "Record timestamps." }, "nodes[].services": { "type": "object", "additionalProperties": true, "description": "Present only when services=true." }, "nodes[].hardware": { "type": "object", "additionalProperties": true, "description": "Present only when hardware=true." } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.node_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-nodes-list", "x-python-sdk": { "method": "prophet.nodes.list(*, services: bool = False, hardware: bool = False) -> list[Node]", "docsUrl": "https://docs.prophet.io/#api-nodes-list" } } }, "/rest/nodes/1.0/outdated": { "get": { "operationId": "nodesOutdated", "tags": [ "Nodes" ], "summary": "List outdated nodes", "description": "Returns nodes whose collector version is behind the latest release for their channel.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "number", "description": "Number of outdated nodes." }, "nodes[]": { "type": "array", "items": { "type": "object" }, "description": "Compact outdated-node view." }, "nodes[].node_id": { "type": "string", "description": "Node identifier." }, "nodes[].collector_version": { "type": "string", "description": "Current node version." }, "nodes[].latest_version": { "type": [ "string", "null" ], "description": "Latest version for the node update channel." }, "nodes[].control_plane": { "type": "boolean", "description": "Whether node can receive an update right now." } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.node_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-nodes-outdated" } }, "/rest/nodes/1.0/{node_id}": { "get": { "operationId": "nodesGet", "tags": [ "Nodes" ], "summary": "Get node", "description": "Returns one node, scoped to the authenticated tenant tree.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "node_id", "in": "path", "required": true, "description": "Controller-assigned node identifier.", "schema": { "type": "string" }, "example": "node-123" }, { "name": "services", "in": "query", "required": false, "description": "Include merged service configuration.", "schema": { "type": "boolean" }, "example": "true" }, { "name": "hardware", "in": "query", "required": false, "description": "Include reported hardware block.", "schema": { "type": "boolean" }, "example": "false" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "node_id": { "type": "string", "description": "Controller-assigned node identifier." }, "machine_id": { "type": [ "string", "null" ], "description": "Stable machine identifier." }, "customer_id": { "type": "string", "description": "Owning tenant or child deployment." }, "customer_name / profile_name": { "type": [ "string", "null" ], "description": "Display names for the owning tenant and applied profile." }, "status": { "type": [ "string", "null" ], "description": "active, pending_approval, staged, or future status value." }, "network": { "type": "object", "additionalProperties": true, "description": "local_ip and public_ip reported by the node." }, "connection": { "type": "object", "additionalProperties": true, "description": "control_plane and ingest connectivity booleans." }, "health": { "type": "object", "additionalProperties": true, "description": "Health status and last_seen_at." }, "created_at / updated_at": { "type": "string", "description": "Record timestamps." } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "404": { "description": "Node is missing or outside the caller tenant tree. Body is {\"error\":\"Node not found\",\"error_type\":\"not_found\"}.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "not_found" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.node_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-nodes-get", "x-python-sdk": { "method": "prophet.nodes.get(node_id: str, *, services: bool = False, hardware: bool = False) -> Node | None", "docsUrl": "https://docs.prophet.io/#api-nodes-get" } } }, "/rest/nodes/1.0/{node_id}/diagnostics": { "get": { "operationId": "nodesDiagnostics", "tags": [ "Nodes" ], "summary": "Pull node diagnostics", "description": "Fetches supervisor diagnostics and recent logs from a connected node.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "node_id", "in": "path", "required": true, "description": "Node identifier.", "schema": { "type": "string" } }, { "name": "log_lines", "in": "query", "required": false, "description": "Recent worker log lines to return. Controller clamps this value.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "node_id": { "type": "string", "description": "Node identifier." }, "diagnostics": { "type": "object", "additionalProperties": true, "description": "Supervisor diagnostics report." }, "recent_logs": { "type": "array", "items": { "type": "object" }, "description": "Recent worker log lines." } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "404": { "description": "Node is missing or outside the caller tenant tree.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "not_found" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "409": { "description": "Node control plane is not connected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "not_connected" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "504": { "description": "Supervisor request timed out or failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "diagnostic_pull_failed" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.node_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-nodes-diagnostics" } }, "/rest/nodes/1.0/{node_id}/pprof": { "get": { "operationId": "nodesPprof", "tags": [ "Nodes" ], "summary": "Capture pprof profile", "description": "Streams a raw gzipped pprof profile for connected nodes.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "node_id", "in": "path", "required": true, "description": "Node identifier.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Profile type. Defaults to HEAP.", "schema": { "type": "string" } }, { "name": "duration", "in": "query", "required": false, "description": "Duration seconds for CPU/BLOCK/MUTEX captures; capped by controller.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "Content-Type": { "type": "string", "description": "Raw gzipped pprof profile bytes." }, "Content-Disposition": { "type": "string", "description": "Attachment filename formatted as -.pprof." } }, "additionalProperties": true } } } }, "400": { "description": "Profile type is not supported.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_type" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "404": { "description": "Node is missing or outside the caller tenant tree.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "not_found" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "409": { "description": "Node control plane is not connected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "not_connected" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "504": { "description": "Profile capture timed out or failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "pprof_capture_failed" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.node_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-nodes-pprof" } }, "/rest/nodes/1.0/{node_id}/update": { "post": { "operationId": "nodesUpdate", "tags": [ "Nodes" ], "summary": "Update node", "description": "Sends the latest collector release to a connected gRPC-managed node.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "node_id", "in": "path", "required": true, "description": "Node identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "node_id": { "type": "string", "description": "Node identifier." }, "update_status": { "type": "string", "description": "Update command result from the node handler." }, "version": { "type": "string", "description": "Latest release version for the node channel." }, "platform": { "type": [ "string", "null" ], "description": "Release platform (os_arch) — present when update_status is update_sent." } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "404": { "description": "Node is missing or outside the caller tenant tree.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "not_found" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "409": { "description": "Node control plane is not connected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "not_connected" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "502": { "description": "Node update command failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "update_failed" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.node_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-nodes-update" } }, "/rest/nodes/provision/1.0": { "post": { "operationId": "nodesProvision", "tags": [ "Nodes" ], "summary": "Provision unit credential", "description": "Mints a per-unit collector credential for a target deployment.", "security": [ { "bearerAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "description": "Target deployment customer_id. Can be the caller itself or one of its children.", "example": "acme_msp-d7890e123" }, "machine_id": { "type": "string", "description": "Stable machine identifier. The SDK can derive this from cpu_id.", "example": "8efc91d2-7f2d-529b-a59b-8f3b4e6b5c2a" }, "description": { "type": "string", "description": "Human label stored on the generated credential.", "example": "SN-0042" }, "profile_id": { "type": "string", "description": "Profile to inherit at first boot. The controller rejects unknown profile_id values.", "example": "prof-1" } }, "required": [ "customer_id" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always \"success\" on 201." }, "access_key": { "type": "string", "description": "One-time collector credential in client_id.client_secret form." }, "customer_id": { "type": "string", "description": "Target deployment customer_id." }, "machine_id": { "type": [ "string", "null" ], "description": "Machine identifier echoed from the request." }, "profile_id": { "type": [ "string", "null" ], "description": "Profile associated with this credential." } }, "additionalProperties": true } } } }, "400": { "description": "customer_id is missing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "missing_required_fields" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Target deployment is not owned by the authenticated parent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "unauthorized" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "404": { "description": "profile_id does not exist.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "profile_not_found" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.node_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-nodes-provision", "x-python-sdk": { "method": "prophet.nodes.provision(deployment: str, cpu_id: str | None = None, *, machine_id: str | None = None, description: str | None = None, profile_id: str | None = None) -> ProvisionedUnit", "docsUrl": "https://docs.prophet.io/#api-nodes-provision" } } }, "/rest/nodes/1.0/{node_id}/manage": { "post": { "operationId": "nodesManage", "tags": [ "Nodes" ], "summary": "Legacy deploy-node manage", "description": "Legacy operations for first-generation deploy nodes.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "node_id", "in": "path", "required": true, "description": "Legacy deploy node identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "string", "description": "Legacy socket operation to run." } }, "required": [ "operation" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "node_id": { "type": "string", "description": "Legacy deploy node identifier." }, "operation": { "type": "string", "description": "Operation that was requested." }, "result": { "type": "object", "additionalProperties": true, "description": "Socket response from the legacy deploy node." } }, "additionalProperties": true } } } }, "400": { "description": "operation is not one of status, logs, pull, restart, upgrade.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "unknown_operation" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "404": { "description": "Legacy deploy node is not connected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "not_connected" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "504": { "description": "Legacy socket operation timed out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "timeout" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.node_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "legacy", "x-docs-url": "https://docs.prophet.io/#api-nodes-manage" } }, "/rest/profiles/1.0": { "get": { "operationId": "profilesList", "tags": [ "Profiles" ], "summary": "List profiles", "description": "Lists reusable node capture profiles for the authenticated tenant tree.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always \"success\" on 200." }, "profiles[]": { "type": "array", "items": { "type": "object" }, "description": "Profiles owned by the caller and child deployments when caller is a parent MSP." }, "count": { "type": "number", "description": "Number of profiles returned." } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.node_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-profiles-list", "x-python-sdk": { "method": "prophet.profiles.list() -> list[Profile]", "docsUrl": "https://docs.prophet.io/#api-profiles-list" } }, "post": { "operationId": "profilesCreate", "tags": [ "Profiles" ], "summary": "Create profile", "description": "Creates a reusable capture configuration profile.", "security": [ { "bearerAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Profile display name.", "example": "Acme fleet" }, "description": { "type": "string", "description": "Optional notes for operators.", "example": "Low-footprint ARMv7 profile" }, "services": { "type": "object", "additionalProperties": true, "description": "Capture-config service blocks. A submitted service block is stored as-is; omitted services and fields fall back to server defaults when the profile is delivered to a node." }, "tags": { "type": "array", "items": { "type": "object" }, "description": "Tags applied to nodes using this profile.", "example": "edge" }, "update_channel": { "type": "string", "description": "Collector update channel. SDK default is stable.", "example": "stable" }, "fleet_staging": { "type": "boolean", "description": "When true, provision-token nodes start staged.", "example": "false" } }, "required": [ "name" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always \"success\" on 201." }, "profile": { "type": "string", "description": "Created profile document. Each submitted service block is echoed as-is; per-field defaults are applied when the profile is delivered to a node, not at create time." } }, "additionalProperties": true } } } }, "400": { "description": "name is missing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "missing_required_fields" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.node_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-profiles-create", "x-python-sdk": { "method": "prophet.profiles.create(name: str, *, description: str | None = None, services: ProfileServices | dict[str, Any] | None = None, tags: list[str] | None = None, update_channel: Literal[\"stable\", \"dev\", \"pinned\"] = \"stable\", fleet_staging: bool = False) -> Profile", "docsUrl": "https://docs.prophet.io/#api-profiles-create" } } }, "/rest/profiles/1.0/{profile_id}": { "delete": { "operationId": "profilesDelete", "tags": [ "Profiles" ], "summary": "Delete profile", "description": "Deletes a profile owned by the authenticated tenant tree.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "profile_id", "in": "path", "required": true, "description": "Profile identifier to delete.", "schema": { "type": "string" }, "example": "prof-1" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always \"success\" on 200." }, "deleted.profile_id": { "type": "string", "description": "Deleted profile identifier." } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "404": { "description": "Profile is missing or outside the caller tenant tree.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "not_found" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.node_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-profiles-delete", "x-python-sdk": { "method": "prophet.profiles.delete(profile_id: str) -> None", "docsUrl": "https://docs.prophet.io/#api-profiles-delete" } } }, "/rest/collector/download/1.0": { "get": { "operationId": "collectorDownload", "tags": [ "Collector" ], "summary": "Download collector binary", "description": "Redirects to a signed GitHub release asset for the latest collector binary.", "security": [], "parameters": [ { "name": "os", "in": "query", "required": false, "description": "Target operating system. Defaults to linux. Supported os/arch pairs: linux/amd64, linux/arm7, darwin/arm64, windows/amd64.", "schema": { "type": "string" }, "example": "linux" }, { "name": "arch", "in": "query", "required": false, "description": "Target architecture. Defaults to amd64. Only the four supported os/arch pairs are valid — there is no linux/arm64 build.", "schema": { "type": "string" }, "example": "arm7" }, { "name": "channel", "in": "query", "required": false, "description": "Release channel. Defaults to stable in production, dev in dev.", "schema": { "type": "string" }, "example": "stable" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "302 Location": { "type": "string", "description": "Temporary signed release asset URL." }, "Content-Disposition": { "type": "string", "description": "Versioned filename when the signed asset response is followed." }, "body": { "type": "string", "description": "Release tarball containing the prophet binary." } }, "additionalProperties": true } } } }, "400": { "description": "Unsupported os/arch pair. Body is {\"error\":\"Unsupported platform: /\",\"supported\":[...]} listing the valid pairs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "404": { "description": "No release, no assets, or no binary for the requested channel/platform. Body is {\"error\":\"\"}.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "500": { "description": "Release lookup failed. Body is {\"error\":\"\"}.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "public", "x-prophet-auth": "none", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-collector-download", "x-python-sdk": { "method": "prophet.collector.download(dest: str | Path | None = None, *, os: OS = \"linux\", arch: Arch = \"amd64\", channel: Channel = \"stable\", extract: bool = False, cache: bool = True) -> Path", "docsUrl": "https://docs.prophet.io/#api-collector-download" } } }, "/rest/collector/install/1.0": { "get": { "operationId": "collectorInstall", "tags": [ "Collector" ], "summary": "Get install script", "description": "Returns a Bash installer for Linux and macOS collectors.", "security": [], "parameters": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "Content-Type": { "type": "string", "description": "Bash installer script." }, "Content-Disposition": { "type": "string", "description": "Script is intended to be piped to a shell or reviewed inline." }, "body": { "type": "string", "description": "Detects OS/architecture, downloads the collector, installs the binary, and configures systemd or launchd." } }, "additionalProperties": true } } } } }, "x-prophet-scope": "public", "x-prophet-auth": "none", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-collector-install" } }, "/rest/collector/uninstall/1.0": { "get": { "operationId": "collectorUninstall", "tags": [ "Collector" ], "summary": "Get uninstall script", "description": "Returns a Bash uninstaller for collector service and local files.", "security": [], "parameters": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "Content-Type": { "type": "string", "description": "Bash uninstall script." }, "Content-Disposition": { "type": "string", "description": "Script is intended to be piped to a shell or reviewed inline." }, "body": { "type": "string", "description": "Stops and removes systemd or launchd service files, removes the collector binary, and removes local configuration." } }, "additionalProperties": true } } } } }, "x-prophet-scope": "public", "x-prophet-auth": "none", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-collector-uninstall" } }, "/search/records/1.0": { "post": { "operationId": "flowsQuery", "tags": [ "Search" ], "summary": "Query flow records", "description": "Queries flow records for one or more instances with PQL, time filters, sorting, field selection, pagination, and optional timeseries buckets.", "security": [ { "bearerAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_ids": { "type": "array", "items": { "type": "object" }, "description": "Instances or customer IDs to search.", "example": "[\"acme_msp-d7890e123\"]" }, "module": { "type": "string", "description": "Must be flows for flow record search.", "example": "flows" }, "sentence": { "type": "string", "description": "PQL query. Empty means match all.", "example": "dst.port eq 443" }, "start": { "type": "string", "description": "Start time filter. Defaults to relative 15 minutes." }, "end": { "type": "string", "description": "End time filter. Defaults to now." }, "sort": { "type": "array", "items": { "type": "object" }, "description": "Sort entries, applied in order. Defaults to @timestamp desc.", "example": "[{\"field\":\"@timestamp\",\"order\":\"desc\"}]" }, "fields": { "type": "array", "items": { "type": "object" }, "description": "Fields to include. Missing dotted paths are omitted; wildcard \"*\" is rejected. @timestamp is always included; the injected record id is dropped unless requested.", "example": "[\"src.ip\",\"dst.ip\",\"stats.volume.bytes.total\"]" }, "size": { "type": "number", "description": "Page size. Default is 15 in REST, SDK default is 100, maximum is 25000. size=0 is only valid with timeseries.", "example": "100" }, "page": { "type": "number", "description": "Zero-based page number. Offset is page * size.", "example": "0" }, "timeseries.buckets": { "type": "number", "description": "Auto date histogram bucket count. Use when interval is not supplied.", "example": "48" }, "timeseries.interval": { "type": "string", "description": "Fixed date histogram interval such as 30s, 5m, 1h, or 1d.", "example": "1h" } }, "required": [ "instance_ids", "module" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { ".flows[]": { "type": "array", "items": { "type": "object" }, "description": "Flow records. With multiple instance_ids the search runs across all of them merged, and each instance key carries the same merged result set. Each record carries an injected id (the backing document id) unless a fields projection is used." }, ".id": { "type": "string", "description": "Opaque per-response identifier; not stable across requests." }, ".found": { "type": "number", "description": "Matching document count." }, ".total": { "type": "number", "description": "Total record count for the searched window." }, ".returned": { "type": "number", "description": "Records returned in this page." }, ".page_size": { "type": "number", "description": "Page size used by this response." }, ".current_page": { "type": "number", "description": "Currently always 0 regardless of the requested page; track pagination from your request. Offset math itself honors the requested page." }, ".next_page": { "type": "number", "description": "1 when more_data_available, otherwise 0." }, ".pages": { "type": "number", "description": "Total page count: found divided by page_size, rounded up." }, ".more_data_available": { "type": "boolean", "description": "True when found exceeds page_size. Not page-aware: it stays true on the last page of a large result." }, ".count_aggregation[]": { "type": "array", "items": { "type": "object" }, "description": "Timeseries buckets with time and count when timeseries is requested." }, ".interval": { "type": [ "string", "null" ], "description": "Histogram interval returned for timeseries queries." }, ".interval_period": { "type": [ "string", "null" ], "description": "Unit suffix of the histogram interval (for example h for hours)." }, ".took": { "type": "number", "description": "Search execution time in seconds." }, "results_for[]": { "type": "array", "items": { "type": "object" }, "description": "Instance IDs searched." }, "total_time_ms": { "type": "number", "description": "End-to-end handler execution time." }, "success": { "type": "boolean", "description": "True when the request completed." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid body, module, instance_ids, date filter, sort, fields, size/page, or PQL parsing failure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "validation_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "500": { "description": "Search execution failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "search_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.search_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-flows-query", "x-python-sdk": { "method": "prophet.flows.query(instance: str, query: str | Q = \"\", start: TimeFilter | None = None, end: TimeFilter | None = None, sort: list[Sort] | None = None, fields: list[str] | None = None, size: int = 100) -> FlowIterator", "docsUrl": "https://docs.prophet.io/#api-flows-query" } } }, "/search/agg/1.0": { "post": { "operationId": "flowsTermsAgg", "tags": [ "Search" ], "summary": "Aggregate flow terms", "description": "Groups matching flows by a field and computes sum, average, or cardinality metrics for each bucket.", "security": [ { "bearerAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "module": { "type": "string", "description": "Must be terms_agg for the aggregation endpoint.", "example": "terms_agg" }, "instance_id": { "type": "string", "description": "Single instance/customer ID to aggregate.", "example": "acme_msp-d7890e123" }, "sentence": { "type": "string", "description": "PQL query. Empty means match all.", "example": "dst.port eq 443" }, "start": { "type": "string", "description": "Start time filter. Defaults to relative 15 minutes." }, "end": { "type": "string", "description": "End time filter. Defaults to now." }, "size": { "type": "number", "description": "Maximum buckets. Defaults to 100; max is 10000.", "example": "10" }, "agg.field": { "type": "string", "description": "Field to group by. Must be an aggregatable (keyword-mapped) field; free-text fields fail.", "example": "dst.ip" }, "agg.by[].field": { "type": "string", "description": "Metric field to aggregate.", "example": "stats.volume.bytes.total" }, "agg.by[].metric": { "type": "string", "description": "Metric aggregation type.", "example": "sum" }, "agg.by[].order": { "type": "string", "description": "Bucket ordering for this metric.", "example": "desc" } }, "required": [ "module", "instance_id", "agg.field", "agg.by[].field", "agg.by[].metric", "agg.by[].order" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Aggregation status." }, "results.aggregation[]": { "type": "array", "items": { "type": "object" }, "description": "Buckets. Each bucket flattens the grouped field, count, requested metrics, and an optional sample flow." }, "results.aggregation[].count": { "type": "number", "description": "Document count in the bucket." }, "results.types": { "type": "object", "additionalProperties": true, "description": "Simple metric type metadata such as bytes, packets, duration, or integer." }, "results.flows[]": { "type": "array", "items": { "type": "object" }, "description": "Sample flow documents, one per bucket when available." }, "results.found": { "type": "number", "description": "Total matching documents." }, "results.total_distinct": { "type": "number", "description": "Cardinality of the grouped field." }, "results.returned": { "type": "number", "description": "Buckets returned." }, "customer_id": { "type": "string", "description": "Echoed instance/customer ID." }, "errors": { "type": [ "string", "null" ], "description": "Error text when status is error." } }, "additionalProperties": true } } } }, "400": { "description": "Validation failure. Body is {\"status\":\"error\",\"errors\":\"\"} — text prefixed with Invalid request body, Request validation failed, Invalid date filter, or PQL parsing failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "500": { "description": "Aggregation failure. Body is {\"status\":\"error\",\"errors\":\"Terms aggregation failed: \"}.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.search_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-flows-terms-agg" } }, "/rest/investigations/1.0": { "get": { "operationId": "investigationsList", "tags": [ "Investigations" ], "summary": "List investigations", "description": "Lists Apollo investigation rollups for the authenticated tenant, filterable by verdict, confidence, and time, most severe first.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "disposition", "in": "query", "required": false, "description": "Filter by Apollo's verdict.", "schema": { "type": "string" }, "example": "escalate" }, { "name": "min_confidence", "in": "query", "required": false, "description": "Only verdicts with confidence >= this (0..1).", "schema": { "type": "number" }, "example": "0.8" }, { "name": "since", "in": "query", "required": false, "description": "Only investigations created at/after this time.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only investigations created at/before this time.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Order. Default severity (most severe first).", "schema": { "type": "string" }, "example": "recent" }, { "name": "limit", "in": "query", "required": false, "description": "Page size, clamped to 1..200. Default 50.", "schema": { "type": "number" }, "example": "25" }, { "name": "offset", "in": "query", "required": false, "description": "Page offset. Default 0.", "schema": { "type": "number" }, "example": "0" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "investigations[]": { "type": "array", "items": { "type": "object" }, "description": "Compact rollup rows for the current page." }, "investigations[].id": { "type": "string", "description": "Investigation id. Pass to GET /rest/investigations/1.0/{id}." }, "investigations[].status": { "type": "string", "description": "Lifecycle state." }, "investigations[].disposition": { "type": [ "string", "null" ], "description": "Apollo's verdict. null while running." }, "investigations[].confidence": { "type": "number", "description": "Verdict confidence 0..1. null while running." }, "investigations[].headline": { "type": [ "string", "null" ], "description": "One-line plain-language summary of the investigation." }, "investigations[].source": { "type": [ "string", "null" ], "description": "Originating entity of the flagged activity." }, "investigations[].destination": { "type": [ "string", "null" ], "description": "Counterparty of the flagged activity." }, "investigations[].detected_at": { "type": [ "string", "null" ], "description": "When the triggering activity was flagged." }, "investigations[].created_at": { "type": [ "string", "null" ], "description": "When Apollo opened the investigation." }, "investigations[].completed_at": { "type": [ "string", "null" ], "description": "When Apollo closed it. null while running." }, "investigations[].related_alerts_count": { "type": "number", "description": "Near-duplicate detections auto-linked into this one investigation." }, "investigations[].tags": { "type": "array", "items": { "type": "object" }, "description": "Free-form labels applied to the investigation." }, "total": { "type": "number", "description": "Total investigations matching the filter (for pagination)." }, "limit": { "type": "number", "description": "Page size used by this response." }, "offset": { "type": "number", "description": "Page offset used by this response." } }, "additionalProperties": true } } } }, "400": { "description": "Unknown query parameter or invalid enum/range.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_request" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "502": { "description": "Upstream engine returned a failure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "upstream_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "503": { "description": "No engine is available for the tenant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "service_unavailable" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "504": { "description": "Upstream request timed out (30s).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "upstream_timeout" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.investigations_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-investigations-list", "x-python-sdk": { "method": "prophet.investigations.list(*, disposition: str | None = None, min_confidence: float | None = None, since: str | datetime | None = None, until: str | datetime | None = None, sort: str | None = None, limit: int = 50, offset: int = 0) -> InvestigationPage", "docsUrl": "https://docs.prophet.io/#api-investigations-list" } } }, "/rest/investigations/1.0/{id}": { "get": { "operationId": "investigationsGet", "tags": [ "Investigations" ], "summary": "Get investigation", "description": "Returns one full Apollo investigation — verdict, key findings, provenance lineage, and recommended actions. Available once analysis completes.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Investigation id from the list endpoint.", "schema": { "type": "string" }, "example": "inv_43d67a..." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Investigation id." }, "status": { "type": "string", "description": "Lifecycle state (completed for any record returned)." }, "created_at": { "type": [ "string", "null" ], "description": "When Apollo opened the investigation." }, "completed_at": { "type": [ "string", "null" ], "description": "When Apollo closed it." }, "trigger.source": { "type": [ "string", "null" ], "description": "Originating entity of the flagged activity." }, "trigger.destination": { "type": [ "string", "null" ], "description": "Counterparty of the flagged activity." }, "trigger.detected_at": { "type": [ "string", "null" ], "description": "When the triggering activity was flagged." }, "trigger.signal.volume_bytes": { "type": "number", "description": "Bytes transferred on the flagged activity." }, "trigger.signal.anomaly_score": { "type": "number", "description": "Overall detector score for the flag." }, "trigger.signal.surprise": { "type": "number", "description": "How far the observed volume departs from what this source produces on its own." }, "trigger.signal.mismatch": { "type": "number", "description": "Behavioral-mismatch magnitude (0..10)." }, "verdict": { "type": "object", "additionalProperties": true, "description": "Apollo's conclusion. null while running." }, "verdict.disposition": { "type": "string", "description": "Apollo's call." }, "verdict.confidence": { "type": "number", "description": "Confidence 0..1 — calibrated on evidence held, not ideal evidence." }, "verdict.headline": { "type": "string", "description": "One- to two-sentence plain-language answer." }, "verdict.rationale": { "type": "string", "description": "Fuller reasoning, 1–3 paragraphs." }, "at_a_glance": { "type": "object", "additionalProperties": true, "description": "Known / unknown / therefore syllogism. null while running." }, "at_a_glance.known": { "type": "string", "description": "The proven core, one sentence." }, "at_a_glance.unknown": { "type": [ "string", "null" ], "description": "The single decisive unresolved fact. null when the verdict is clean." }, "at_a_glance.therefore": { "type": "string", "description": "The call plus the single most important next move." }, "key_findings[]": { "type": "array", "items": { "type": "object" }, "description": "The observations that drove the verdict." }, "key_findings[].headline": { "type": "string", "description": "The scannable takeaway." }, "key_findings[].observation": { "type": "string", "description": "What was observed — specific and traceable." }, "key_findings[].significance": { "type": "string", "description": "Why it matters." }, "key_findings[].role": { "type": "string", "description": "Epistemic role of the finding." }, "key_findings[].importance": { "type": "string", "description": "Relative weight of the finding." }, "key_findings[].rules_out": { "type": "array", "items": { "type": "object" }, "description": "Candidate explanations this finding rules out (resolved names)." }, "key_findings[].confirms": { "type": "array", "items": { "type": "object" }, "description": "Candidate explanations this finding confirms (resolved names)." }, "key_findings[].timeline[]": { "type": "array", "items": { "type": "object" }, "description": "Temporal anchors: { at, label, children? }." }, "key_findings[].traffic_links[]": { "type": "array", "items": { "type": "object" }, "description": "Replayable pointers into the underlying flows." }, "key_findings[].traffic_links[].label": { "type": "string", "description": "Chip text, e.g. \"April 9 upload flows (78 flows)\"." }, "key_findings[].traffic_links[].rationale": { "type": [ "string", "null" ], "description": "Why this query demonstrates the finding." }, "key_findings[].traffic_links[].query": { "type": "object", "additionalProperties": true, "description": "The internal search query (tenant fields stripped). Opaque/unstable in v1." }, "provenance": { "type": "object", "additionalProperties": true, "description": "Access→exfiltration lineage. null when the source host collects no host-logs." }, "provenance.available": { "type": "boolean", "description": "Whether a chain was reconstructed. When false, render the ceiling not an empty chain." }, "provenance.unavailable_reason": { "type": [ "string", "null" ], "description": "Why no chain (e.g. host collects no host-logs)." }, "provenance.headline": { "type": [ "string", "null" ], "description": "One-line narrative of the whole chain." }, "provenance.host": { "type": [ "string", "null" ], "description": "Resolved source hostname." }, "provenance.completeness": { "type": "number", "description": "Fraction of legs directly observed (0..1)." }, "provenance.host_value": { "type": "object", "additionalProperties": true, "description": "What the host is worth to an attacker: { role, value, reach }." }, "provenance.host_value.value": { "type": "string", "description": "Attacker value of the host." }, "provenance.legs[]": { "type": "array", "items": { "type": "object" }, "description": "Ordered kill-chain steps." }, "provenance.legs[].stage": { "type": "string", "description": "Kill-chain tactic bucket." }, "provenance.legs[].title": { "type": "string", "description": "Display heading, e.g. \"Exfiltration\"." }, "provenance.legs[].headline": { "type": "string", "description": "One-line leg takeaway." }, "provenance.legs[].detail": { "type": [ "string", "null" ], "description": "Longer detail for the leg." }, "provenance.legs[].confidence": { "type": "string", "description": "Evidentiary confidence for the leg." }, "provenance.legs[].gap_reason": { "type": [ "string", "null" ], "description": "Why the link is not directly observed (when confidence ≠ directly_observed)." }, "provenance.legs[].at": { "type": [ "string", "null" ], "description": "When (ISO-8601 or window string)." }, "provenance.legs[].actors[]": { "type": "array", "items": { "type": "object" }, "description": "The who/what on this leg: { kind, label, detail? }." }, "provenance.legs[].actors[].kind": { "type": "string", "description": "Actor type." }, "provenance.legs[].attack[]": { "type": "array", "items": { "type": "object" }, "description": "MITRE ATT&CK techniques: { tactic, technique_id, technique }." }, "provenance.legs[].pivot_keys": { "type": "array", "items": { "type": "object" }, "description": "Join keys linking this leg to adjacent ones, e.g. [\"uid=1002\"]." }, "decision_support.confidence_limits": { "type": [ "string", "null" ], "description": "The honest cap on certainty given available telemetry." }, "decision_support.what_would_change_the_verdict": { "type": [ "string", "null" ], "description": "The single artifact that would flip the verdict." }, "decision_support.open_questions[]": { "type": "array", "items": { "type": "object" }, "description": "Unresolved questions: { question, needed_data?, priority? }." }, "decision_support.open_questions[].priority": { "type": "string", "description": "Priority of the question." }, "decision_support.recommended_actions[]": { "type": "array", "items": { "type": "object" }, "description": "Next steps: { timeframe, action }." }, "meta.generated_at": { "type": [ "string", "null" ], "description": "When this analysis was produced." }, "meta.ai_generated": { "type": "string", "description": "Always true — the analysis is AI-authored." }, "meta.analysis_version": { "type": [ "string", "null" ], "description": "Opaque version of the analysis format." } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "404": { "description": "Investigation does not exist, is not yours, has not finished yet, or the upstream lookup failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "not_found" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "503": { "description": "No engine is available for the tenant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "service_unavailable" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "504": { "description": "Upstream request timed out (30s).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "upstream_timeout" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.investigations_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-investigations-get", "x-python-sdk": { "method": "prophet.investigations.get(investigation_id: str) -> Investigation | None", "docsUrl": "https://docs.prophet.io/#api-investigations-get" } } }, "/rest/events/1.0/{customerId}": { "get": { "operationId": "eventsTopics", "tags": [ "Events" ], "summary": "Fetch event topics", "description": "Fetches plugin event topics for a customer.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "Tenant/customer ID whose event topics should be fetched.", "schema": { "type": "string" }, "example": "acme_msp-d7890e123" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "start": { "type": "string", "description": "Start date filter. Defaults to relative 15 minutes." }, "end": { "type": "string", "description": "End date filter. Defaults to now." }, "modules": { "type": "array", "items": { "type": "object" }, "description": "Module filter. Omit to apply no module filter.", "example": "[\"infrastructure\"]" }, "states": { "type": "array", "items": { "type": "object" }, "description": "Event state filter.", "example": "[\"active\"]" }, "plugins": { "type": "array", "items": { "type": "object" }, "description": "Plugin name filter.", "example": "[\"zeek\"]" }, "labels": { "type": "array", "items": { "type": "object" }, "description": "Label filter applied to event records.", "example": "[\"prod\"]" }, "sort": { "type": "array", "items": { "type": "object" }, "description": "Sort entries applied to the result set.", "example": "[{\"field\":\"@timestamp\",\"order\":\"desc\"}]" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "string", "description": "Operation echoed in the response." }, "status": { "type": "string", "description": "Request status, usually success." }, "events[]": { "type": "array", "items": { "type": "object" }, "description": "Event topic summaries returned as notifications." }, "returned": { "type": "number", "description": "Number of topics returned." } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": ":customerId is outside the caller tenant tree.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "cross_instance_authorization" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "500": { "description": "Upstream request failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "compute_engine_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.event_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-events-topics" } }, "/rest/events/1.0/{customerId}/{eventId}": { "get": { "operationId": "eventsRecords", "tags": [ "Events" ], "summary": "Fetch event records", "description": "Fetches event records for one event topic.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "Tenant/customer ID whose records should be fetched.", "schema": { "type": "string" }, "example": "acme_msp-d7890e123" }, { "name": "eventId", "in": "path", "required": true, "description": "Event topic identifier.", "schema": { "type": "string" }, "example": "evt-123" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "start": { "type": "string", "description": "Start date filter. Defaults to relative 15 minutes." }, "end": { "type": "string", "description": "End date filter. Defaults to now." }, "sort": { "type": "array", "items": { "type": "object" }, "description": "Sort entries applied to the result set.", "example": "[{\"field\":\"@timestamp\",\"order\":\"desc\"}]" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "page_size": { "type": "number", "description": "Page size from searchProps when returned by the engine." }, "page_next": { "type": "number", "description": "Next page cursor from searchProps when returned by the engine." }, "returned": { "type": "number", "description": "Number of event records returned." }, "operation": { "type": "object", "additionalProperties": true, "description": "Operation echoed in the response." }, "status": { "type": "string", "description": "Request status, usually success." }, "parts[]": { "type": "array", "items": { "type": "object" }, "description": "Event record rows for the topic." } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": ":customerId is outside the caller tenant tree.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "cross_instance_authorization" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "500": { "description": "Upstream request failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "compute_engine_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.event_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-events-records" } }, "/rest/automation/1.0": { "get": { "operationId": "automationList", "tags": [ "Automation" ], "summary": "List or fetch automations", "description": "Lists automations or fetches one automation when both id and feed_id are supplied.", "security": [ { "bearerAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_id": { "type": "string", "description": "Target tenant/customer ID.", "example": "acme_msp-d7890e123" }, "filter": { "type": "string", "description": "Text filter forwarded as textFilter to the automation engine.", "example": "dns" }, "id": { "type": "string", "description": "Automation ID. Include feed_id with id to fetch one automation.", "example": "auto-123" }, "feed_id": { "type": "string", "description": "Automation feed. Defaults to local; required with id when fetching one automation.", "example": "local" } }, "required": [ "instance_id" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Automation engine status." }, "operation": { "type": "array", "items": { "type": "object" }, "description": "list when id is omitted, fetch when id and feed_id are supplied." }, "automations[]": { "type": "array", "items": { "type": "object" }, "description": "Declarative automations for list responses." }, "automation": { "type": "object", "additionalProperties": true, "description": "Declarative automation for fetch responses." }, "message": { "type": [ "string", "null" ], "description": "Error or informational message when returned by the engine." } }, "additionalProperties": true } } } }, "400": { "description": "id and feed_id must be supplied together when fetching one automation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "body.validation" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "instance_id is missing or outside the caller tenant tree.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "cross_instance_authorization" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.automation_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-automation-list" }, "post": { "operationId": "automationSet", "tags": [ "Automation" ], "summary": "Create or update automation", "description": "Creates or updates an automation pipeline for a tenant.", "security": [ { "bearerAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_id": { "type": "string", "description": "Target tenant/customer ID.", "example": "acme_msp-d7890e123" }, "name": { "type": "string", "description": "Automation display name.", "example": "DNS exfiltration guard" }, "pipeline": { "type": "array", "items": { "type": "object" }, "description": "Declarative automation pipeline forwarded to the automation engine." }, "tags": { "type": "array", "items": { "type": "object" }, "description": "Tags stored with the automation. Defaults to an empty list.", "example": "[\"dns\"]" }, "feed_id": { "type": "string", "description": "Automation feed. Defaults to local.", "example": "local" }, "id": { "type": "string", "description": "Automation ID. Defaults to a generated UUID for creates.", "example": "auto-123" }, "enabled": { "type": "boolean", "description": "Enabled state. Controller coerces with Boolean(enabled).", "example": "true" } }, "required": [ "instance_id", "name", "pipeline" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Automation engine status." }, "operation": { "type": "string", "description": "Create/update operation." }, "automation": { "type": "object", "additionalProperties": true, "description": "Saved declarative automation returned by the automation engine." }, "message": { "type": [ "string", "null" ], "description": "Error message when the engine reports status error." }, "customer_id": { "type": [ "string", "null" ], "description": "Customer ID included by the engine on errors." } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "instance_id is missing or outside the caller tenant tree.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "cross_instance_authorization" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.automation_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-automation-set" }, "delete": { "operationId": "automationDelete", "tags": [ "Automation" ], "summary": "Delete automation", "description": "Deletes an automation by ID for the scoped instance.", "security": [ { "bearerAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_id": { "type": "string", "description": "Target tenant/customer ID.", "example": "acme_msp-d7890e123" }, "id": { "type": "string", "description": "Automation ID to delete.", "example": "auto-123" } }, "required": [ "instance_id", "id" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "success when deleted, info when the automation does not exist, or error from the engine." }, "operation": { "type": "string", "description": "Delete operation." }, "message": { "type": [ "string", "null" ], "description": "Informational or error message returned by the engine." }, "customer_id": { "type": [ "string", "null" ], "description": "Customer ID included by the engine on errors." } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "instance_id is missing or outside the caller tenant tree.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "cross_instance_authorization" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.automation_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-automation-delete" } }, "/rest/explore/1.0/egress/organizations": { "get": { "operationId": "exploreEgressOrganizations", "tags": [ "Explore" ], "summary": "List external organizations", "description": "External organizations the network sent traffic to, ranked by volume and merged across instance_ids.", "security": [ { "bearerAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_ids": { "type": "array", "items": { "type": "object" }, "description": "Instances/customer IDs to aggregate over (merged). Self or authorized children.", "example": "[\"acme_msp-d7890e123\"]" }, "start": { "type": "string", "description": "Start time filter. Defaults to relative 24 hours." }, "end": { "type": "string", "description": "End time filter. Defaults to now." }, "size": { "type": "number", "description": "Maximum organizations to return.", "example": "25" } }, "required": [ "instance_ids" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "organizations[].name": { "type": "string", "description": "Organization name (dst.ctx.organization)." }, "organizations[].industry": { "type": [ "string", "null" ], "description": "Classified industry for the organization." }, "organizations[].apps[]": { "type": "array", "items": { "type": "object" }, "description": "Up to three top application labels by flow count." }, "organizations[].bytes": { "type": "number", "description": "Total bytes (upload + download)." }, "organizations[].upload": { "type": "number", "description": "Egress bytes (network -> org)." }, "organizations[].download": { "type": "number", "description": "Ingress bytes (org -> network)." }, "organizations[].flows": { "type": "number", "description": "Flow records in the window." }, "organizations[].sources": { "type": "number", "description": "Distinct internal hosts talking to the org." }, "total_orgs": { "type": "number", "description": "Distinct external organizations in the window." }, "coverage.classified_in_page": { "type": "number", "description": "Flows behind the returned orgs. Org classification covers a minority of flows." }, "coverage.total_flows": { "type": "number", "description": "Total flows in the window." }, "base_pql": { "type": "string", "description": "PQL fragment scoping the egress view; combine it with your own predicates in the Search API." }, "results_for[]": { "type": "array", "items": { "type": "object" }, "description": "Instance IDs the merged data covers." }, "status": { "type": "string", "description": "success on 200; failure with ui_message when the query fails." } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.explore_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-explore-egress-organizations", "x-python-sdk": { "method": "prophet.explore.egress.organizations(instances: str | list[str], *, start: TimeFilter | None = None, end: TimeFilter | None = None, size: int = 25) -> OrganizationList", "docsUrl": "https://docs.prophet.io/#api-explore-egress-organizations" } } }, "/rest/explore/1.0/egress/organizations/{org}": { "get": { "operationId": "exploreEgressOrganization", "tags": [ "Explore" ], "summary": "Organization header", "description": "Stable header attributes for one organization: geo, industry, host and endpoint counts, processes, and a plain-language readout.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization name (dst.ctx.organization).", "schema": { "type": "string" }, "example": "google" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_ids": { "type": "array", "items": { "type": "object" }, "description": "Instances/customer IDs to aggregate over.", "example": "[\"acme_msp-d7890e123\"]" }, "start": { "type": "string", "description": "Start time filter. Defaults to relative 24 hours." }, "end": { "type": "string", "description": "End time filter. Defaults to now." }, "src_ip": { "type": "string", "description": "Scope to one internal host -> org relationship.", "example": "10.0.0.10" } }, "required": [ "instance_ids" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "org": { "type": "string", "description": "Organization name." }, "industry": { "type": [ "string", "null" ], "description": "Classified industry." }, "geo": { "type": [ "string", "null" ], "description": "Top destination country." }, "upload / download": { "type": "number", "description": "Egress / ingress bytes." }, "sources / endpoints": { "type": "number", "description": "Distinct internal hosts / org endpoints." }, "processes[]": { "type": "array", "items": { "type": "object" }, "description": "Top internal processes reaching the org (packet-sourced)." }, "readout": { "type": "string", "description": "Plain-language summary." }, "results_for[]": { "type": "array", "items": { "type": "object" }, "description": "Instance IDs covered." } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.explore_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-explore-egress-organization", "x-python-sdk": { "method": "prophet.explore.egress.organization(instances: str | list[str], org: str, *, start: TimeFilter | None = None, end: TimeFilter | None = None, src_ip: str | None = None) -> OrganizationHeader", "docsUrl": "https://docs.prophet.io/#api-explore-egress-organization" } } }, "/rest/explore/1.0/egress/organizations/{org}/temporal": { "get": { "operationId": "exploreEgressTemporal", "tags": [ "Explore" ], "summary": "Organization — temporal", "description": "WHEN: a day-of-week by hour-of-day heatmap of traffic to the organization.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization name.", "schema": { "type": "string" }, "example": "google" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_ids": { "type": "array", "items": { "type": "object" }, "description": "Instances to aggregate over.", "example": "[\"acme_msp-d7890e123\"]" }, "start": { "type": "string", "description": "Start time. Defaults to relative 7 days." }, "end": { "type": "string", "description": "End time. Defaults to now." }, "src_ip": { "type": "string", "description": "Scope to one host.", "example": "10.0.0.10" } }, "required": [ "instance_ids" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cells[].row": { "type": "string", "description": "Day-of-week label (Mon..Sun)." }, "cells[].col": { "type": "string", "description": "Hour-of-day label (00..23)." }, "cells[].value": { "type": "number", "description": "Flow count for that day/hour cell." }, "rows": { "type": "array", "items": { "type": "object" }, "description": "Ordered day labels (Mon..Sun)." }, "cols": { "type": "array", "items": { "type": "object" }, "description": "Ordered hour labels (00..23)." }, "total": { "type": "number", "description": "Total flows in the window." }, "readout": { "type": "string", "description": "e.g. \"always-on — traffic in nearly every hour (automated)\"." } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.explore_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-explore-egress-temporal", "x-python-sdk": { "method": "prophet.explore.egress.temporal(instances, org, *, start=None, end=None, src_ip=None) -> Temporal", "docsUrl": "https://docs.prophet.io/#api-explore-egress-temporal" } } }, "/rest/explore/1.0/egress/organizations/{org}/cadence": { "get": { "operationId": "exploreEgressCadence", "tags": [ "Explore" ], "summary": "Organization — cadence", "description": "RHYTHM: is the communication consistent or random? The session-gap CDF (stepped = machine-driven) plus the beacon-flagged subset.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization name.", "schema": { "type": "string" }, "example": "google" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_ids": { "type": "array", "items": { "type": "object" }, "description": "Instances to aggregate over.", "example": "[\"acme_msp-d7890e123\"]" }, "start": { "type": "string", "description": "Start time. Defaults to relative 24 hours." }, "end": { "type": "string", "description": "End time. Defaults to now." }, "src_ip": { "type": "string", "description": "Scope to one internal host -> org relationship.", "example": "10.0.0.10" } }, "required": [ "instance_ids" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cdf[].gap_secs": { "type": "number", "description": "Session-gap value at this point of the CDF, in seconds." }, "cdf[].fraction": { "type": "number", "description": "Fraction of sessions with a gap at or below gap_secs (0..1)." }, "dominant_intervals[]": { "type": "array", "items": { "type": "object" }, "description": "Up to three dominant beats — vertical steps of the CDF holding at least 15% of the mass. A strong beat means a scheduler owns the relationship." }, "steppedness": { "type": "number", "description": "Mass fraction of the largest beat (~1.0 means one interval dominates: machine-driven)." }, "median_gap_secs": { "type": "number", "description": "Median session gap in seconds." }, "stats": { "type": "object", "additionalProperties": true, "description": "Map of metric name -> value: mean regularity, mean_gap (seconds), and burstiness." }, "beacon.flows": { "type": "number", "description": "Beacon-flagged (periodic) flow count." }, "beacon.sources": { "type": "number", "description": "Distinct sources with beacon-flagged flows." }, "beacon.interval_ms": { "type": "number", "description": "Mean detected beacon interval in milliseconds." }, "readout": { "type": "string", "description": "e.g. \"steady rhythm, ~60 s between flows\"." } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.explore_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-explore-egress-cadence", "x-python-sdk": { "method": "prophet.explore.egress.cadence(instances, org, *, start=None, end=None, src_ip=None) -> Cadence", "docsUrl": "https://docs.prophet.io/#api-explore-egress-cadence" } } }, "/rest/explore/1.0/egress/organizations/{org}/transfer": { "get": { "operationId": "exploreEgressTransfer", "tags": [ "Explore" ], "summary": "Organization — transfer", "description": "WHAT IS MOVED: chunk size (mean and coefficient of variation), payload entropy, session duration, and upload/download split.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization name.", "schema": { "type": "string" }, "example": "mongodb" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_ids": { "type": "array", "items": { "type": "object" }, "description": "Instances to aggregate over.", "example": "[\"acme_msp-d7890e123\"]" }, "start": { "type": "string", "description": "Start time. Defaults to relative 24 hours." }, "end": { "type": "string", "description": "End time. Defaults to now." } }, "required": [ "instance_ids" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfer.chunk_bytes_mean": { "type": "number", "description": "Mean packet/chunk size (packet-sourced)." }, "transfer.chunk_cv": { "type": "number", "description": "Coefficient of variation — low is uniform (bulk sync), high is mixed." }, "transfer.entropy_mean": { "type": "number", "description": "Mean payload entropy (encrypted/compressed when high)." }, "transfer.duration_mean": { "type": "number", "description": "Mean session duration in seconds." }, "transfer.up / transfer.down": { "type": "number", "description": "Egress / ingress bytes." }, "readout": { "type": "string", "description": "e.g. \"~64 KB uniform chunks, encrypted, upload-heavy\"." } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.explore_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-explore-egress-transfer", "x-python-sdk": { "method": "prophet.explore.egress.transfer(instances, org, *, start=None, end=None, src_ip=None) -> Transfer", "docsUrl": "https://docs.prophet.io/#api-explore-egress-transfer" } } }, "/rest/explore/1.0/egress/organizations/{org}/reach": { "get": { "operationId": "exploreEgressReach", "tags": [ "Explore" ], "summary": "Organization — reach", "description": "WHO / WHAT: the internal sources and processes reaching the organization.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization name.", "schema": { "type": "string" }, "example": "jumpcloud" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_ids": { "type": "array", "items": { "type": "object" }, "description": "Instances to aggregate over.", "example": "[\"acme_msp-d7890e123\"]" }, "start": { "type": "string", "description": "Start time. Defaults to relative 24 hours." }, "end": { "type": "string", "description": "End time. Defaults to now." }, "size": { "type": "number", "description": "Maximum sources to return.", "example": "50" } }, "required": [ "instance_ids" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sources[].ip": { "type": "string", "description": "Internal host IP." }, "sources[].upload": { "type": "number", "description": "Egress bytes from this host to the org." }, "sources[].download": { "type": "number", "description": "Ingress bytes from the org to this host." }, "sources[].flows": { "type": "number", "description": "Flow records for this host." }, "processes[].name": { "type": "string", "description": "Process name (packet-sourced eBPF attribution)." }, "processes[].flows": { "type": "number", "description": "Flow records attributed to the process." }, "processes[].sources": { "type": "number", "description": "Distinct internal hosts running the process." }, "source_count": { "type": "number", "description": "Distinct internal hosts." }, "readout": { "type": "string", "description": "e.g. \"26 internal host(s) -> 25 endpoint(s); driven by jumpcloud-agent\"." } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.explore_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-explore-egress-reach", "x-python-sdk": { "method": "prophet.explore.egress.reach(instances, org, *, start=None, end=None, src_ip=None, size=50) -> Reach", "docsUrl": "https://docs.prophet.io/#api-explore-egress-reach" } } }, "/rest/explore/1.0/egress/organizations/{org}/access": { "get": { "operationId": "exploreEgressAccess", "tags": [ "Explore" ], "summary": "Organization — access", "description": "HOW REACHED: TLS versions, ports, protocols, and applications used to reach the organization.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization name.", "schema": { "type": "string" }, "example": "google" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_ids": { "type": "array", "items": { "type": "object" }, "description": "Instances to aggregate over.", "example": "[\"acme_msp-d7890e123\"]" }, "start": { "type": "string", "description": "Start time. Defaults to relative 24 hours." }, "end": { "type": "string", "description": "End time. Defaults to now." } }, "required": [ "instance_ids" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tls_versions[].name": { "type": "string", "description": "TLS version label (e.g. TLS 1.3)." }, "tls_versions[].flows": { "type": "number", "description": "Flow records at this TLS version." }, "tls_versions[].bytes": { "type": "number", "description": "Total bytes at this TLS version." }, "ports[]": { "type": "array", "items": { "type": "object" }, "description": "Destination ports. Same row shape as tls_versions[]." }, "protocols[]": { "type": "array", "items": { "type": "object" }, "description": "Transport protocols. Same row shape as tls_versions[]." }, "apps[]": { "type": "array", "items": { "type": "object" }, "description": "Application labels from protocol classification. Same row shape as tls_versions[]." }, "readout": { "type": "string", "description": "e.g. \"TLS 1.3 / port 443 / HTTPS.Google\"." } }, "additionalProperties": true } } } }, "401": { "description": "Missing, expired, or invalid bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "403": { "description": "Token lacks the required scope or tenant access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "authorization_error" }, "message": { "type": "string" } }, "additionalProperties": true } } } } }, "x-prophet-scope": "p.token.scope.explore_api", "x-prophet-auth": "bearer token", "x-prophet-version": "1.0", "x-prophet-stability": "stable", "x-docs-url": "https://docs.prophet.io/#api-explore-egress-access", "x-python-sdk": { "method": "prophet.explore.egress.access(instances, org, *, start=None, end=None, src_ip=None) -> Access", "docsUrl": "https://docs.prophet.io/#api-explore-egress-access" } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } } }