Skip to main content

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 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 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 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.
  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.

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 (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.
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: a map of this site for language models
  • sitemap.xml: every public page
  • developers.md: this page as Markdown. Requesting /developers with Accept: text/markdown returns 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.