Sign in

v1

latestOpenAPI 3.1.0Apache 2.02026-07-1233591.8 KB
apex

Processes the scan request.

post/_acuvity/scan

Request body

accessPolicystring

AccessPolicy allows to pass optional Rego access policy. If not set, The action is always Allow, If it is set, it will be run, and the final decision will be computed based on that policy. If the rego code does not start with package main, then the needed classic package definition and acuvity imports will be added automatically. If the code starts with package main, then everything remains untouched.

analyzersstring[]

The analyzers parameter allows for customizing which analyzers should be used, overriding the default selection. Each analyzer entry can optionally include a prefix to modify its behavior:

  • No prefix: Runs only the specified analyzers and any dependencies required for deeper analysis (slower but more acurate).
  • '+' (enable): Activates an analyzer that is disabled by default.
  • '-' (disable): Disables an analyzer that is enabled by default.
  • '@' (direct execution): Runs the analyzer immediately, bypassing the deeper analysis (faster but less acurate).

An analyzers entry can be specified using:

  • The analyzer name (e.g., 'Toxicity detector')
  • The analyzer ID (e.g., 'en-text-toxicity-detector')
  • The analyzer group (e.g., 'Detectors')
  • A detector name (e.g., 'toxic')
  • A detector label (e.g., 'insult')
  • A detector group (e.g., 'Malcontents')

If left empty, all default analyzers will be executed.

annotationsobject

Annotations attached to the extraction.

anonymization'FixedSize' | 'VariableSize'

How to anonymize the data. If deanonymize is true, then VariablSize is required.

bypassHashstring

In the case of a contentPolicy that asks for a confirmation, this is the hash you must send back to bypass the block. This is only useful when a content policy has been set or is evaluated remotely.

contentPolicystring

ContentPolicy allows to pass optional Rego content policy. If not set, The action is always Allow, and there cannot be any alerts raised etc If it is set, it will be run, and the final decision will be computed based on that policy. If the rego code does not start with package main, then the needed classic package definition and acuvity imports will be added automatically. If the code starts with package main, then everything remains untouched.

keywordsstring[]

The keywords found during classification.

messagesstring[]

Messages to process and provide detections for. Use data in extractions for processing binary data.

minimalLoggingboolean

If true, the system will skip logging roundtrips with an Allow decision. Denials, errors, and other non-Allow decisions are still logged. When combined with no embedded policy, this effectively disables all logging.

modelstring

The model used by the request.

providerstring

The name of the provider to use for policy resolutions. Must not be set when destination app and component are set.

redactionsstring[]

The redactions to perform if they are detected.

toolsobject

The various tools used by the request.

type'Input' | 'Output'

The type of text.

Example request

{
  "analyzers": [
    "Malcontents"
  ],
  "annotations": {
    "key1": "value1",
    "key2": "value2"
  },
  "app": {
    "IP": "192.0.2.42",
    "component": "email-agent",
    "name": "acme-ai-app",
    "userClaims": [
      "name=John Doe",
      "email=john.doe@acme.com",
      "@validated=false"
    ],
    "username": "john.doe@acme.com"
  },
  "bypassHash": "6f37d752-bce1-4973-88f6-28b6c100ceb8",
  "destination": {
    "app": "other-ai-app",
    "component": "backend",
    "host": "api.openai.com",
    "ip": "192.0.2.42"
  },
  "extractions": [
    {
      "toolResults": [
        {
          "callID": "toolu_019X5QaEeVTDFrQPHqMMgd1n",
          "name": "fetch",
          "serverName": "my-mcp-server"
        }
      ],
      "toolUses": [
        {
          "callID": "toolu_019X5QaEeVTDFrQPHqMMgd1n",
          "name": "get_weather",
          "serverName": "deepwiki"
        }
      ]
    }
  ],
  "keywords": [
    "legal",
    "technical",
    "scientific"
  ],
  "messages": [
    "Summarize the main points of this article in bullet points.",
    "Generate a list of creative product names for a futuristic tech gadget."
  ],
  "model": "claude-3-7-sonnet",
  "provider": "openai",
  "redactions": [
    "person",
    "ssn",
    "location"
  ]
}

Response

Successfully processing a scan request returns a scan response.

IDstring

ID is the identifier of the object.

annotationsobject

Annotations attached to the log.

clientstring

The client used to send the request.

clientVersionstring

The version of the client used to send the request.

decision'Deny' | 'Allow' | 'Ask' | 'Report' | 'Bypassed' | 'ForbiddenUser' | 'Skipped' | 'Redirected' | 'NotApplicable' | 'Error' | 'UpstreamError'

User-facing outcome of the roundtrip. Reflects the policy engine's verdict, or in case of platform failure, the result of the failClose strategy (Deny on fail-close, Allow on fail-open, with structured error field carring the detail). NotApplicable is used by the scan and police APIs, which analyze content without rendering an enforcement decision. Error and UpstreamError stay in the allowed_choices list for backward compatibility with clients that still PUT those values; new round-trips never emit them — platform/upstream failures now surface via the structured Error field instead. NOTE: safe to drop Error and UpstreamError from this enum on or after 2026-07-19 (two months after the structured RoundtripError landed on 2026-05-19), once consumers have rolled forward.

hashstring

The hash of the input.

modelstring

The model used by the request.

namespacestring

The namespace of the object.

pipelineNamestring

The name of the particular pipeline that extracted the text.

providerstring

The provider to use.

providerType'LLM' | 'MCPServer' required

The type of the provider.

reasonsstring[]

The various reasons returned by the policy engine.

