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
- Create a free account and create a project for the repository that contains your AI system.
- Install the VEYZL GitHub App on that repository when the dashboard prompts you.
- Review the detected system profile: the AI surfaces VEYZL found and the controls they trigger.
- Open a pull request. VEYZL runs the audit and posts a
VEYZL Auditstatus check with the result and fix guidance. - On the Startup plan, mark
VEYZL Auditas a required check in branch protection so a failing audit blocks the merge.
The 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.
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 startedveyzl loginopenshttps://veyzl.ai/cli-loginand 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 logoutdeletes the file.- In CI and cloud coding agents, set
VEYZL_TOKENto 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 projectsis unavailable; every other command takes the project ID. veyzl audit <project-id> --waitstarts a hosted audit, waits for it, and exits0only if the audit passes,1otherwise. Without--waitit queues the run and returns.veyzl watch <project-id>follows the audit GitHub started for a push or pull request and exits likeaudit --wait. Pick the run with--commit SHA,--pr Nor--branch B; with none of them inside a git repo it followsHEAD.veyzl runs <project-id>lists hosted runs, newest first.veyzl export <project-id>writes the signed evidence pack (Startup plan).whoami,projects,runs,auditandwatchtake--jsonfor the raw API response. A failed run includesfailure_reasonandsummary_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.
- Open the project in the VEYZL dashboard.
- Go to Settings > Upload token and choose Show token.
- Store the token as
VEYZL_API_KEYin 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.
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
}'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(theX-Veyzl-Audit-Requestheader value) andtool_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 uniqueaudit_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.
curl https://api.veyzl.ai/v1/audits/$AUDIT_ID \
-H "Authorization: Bearer $VEYZL_API_KEY"Errors
400 Bad Request: an audit report has noaudit_id, or contains raw dataset rows; or an agent trace has arequest_idVEYZL 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 thataudit_id.409 Conflict: an audit with thataudit_idis 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: a map of this site for language models
- sitemap.xml: every public page
- developers.md: this page as Markdown. Requesting
/developerswithAccept: text/markdownreturns the same document. - index.md: the homepage as Markdown
Support
Questions about the API or CLI go through Support. For security disclosures, see Security or Contact.