Sign in
apex

Processes the scan request.

post/api/v1/scan

Request body

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.

anonymization'FixedSize' | 'VariableSize'

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

conversationIDstring

Identifies the conversation this request belongs to. Apex records it on the resulting log, which is what groups the successive requests of one conversation together in the logs and in the conversation view, and it is also made available to the analyzers and to policies. Send the same value on every request of the same conversation.

direction'Egress' | 'Ingress'

The direction of the traffic for this request, relative to the app component the caller's token identifies. Determines whether the ingress or the egress policies of that app component are evaluated.

keywordsstring[]

The keywords found during classification.

messagesstring[]

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

providerstring

The name of the provider to use for policy resolutions. Must not be set when destination app and component are set. On the police API an egress request must set either this or the destination app and component. On the scan API both may be omitted to run a plain scan that targets nothing.

redactContentboolean

If true, the user data is removed from the logged roundtrip, while the analysis and all other metadata are kept. This only affects what is logged: the response of this call always carries the full content.

redactContentBypassboolean

If true, and redactContent is also true, the user data is kept in the logged roundtrip whenever the decision reports a violation, so that the content behind a denial stays available for review. It has no effect on its own.

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"
  ],
  "conversationID": "6f37d752-bce1-4973-88f6-28b6c100ceb8",
  "destination": {
    "app": "other-ai-app",
    "component": "backend",
    "host": "api.openai.com",
    "ip": "192.0.2.42",
    "port": 443
  },
  "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."
  ],
  "provider": "openai",
  "redactions": [
    "person",
    "ssn",
    "location"
  ],
  "source": {
    "ip": "192.0.2.42",
    "userClaims": [
      "name=John Doe",
      "email=john.doe@acme.com",
      "@validated=false"
    ],
    "username": "john.doe@acme.com"
  },
  "trace": {
    "parentSpanID": "00f067aa0ba902b7",
    "traceID": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Response

The request was processed. Scan renders no verdict of its own, so the response carries the analysis with a decision of NotApplicable.

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.

contentRedactedboolean

If true, the content of the extractions was stripped from the audit entry for this request, and only the analysis and other metadata were kept. It reports what actually happened, which is not the same as what was requested: redactContentBypass can leave the content in place.

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",
  "destination": {
    "app": "MyApp",
    "component": "frontend",
    "host": "api.openai.com",
    "ip": "192.0.2.42",
    "labels": [
      "country=us",
      "another-label"
    ],
    "workloadGroupHash": "wg-0ff92a76a3765740e26d84947d92e5fc",
    "workloadGroupLabel": "k8s:deployment=mcp-chatbot-agent,namespace=demo",
    "workloadGroupSetHash": "wgs-0ff92a76a3765740e26d84947d92e5fc",
    "workloadGroupSetLabel": "k8s:namespace=demo"
  },
  "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"
  }
}

Changes

Changed in 4 of the 6 revisions of this API.25

  • 0f21cd12148e13See the full diff
    • ●

      added the new None enum value to the tools/additionalProperties/category response property for the response status 200

      response-property-enum-value-added

    • ○

      the category request property default value None was added

      request-property-default-value-added

    • ○

      added the new None enum value to the request property tools/additionalProperties/category

      request-property-enum-value-added

    • ○

      the category response's property default value None was added for the status 200

      response-property-default-value-added

  • e850756435a61See the full diff
    • ●

      added the new Redaction enum value to the error/stage response property for the response status 200

      response-property-enum-value-added

  • 58d2295ee11e1See the full diff
    • ○

      added the optional property latency/contentAttribution to the response with the 200 status

      response-optional-property-added

  • 010e99908a0e1See the full diff
    • ○

      endpoint added

      endpoint-added