ACacuvity
apex

POST /api/v1/police

Changed on

Processes the scan and police request.

Request

  • Base URL
    https://apex.acuvity.ai:443
  • URL
    https://apex.acuvity.ai:443/api/v1/police
  • Auth
    • HTTP bearer
    • or API key in cookie x-a3s-token

Request body

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.

encryptionEgressState'Unknown' | 'Unencrypted' | 'Encrypted'

Whether the connection from the app component to the origin server was encrypted. Unknown when it is not known. When left Unknown and encryptionEgress is set, it is considered Encrypted. It must not be Unencrypted when encryptionEgress is set.

encryptionIngressState'Unknown' | 'Unencrypted' | 'Encrypted'

Whether the connection from the client to the app component was encrypted. Unknown when it is not known. When left Unknown and encryptionIngress is set, it is considered Encrypted. It must not be Unencrypted when encryptionIngress is set.

messagesstring[]

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

modelstring

The model used by the request. When the request names neither a provider nor a destination app and component and the destination host resolves no provider either, the provider serving this model becomes the policy target.

providerstring

The name of the provider to use for policy resolutions. Must not be set when destination app and component are set. When neither this nor the destination app and component are set on an egress request, the provider is resolved from the destination host, and then from the model. On the police API an egress request must end up with a target. On the scan API it may end up with none to run a plain scan that targets nothing.

toolsobject

The various tools used by the request.

type'Input' | 'Output'

The type of text.

Example request

