# Try it

This page is for an agent proving to a person that Zaun works on their own key before any
agent traffic is configured. It gives the published test string, a curl that runs it, the
detection samples, and the result to show the person. If you are the person, this is the
first thing to run after you create a key.

## The test string

`ZAUN-TEST-VIOLATION-7f3a9c` is a harmless string that Zaun always reports as a blocked
input check named `zaun_test`. It matches the exact string, case-sensitively, in prompts and
inside tool-call arguments. No project control can lower it. Use it to prove a key, a hook, a
gateway or an alert without sending a real attack. It is billed like any scan.

Run it with the scan key in `$ZAUN_API_KEY` (see [set up with your agent](agent-setup.md)
for how the person stores `<SCAN_KEY>` without pasting it into the conversation) and the API
base URL in `$ZAUN_BASE_URL`:

```sh
export ZAUN_BASE_URL='https://api.zaun.ai'
```


```sh
curl --silent --show-error --fail-with-body --max-time 50 \
  "$ZAUN_BASE_URL/v1/scan/prompt" \
  -H "Authorization: Bearer $ZAUN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{"messages":[{"role":"user","content":"ZAUN-TEST-VIOLATION-7f3a9c"}]}'
```

The response is the compact scan result from the [quickstart](quickstart.md), with the
input check named:

```json
{
  "scan_uuid": "3a723044-ed79-43c9-aa03-d74603503a49",
  "completed_at": "2026-10-13T18:02:11.204511Z",
  "violation": true,
  "action": "block",
  "session_uuid": null,
  "taxonomy": "mitre_atlas_tactic",
  "technique": [],
  "usage": {"input_tokens": 12, "cached_input_tokens": 0, "output_tokens": 0},
  "input_checks": {"controls": ["zaun_test"], "action": "block"}
}
```

The scan reports the action; your application or hook enforces it. `technique` stays empty
because the string is an input check, not a detected attack. `usage.input_tokens` is the new
tokens billed at the scan rate; `usage.cached_input_tokens` is a session's earlier tokens,
billed at a tenth of it, and is zero without a `session_uuid`. The exact counts depend on the
request.

The string also works inside a tool call, which is how hooks and gateways are proven:

```sh
curl --silent --show-error --fail-with-body --max-time 50 \
  "$ZAUN_BASE_URL/v1/scan/prompt" \
  -H "Authorization: Bearer $ZAUN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{"messages":[{"role":"assistant","content":null,"tool_calls":[{"id":"call_1","type":"function","function":{"name":"run_shell","arguments":"{\"command\":\"echo ZAUN-TEST-VIOLATION-7f3a9c\"}"}}]}]}'
```

## The detection samples

`GET /v1/detection-samples` returns Zaun-written sample requests and needs no key. Each
sample has an `id`, a `group`, a `title`, one sentence on why it matters (`explains`), the
exact `messages` to send, and the outcome `expected` under the default controls of a new
self-serve project.

```sh
curl --silent --show-error --fail-with-body "$ZAUN_BASE_URL/v1/detection-samples"
```

The groups are prompt attacks and jailbreaks, agent and tool security, sensitive data leaks,
harmful content, fraud and illegal activity, unreliable or unsafe advice, benign requests,
and the test string. `benign_coding` should come back with no violation. `benign_support`, an
ordinary refund exchange, can come back as an alert under the default controls; report it if
it does.

To run a sample on your own key, send its `messages` unchanged as the body of
`POST /v1/scan/prompt`. The result follows your project's controls, so it can differ from
`expected` when your controls differ from the defaults. An action at least as strong as the
expected one counts as a match. In the console, the **Playground** offers the same samples as
one-click runs.

## Read the stored result

Every scan is stored under its `scan_uuid`. A key with `result:read` in the same project
reads the full result, including the findings Hex v1.3 reported:

```sh
curl --silent --show-error --fail-with-body \
  -H "Authorization: Bearer $ZAUN_API_KEY" \
  "$ZAUN_BASE_URL/v1/result/REPLACE_WITH_SCAN_UUID"
```

## The proof to show

Show the person the test string response: its `scan_uuid`, `"action": "block"` and
`input_checks.controls` containing `zaun_test`. Then run the `benign_coding` sample and show
that it has no violation. Together they prove that the key, the project and its controls work.
Next, [choose a capture path](capture-paths.md).