# VEYZL developer portal

Connect VEYZL to your code: the GitHub merge check, project API keys, agent testing, and the REST API at `https://api.veyzl.ai`.

## Quickstart

1. [Create a free account](https://veyzl.ai/signup) and create a project for the repository that contains your AI system.
2. Install the VEYZL GitHub App on that repository when the dashboard prompts you.
3. Review the detected system profile: the AI surfaces VEYZL found and the controls they trigger.
4. Open a pull request. VEYZL runs the audit and posts a `VEYZL Audit` status check with the result and fix guidance.
5. On the Startup plan, mark `VEYZL Audit` as a required check in branch protection so a failing audit blocks the merge.

The [How it works](https://veyzl.ai/how-it-works) paper covers model configuration, gating, and reading reports in depth.

## CLI

The `veyzl` command-line client starts hosted audits and gates on their result, from your terminal, CI, or an AI coding agent. It needs Python 3.9 or later.

```bash
pipx install veyzl-cli        # or: pip install veyzl-cli
veyzl login                    # approve in the browser; any sign-in method works
veyzl projects                 # find the project ID
veyzl audit <project-id> --wait
git push && veyzl watch <project-id>   # follow the audit the push started
```

- `veyzl login` opens `https://veyzl.ai/cli-login` and stores the session in `~/.config/veyzl/credentials.json`. It needs a browser on the same machine, so it does not work over plain SSH. `veyzl logout` deletes the file.
- In CI and cloud coding agents, set `VEYZL_TOKEN` to a project CI token instead. Anyone on the project creates one in the project's Settings, under CI tokens (Startup plan). It is shown once, works only on that project, and expires after 90 days. Example: `VEYZL_TOKEN=${{ secrets.VEYZL_TOKEN }} veyzl watch <project-id> --commit $GITHUB_SHA`. With a CI token, `veyzl projects` is unavailable; every other command takes the project ID.
- `veyzl audit <project-id> --wait` starts a hosted audit, waits for it, and exits `0` only if the audit passes, `1` otherwise. Without `--wait` it queues the run and returns.
- `veyzl watch <project-id>` follows the audit GitHub started for a push or pull request and exits like `audit --wait`. Pick the run with `--commit SHA`, `--pr N` or `--branch B`; with none of them inside a git repo it follows `HEAD`.
- `veyzl runs <project-id>` lists hosted runs, newest first. `veyzl export <project-id>` writes the signed evidence pack (Startup plan).
- `whoami`, `projects`, `runs`, `audit` and `watch` take `--json` for the raw API response. A failed run includes `failure_reason` and `summary_metrics`.

In a terminal, `audit --wait` and `watch` draw a live progress bar. When output is not a terminal (CI logs, pipes, AI coding agents) they print one plain line per stage instead.

## API keys

The `/v1` REST endpoints, including agent trace reporting, authenticate with a **project upload token** sent as a bearer token. Each token is scoped to one project.

1. Open the project in the [VEYZL dashboard](https://veyzl.ai/dashboard).
2. Go to **Settings > Upload token** and choose **Show token**.
3. Store the token as `VEYZL_API_KEY` in your secret manager or CI secrets.

Treat the token like a password and never commit it. Requests with a missing or invalid token get `401 Unauthorized`.

## Agent testing

With agent testing on (project settings, Connection & stats), audits check what your agent does with its tools: VEYZL asks it to delete data, move money, change access and send data out, then grades the tool calls by fixed rules. If your endpoint returns its tool calls (OpenAI or Anthropic format, or a `tool_calls` list), nothing else is needed.

If your agent runs its tools on the server and replies only with text, report the calls. Every audit request carries `X-Veyzl-Audit-Request` (an id for that request) and `X-Veyzl-Audit: test`. When a request has these headers, skip side effects, note each tool call your agent makes, and before you reply send them to `POST /v1/agent-traces` with the project upload token, also when no tool ran (`"tool_calls": []`). Set `dry_run` to `true` when the tools did not run for real. Posting again for the same `request_id` adds calls.

```bash
curl -X POST https://api.veyzl.ai/v1/agent-traces \
  -H "Authorization: Bearer $VEYZL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "<X-Veyzl-Audit-Request header value>",
    "tool_calls": [{"name": "send_email", "arguments": {"to": "ops@example.com", "subject": "Export"}}],
    "dry_run": true
  }'
```

## Business rules

On the Startup plan, a project can add its own rules for its AI in project Settings, under Business rules: words or patterns it must never say (such as a percentage or an amount of money), a line it must always include, a topic it must decline, the right answer to a question, or a value it must keep secret. A rule no fixed check fits, such as not giving personal financial advice, can be added as a reviewed rule: two language models read each reply against it, the report marks it, and it is the only kind of test they decide.

Each rule needs the questions that test it: write them, or draft some and keep the ones you want. Every approved question runs on every audit, alongside the built-in tests, and is attacked the same way; a broken rule fails the audit and the `VEYZL Audit` check like any other test, and the report names the rule. A secret value never appears in a stored result.

## REST API

Base URL: `https://api.veyzl.ai`. Requests and responses are JSON. Every `/v1` endpoint requires `Authorization: Bearer <project upload token>`.

- `POST /v1/agent-traces`: report the tool calls your agent ran for one audit request (see Agent testing). Required: `request_id` (the `X-Veyzl-Audit-Request` header value) and `tool_calls` (a list of `{name, arguments}`, empty when no tool ran). Optional: `dry_run`. Traces expire after a day.
- `POST /v1/audits`: store an audit report as append-only evidence. The body must include a unique `audit_id`; raw dataset rows are rejected.
- `GET /v1/audits/{audit_id}`: fetch a stored audit report that belongs to your project.
- `GET /health`: service health check. No authentication.

```bash
curl https://api.veyzl.ai/v1/audits/$AUDIT_ID \
  -H "Authorization: Bearer $VEYZL_API_KEY"
```

### Errors

- `400 Bad Request`: an audit report has no `audit_id`, or contains raw dataset rows; or an agent trace has a `request_id` VEYZL didn't send, a tool call without a name, or more than 50 calls.
- `401 Unauthorized`: the bearer token is missing or invalid.
- `403 Forbidden`: the resource belongs to another project.
- `404 Not Found`: no audit exists with that `audit_id`.
- `409 Conflict`: an audit with that `audit_id` is already stored. Evidence is never overwritten.
- `422 Unprocessable Entity`: the JSON body is missing a required field or has the wrong type.

## Testing and sandbox

There is no separate sandbox environment. The Free plan is the safe place to try VEYZL: audits run on every push and pull request, findings are posted to the pull request, and merges are never blocked. When the results look right, upgrade to Startup and make the check required.

To re-run an audit without pushing a commit, use **Run audit** at the top of the project page.

## Machine-readable resources

- [llms.txt](https://veyzl.ai/llms.txt): a map of this site for language models
- [sitemap.xml](https://veyzl.ai/sitemap.xml): every public page
- [developers.md](https://veyzl.ai/developers.md): this page as Markdown. Requesting `/developers` with `Accept: text/markdown` returns the same document.
- [index.md](https://veyzl.ai/index.md): the homepage as Markdown

## Support

Questions about the API or CLI go through [Support](https://veyzl.ai/support). For security disclosures, see [Security](https://veyzl.ai/security) or [Contact](https://veyzl.ai/contact).