timestring date-time

Set the time of the message request.

toolsobject

The various tools used by the request.

type'Input' | 'Output'

The type of text.

Example response

{
  "alerts": [
    {
      "alertDefinition": "warning-notification",
      "principal": {
        "IP": "192.0.2.42",
        "app": {
          "component": "frontend",
          "labels": [
            "country=us",
            "another-label"
          ],
          "name": "MyApp",
          "userClaims": [
            "name=John Doe",
            "email=john.doe@acme.com",
            "@validated=false"
          ],
          "username": "john.doe@acme.com",
          "workloadGroupHash": "wg-0ff92a76a3765740e26d84947d92e5fc",
          "workloadGroupLabel": "k8s:deployment=mcp-chatbot-agent,namespace=demo",
          "workloadGroupSetHash": "wgs-0ff92a76a3765740e26d84947d92e5fc",
          "workloadGroupSetLabel": "k8s:namespace=demo"
        },
        "external": {
          "userClaims": [
            "name=John Doe",
            "email=john.doe@acme.com",
            "@validated=false"
          ],
          "username": "john.doe@acme.com",
          "workloadGroupHash": "wg-0ff92a76a3765740e26d84947d92e5fc",
          "workloadGroupLabel": "k8s:deployment=mcp-chatbot-agent,namespace=demo",
          "workloadGroupSetHash": "wgs-0ff92a76a3765740e26d84947d92e5fc",
          "workloadGroupSetLabel": "k8s:namespace=demo"
        },
        "tokenID": "1234-1224-123-1",
        "tokenName": "my-user-token",
        "user": {
          "name": "user@company.com"
        }
      }
    }
  ],
  "client": "curl",
  "clientVersion": "7.64.1",
  "extractions": [
    {
      "PIIs": {
        "ssn": 0.8
      },
      "categories": [
        {
          "group": "image",
          "type": "png"
        }
      ],
      "confidentiality": 0.9,
      "customDataTypes": {
        "my_cdt": 1
      },
      "dataSets": {
        "cds": {
          "ct1": 1,
          "ct2": 2
        }
      },
      "exploits": {
        "prompt_injection": 0.8
      },
      "intent": {
        "write": 0.8
      },
      "keywords": {
        "my_keywork": 0.8
      },
      "languages": {
        "english": 0.8
      },
      "malcontents": {
        "toxic": 0.8
      },
      "modalities": [
        {
          "group": "image",
          "type": "png"
        }
      ],
      "relevance": 0.9,
      "secrets": {
        "credentials": 0.7
      },
      "toolResults": [
        {
          "callID": "toolu_019X5QaEeVTDFrQPHqMMgd1n",
          "name": "fetch",
          "serverName": "my-mcp-server"
        }
      ],
      "toolUses": [
        {
          "callID": "toolu_019X5QaEeVTDFrQPHqMMgd1n",
          "name": "get_weather",
          "serverName": "deepwiki"
        }
      ],
      "topics": {
        "category/enterprise": 0.7,
        "department/logistics": 0.8,
        "depict/document": 0.8,
        "extracted/typed_text_content": 1,
        "timeframe/current_year": 0.6
      }
    }
  ],
  "mcpMessage": {
    "direction": "Client2Server",
    "gatewayName": "maxibridge",
    "method": "tools/call",
    "paramsName": "search",
    "requestID": "2",
    "sessionID": "1f02aa20-22d8-6e87-8432-be15d4f7b5b2",
    "type": "Request"
  },
  "model": "claude-3-7-sonnet",
  "principal": {
    "IP": "192.0.2.42",
    "app": {
      "component": "frontend",
      "labels": [
        "country=us",
        "another-label"
      ],
      "name": "MyApp",
      "userClaims": [
        "name=John Doe",
        "email=john.doe@acme.com",
        "@validated=false"
      ],
      "username": "john.doe@acme.com",
      "workloadGroupHash": "wg-0ff92a76a3765740e26d84947d92e5fc",
      "workloadGroupLabel": "k8s:deployment=mcp-chatbot-agent,namespace=demo",
      "workloadGroupSetHash": "wgs-0ff92a76a3765740e26d84947d92e5fc",
      "workloadGroupSetLabel": "k8s:namespace=demo"
    },
    "external": {
      "userClaims": [
        "name=John Doe",
        "email=john.doe@acme.com",
        "@validated=false"
      ],
      "username": "john.doe@acme.com",
      "workloadGroupHash": "wg-0ff92a76a3765740e26d84947d92e5fc",
      "workloadGroupLabel": "k8s:deployment=mcp-chatbot-agent,namespace=demo",
      "workloadGroupSetHash": "wgs-0ff92a76a3765740e26d84947d92e5fc",
      "workloadGroupSetLabel": "k8s:namespace=demo"
    },
    "tokenID": "1234-1224-123-1",
    "tokenName": "my-user-token",
    "user": {
      "name": "user@company.com"
    }
  },
  "provider": "openai",
  "providerType": "LLM",
  "trace": {
    "kind": "Server",
    "parentSpanID": "00f067aa0ba902b7",
    "spanEnd": "2025-03-22T14:35:00.123456789Z",
    "spanID": "6ba80aaa3b2f43d8",
    "spanName": "acuvity_prompt_input_analysis",
    "spanStart": "2025-03-22T14:35:00.123456789Z",
    "statusCode": "OK",
    "statusMessage": "Failed to make API call to service Foo.",
    "traceID": "4bf92f3577b34da6a3ce929d0e0e4736",
    "transparentSpanID": "6ba80aaa3b2f43d8"
  }
}