{
  "conversationID": "6f37d752-bce1-4973-88f6-28b6c100ceb8",
  "destination": {
    "app": "other-ai-app",
    "component": "backend",
    "host": "api.openai.com",
    "ip": "192.0.2.42",
    "port": 443
  },
  "encryptionEgress": {
    "ALPNNegotiatedProtocol": "h2",
    "TLSVersion": "TLS12",
    "cipherSuite": "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
    "implementation": "OpenSSL"
  },
  "encryptionEgressState": "Encrypted",
  "encryptionIngress": {
    "ALPNNegotiatedProtocol": "h2",
    "TLSVersion": "TLS12",
    "cipherSuite": "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
    "implementation": "OpenSSL"
  },
  "encryptionIngressState": "Encrypted",
  "extractions": [
    {
      "toolResults": [
        {
          "callID": "toolu_019X5QaEeVTDFrQPHqMMgd1n",
          "name": "fetch",
          "serverName": "my-mcp-server"
        }
      ],
      "toolUses": [
        {
          "callID": "toolu_019X5QaEeVTDFrQPHqMMgd1n",
          "name": "get_weather",
          "serverName": "deepwiki"
        }
      ]
    }
  ],
  "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-api",
  "source": {
    "ip": "192.0.2.42",
    "userClaims": [
      "name=John Doe",
      "email=john.doe@acme.com",
      "@validated=false"
    ],
    "username": "john.doe@acme.com"
  },
  "tools": {
    "tool1": {
      "description": "This is a tool.",
      "name": "tool1"
    }
  },
  "trace": {
    "parentSpanID": "00f067aa0ba902b7",
    "traceID": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Response

The request was processed and the response carries the enforcement decision. A platform failure inside the pipeline is also reported here rather than as an HTTP error: the response then carries the decision the application's failClose strategy dictates, Deny when failing closed and Allow when failing open, together with the structured error and the decision that was intended.

IDstring

ID is the identifier of the object.

annotationsobject

Annotations carried alongside the content, like the conversation ID. They are set during extraction, passed to the analysis and kept on what it produces.

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. This is driven by the policy that produced this decision, so it is reported here because the caller has no other way to know it happened.

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.

encryptionEgressState'Unknown' | 'Unencrypted' | 'Encrypted'

Whether the connection from the proxy to the origin server was encrypted. Unknown when it was not observed, which is the case for the scan and police APIs and for webhook integrations unless the caller provided it.

encryptionIngressState'Unknown' | 'Unencrypted' | 'Encrypted'

Whether the connection from the client to the proxy was encrypted. Unknown when it was not observed, which is the case for the scan and police APIs and for webhook integrations unless the caller provided it.

hashstring

The hash of the input.

modelstring

The model used by the request.

namespacestring

The namespace of the object.

offbandboolean

If true, this decision was made without waiting for the analyzers: the policy that produced it either asked for offband analysis, or pinned an empty inband analyzer set for this direction. The extractions in this response therefore carry no detections, and any redaction the analyzers would have found was not applied. The full analyzer set runs after this response is sent, so the stored roundtrip for this request can report a stricter outcome than the one reported here.

permissiveboolean

If true, the policy that produced this decision is configured in permissive mode, so the content decision reported here is what the policy would have enforced and is not meant to be enforced. A caller acting on this response must let the request through when the decision is Deny, Ask or Report. This covers the content decision only. A decision of ForbiddenUser comes from the access policy, which permissive does not affect, and must still be enforced.

pipelineNamestring

The name of the particular pipeline that extracted the text.

providerstring

The provider to use.

providerType'AIDomain' | 'LLM' | 'MCPServer' required

The type of the provider. AIDomain when no provider handled a request to a host targeted by an access policy.

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"
    ],
    "path": "/design",
    "workloadGroupHash": "wg-0ff92a76a3765740e26d84947d92e5fc",
    "workloadGroupLabel": "k8s:deployment=mcp-chatbot-agent,namespace=demo",
    "workloadGroupSetHash": "wgs-0ff92a76a3765740e26d84947d92e5fc",
    "workloadGroupSetLabel": "k8s:namespace=demo"
  },
  "encryptionEgress": {
    "ALPNNegotiatedProtocol": "h2",
    "TLSVersion": "TLS12",
    "cipherSuite": "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
    "implementation": "OpenSSL"
  },
  "encryptionEgressState": "Encrypted",
  "encryptionIngress": {
    "ALPNNegotiatedProtocol": "h2",
    "TLSVersion": "TLS12",
    "cipherSuite": "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
    "implementation": "OpenSSL"
  },
  "encryptionIngressState": "Encrypted",
  "extractions": [
    {
      "PIIs": {
        "ssn": 0.8
      },
      "categories": [
        {
          "group": "image",
          "type": "png"
        }
      ],
      "confidentiality": 0.9,
      "customDataTypes": {
        "my_cdt": 1
      },
      "dataSets": {
        "cds": {
          "ct1": 1,
          "ct2": 2
        }
      },
      "dlp": {
        "credit_card": 0.8
      },
      "exploits": {
        "prompt_injection": 0.8
      },
      "genericdetections": [
        {
          "category": "Personal Information"
        }
      ],
      "intent": {
        "write": 0.8
      },
      "keywords": {
        "my_keywork": 0.8
      },
      "languages": {
        "english": 0.8
      },
      "malcontents": {
        "toxic": 0.8
      },
      "metadata": {
        "sensitivity_label": [
          "Confidential"
        ]
      },
      "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",
  "policyRefs": [
    {
      "appPolicyID": "xxx-xxx-xxx-xxx",
      "appPolicyName": "email-agent",
      "appPolicyType": "ingress",
      "matchingTeams": [
        "team-a",
        "team-b"
      ],
      "policyID": "xxx-xxx-xxx-xxx",
      "policyIdentity": "default",
      "policyName": "frontend",
      "policyNamespace": "frontend"
    }
  ],
  "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-api",
  "providerType": "LLM",
  "tools": {
    "tool1": {
      "description": "This is a tool.",
      "name": "tool1"
    }
  },
  "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

  • 896f91b732fbRevision changes
    • warning

      added the new AIDomain enum value to the response property for the response status

    • info

      added the optional property / to the response with the status

  • 2a4a7adaa29eRevision changes
    • info

      added the optional property // to the response with the status