Everything you need to build with VERA.

Getting access

The Partner API is in early access. Every partner goes through a security review and signs the VERA Partner Agreement before receiving keys. Keys are delivered through a secure channel, never by plain email or chat, and only a hash of each key is stored on our side. If a key is lost, we revoke it and issue a new one.

You can build against the specification today: download the OpenAPI 3.1 file and generate a client in any language with your usual OpenAPI tooling.

Base URL and versioning

The version you are talking to is returned in VERA-Version on every response. New fields, endpoints and webhook events can be added, so ignore fields you don't recognise. You may send your own X-Request-Id (8 to 64 letters, digits,_ or -) to trace a request end to end; otherwise we create one.

Authentication and scopes

Send your key as a bearer token on every request under /v1:

Authorization: Bearer vera_sk_...

Keep keys on your server. Never ship one in a browser, a mobile app or a public repository. Revocation takes effect on the very next request. Keys are scoped to least privilege:

Quickstart

Four calls cover the full loop: start, talk, approve, report.

# 1. Start a conversation for one person on your platform
curl -X POST https://api.veraneural.com/v1/conversations \
  -H "Authorization: Bearer $VERA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: conv-user_8f3a21-001" \
  -d '{"end_user_id":"user_8f3a21","locale":"en-US","country":"US"}'

# 2. Send what the person says
curl -X POST https://api.veraneural.com/v1/conversations/conv_8xZr0aQ1/messages \
  -H "Authorization: Bearer $VERA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: msg-user_8f3a21-001" \
  -d '{"content":"Big week. I am stretched thin.","context":"Today: 3 site visits, 1 client call at 15:00"}'

# 3. The person approved a proposed action in your interface
curl -X POST https://api.veraneural.com/v1/actions/act_3kP0b2Lm/approve \
  -H "Authorization: Bearer $VERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"end_user_id":"user_8f3a21"}'

# 4. Your platform carried it out. Tell VERA what happened
curl -X POST https://api.veraneural.com/v1/actions/act_3kP0b2Lm/result \
  -H "Authorization: Bearer $VERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"completed","message":"Booked for 3pm Thursday."}'

The same loop in Node.js

// Node.js 20+ (built-in fetch). Keep VERA_KEY on your server.
const BASE = "https://api.veraneural.com/v1";
const headers = {
  Authorization: `Bearer ${process.env.VERA_KEY}`,
  "Content-Type": "application/json",
};

async function vera(path, body, idempotencyKey) {
  const res = await fetch(BASE + path, {
    method: "POST",
    headers: idempotencyKey ? { ...headers, "Idempotency-Key": idempotencyKey } : headers,
    body: JSON.stringify(body),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(`${data.error.type}: ${data.error.message} (${data.error.request_id})`);
  return data;
}

const conv = await vera("/conversations", { end_user_id: "user_8f3a21", country: "US" }, "conv-user_8f3a21-001");
const reply = await vera(`/conversations/${conv.id}/messages`, { content: "Big week. I am stretched thin." }, "msg-user_8f3a21-001");

if (reply.safety.display_required) showResourcesProminently(reply.safety.resources); // never hide or delay
console.log(reply.message.content);
for (const action of reply.proposed_actions) askThePerson(action.summary, action.id);   // approve only after a clear yes

The same loop in Python

# Python 3.9+ with requests. Keep VERA_KEY on your server.
import os, requests

BASE = "https://api.veraneural.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['VERA_KEY']}"}

def vera(path, body, idempotency_key=None):
    h = dict(HEADERS, **({"Idempotency-Key": idempotency_key} if idempotency_key else {}))
    r = requests.post(BASE + path, json=body, headers=h, timeout=30)
    data = r.json()
    if not r.ok:
        e = data["error"]
        raise RuntimeError(f"{e['type']}: {e['message']} ({e['request_id']})")
    return data

conv = vera("/conversations", {"end_user_id": "user_8f3a21", "country": "US"}, "conv-user_8f3a21-001")
reply = vera(f"/conversations/{conv['id']}/messages", {"content": "Big week. I am stretched thin."}, "msg-user_8f3a21-001")

if reply["safety"]["display_required"]:
    show_resources_prominently(reply["safety"]["resources"])  # never hide or delay
print(reply["message"]["content"])
for action in reply["proposed_actions"]:
    ask_the_person(action["summary"], action["id"])  # approve only after a clear yes

Prefer clicking to typing? Import the Postman collection, set the VERA_KEY variable, and every endpoint is ready to send.

Conversations

A conversation is between VERA and one person on your platform. end_user_id must be an opaque ID from your system (letters, digits and . _ : @ -, up to 128 characters), never a name, email address or phone number. Set country (ISO 3166 alpha-2, for example US, DE, CH) so VERA gives the right crisis numbers. metadata holds up to 20 string values of 500 characters each.

{
  "id": "conv_8xZr0aQ1",
  "object": "conversation",
  "end_user_id": "user_8f3a21",
  "locale": "en-US",
  "country": "US",
  "metadata": { "workspace": "site-north" },
  "safety_hold": false,
  "created_at": "2026-10-23T14:02:11Z"
}

Messages

POST /v1/conversations/{id}/messages sends what the person says (content, 1 to 8,000 characters) and returns VERA's reply. The optional context field (up to 4,000 characters) carries reference information from your platform, such as today's schedule or an open job. It is always treated as data, never as instructions, so it cannot change who VERA is or what she is allowed to do.

{
  "object": "vera.reply",
  "conversation_id": "conv_8xZr0aQ1",
  "message": {
    "id": "msg_2Lq9",
    "role": "assistant",
    "content": "That's a lot for one week. One slow breath first...",
    "created_at": "2026-10-23T14:02:14Z"
  },
  "safety": {
    "level": "none",
    "protocol": null,
    "display_required": false,
    "resources": []
  },
  "proposed_actions": [
    {
      "id": "act_3kP0b2Lm",
      "object": "action",
      "tool": "schedule_meeting",
      "arguments": { "title": "Client update", "start": "2026-10-24T15:00:00Z", "minutes": 20 },
      "summary": "Book a 20-minute client update tomorrow at 3pm.",
      "status": "pending_approval",
      "expires_at": "2026-10-24T14:02:14Z"
    }
  ]
}

GET /v1/conversations/{id}/messages?limit=50 lists messages oldest first (limit 1 to 200). Each message carries its own safety_level.

Safety levels

Every reply carries a safety object. Always check it before you render the reply.

"safety": {
  "level": "crisis",
  "protocol": "crisis_v1",
  "display_required": true,
  "resources": [
    {
      "name": "988 Suicide & Crisis Lifeline",
      "contact": "Call or text 988",
      "description": "Free, confidential support, 24/7."
    }
  ]
}

After a crisis signal, the conversation enters a safety hold for the next 10 replies: safety_hold is true on the conversation, replies are at least elevated, and no actions are proposed. The crisis protocol can't be switched off, edited or bypassed by any partner. If you have a human support or safeguarding process, route safety.crisis_detected to it.

Actions and approval

VERA never executes anything. She can only propose an action from the tools you registered. Each proposal has a plain-language summary that you show the person before they decide. Your platform carries out the action only after they approve.

end_user_id on approve and reject must match the conversation's person, otherwise you get 403. Deciding twice, or after expiry, returns 409. Results you report are shown to VERA on her next turn, so she never claims something happened that didn't.

Tools

Tools declare what VERA may propose on your platform, such as schedule_meeting or create_invoice_draft. Names match ^[a-z][a-z0-9_]{1,47}$. Arguments VERA proposes are validated against your input_schema; anything invalid or unknown is discarded and recorded in your audit trail.

curl -X PUT https://api.veraneural.com/v1/tools/schedule_meeting \
  -H "Authorization: Bearer $VERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Schedule a meeting on the person'\''s calendar.",
    "input_schema": {
      "type": "object",
      "properties": {
        "title":   { "type": "string" },
        "start":   { "type": "string", "description": "ISO 8601 date-time" },
        "minutes": { "type": "integer" }
      },
      "required": ["title", "start"]
    }
  }'

Property types are string, number, integer and boolean, each with an optional description and enum. GET /v1/tools lists your tools; DELETE /v1/tools/{name} removes one.

Webhooks

curl -X POST https://api.veraneural.com/v1/webhooks \
  -H "Authorization: Bearer $VERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/vera","events":["action.approved","safety.crisis_detected"]}'

# 201 Created: the secret is shown once. Store it now.
{ "id": "wh_...", "object": "webhook_endpoint", "url": "https://hooks.example.com/vera",
  "events": ["action.approved", "safety.crisis_detected"], "secret": "whsec_..." }

POST https://hooks.example.com/vera
Content-Type: application/json
VERA-Event: action.approved
VERA-Event-Id: evt_9Xf2
VERA-Signature: t=1761228134,v1=5f1c...e9

{
  "id": "evt_9Xf2",
  "type": "action.approved",
  "created_at": "2026-10-23T14:02:14Z",
  "data": { "action": { "id": "act_3kP0b2Lm", "tool": "schedule_meeting", "status": "approved", ... } }
}

Each delivery is signed: VERA-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of <t>.<raw body> with your endpoint secret. Verify it against the raw body, and reject timestamps older than 5 minutes.

import crypto from "node:crypto";

// rawBody: the exact bytes you received, before JSON parsing
export function verifyVera(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // older than 5 minutes
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const given = String(parts.v1 ?? "");
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(given));
}

import hashlib, hmac, time

def verify_vera(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", "0"))
    if not t or abs(time.time() - t) > 300:  # older than 5 minutes
        return False
    signed = f"{t}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Answer with any 2xx quickly and do the work afterwards. Failed deliveries are retried after 1 s, 10 s and 60 s, so use VERA-Event-Id to ignore duplicates. Webhook URLs must be public HTTPS addresses; private and internal addresses are refused. Up to 5 endpoints per partner. Webhooks never contain message content.

Idempotency and retries

Send an Idempotency-Key header (8 to 128 characters) on every write. Repeating the same key within 24 hours returns the original response instead of doing the work twice, so you can retry timeouts and 5xx errors safely. Use one key per logical operation, for example per message the person sends.

Retry 429 after the Retry-After seconds, and 502 engine_unavailable with exponential backoff and the same key. Don't retry other 4xx errors without changing the request.

Errors

Every error has the same shape. Quote request_id when you contact us.

{
  "error": {
    "type": "permission_error",
    "message": "Only the person in this conversation can approve this action.",
    "request_id": "req_7d2K..."
  }
}

Limits and rate limits

Every authenticated response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds).

Data, privacy and deletion

• Each partner's data is fully isolated. Another partner's IDs return 404, never their data
• People are opaque IDs. Names, emails and phone numbers are rejected as end_user_id
• Conversations are never used to train models
• Audit events and webhooks never contain message content
• DELETE /v1/conversations/{id} deletes a conversation, its messages and its actions permanently
• Conversations are deleted automatically after the retention period, 365 days unless agreed otherwise
• GET /v1/audit-events lists requests, approvals, safety events and webhook failures for your account, newest first

Security

• HTTPS only. Every request and webhook travels over TLS
• API keys are shown once. Only a SHA-256 hash is stored, and revocation applies on the very next request
• Hosted on Microsoft Azure in the United States, with data encrypted at rest and secrets kept in a managed key vault
• Every partner's data is isolated. A request can only ever see its own partner's conversations, actions and audit events
• Webhooks are signed with HMAC-SHA256 and a timestamp, and only sent to HTTPS addresses
• Every request, approval, safety event and webhook failure is written to your audit trail
• Every partner is security-reviewed before receiving keys, and we review our own service the same way before each new partner goes live

Found a vulnerability? Please tell us privately through our contact form with the topic “Security”, and don't test against other partners' data. We reply to every report.

Partner obligations

These are part of the VERA Partner Agreement and are checked in the security review.

1. Keep API keys on your server.
2. Whenever safety.display_required is true, show the reply and every resource prominently. Never hide, shorten or delay them.
3. Show each action's summary to the person, and call /approve only after they explicitly agree.
4. Report the outcome of every approved action with /result.
5. Use opaque user IDs only.
6. Tell people they are talking with VERA, not a person, and link the VERANeural privacy notice.
7. When someone asks for their data to be deleted, call DELETE /v1/conversations/{id}.

Endpoint reference

Full request and response schemas are in the OpenAPI 3.1 specification.

Changelog and versioning policy

How versions work

• Adding fields, endpoints, webhook events or error details is not a breaking change, and can happen in any version. Ignore what you don't recognise
• Removing or renaming anything, or changing what a field means, only happens in a new dated version
• We announce a new version to every partner at least 90 days before the previous one changes, and keep the previous version running for at least 12 months
• Safety fixes are the exception: if a change is needed to keep people safe, it ships right away, and we tell you the same day

Not yet available

So you can plan honestly, these are not in the current version:

• Streaming replies (server-sent events) and real-time voice through the API
• A self-service partner dashboard for keys, webhooks and usage
• Usage metering and billing through the API
• Official SDKs. Generate a client from the OpenAPI file in the meantime
• A sandbox with test keys and test data. Until then, early-access partners start on a key with a low rate limit
• A public status page. Early-access partners are told directly about any incident

Pricing for the Partner API is agreed with each partner during onboarding.

VERA CLI

VERA in your terminal: PowerShell, Windows Terminal, bash, zsh and macOS Terminal. Node.js 20 or newer. VERA reads your repository, plans the change, shows the exact diff and waits for Apply, Revise or Reject. VERA CLI is in early access for the teams we work with.

VERA doesn't just vibe-code your app, she vibe-codes your model. Describe the fine-tune, and VERA writes the data preparation, training and evaluation pipeline, then runs it on your own cloud, on your own data, with every command shown and approved first.

Install

# Early-access teams receive package access first. Then, once per computer:
npm install -g @veraneural/vera-cli

# Update
npm install -g @veraneural/vera-cli@latest

Choose your model

Bring your own model: VERA CLI works with the major frontier model providers and any OpenAI-compatible endpoint, including models you run yourself. Keys live in your computer's secure store or the provider's usual environment variable, never in a config file. If a model is busy, VERA retries, then moves to your next model and tells you.

vera login <provider>        # key saved in your computer's secure store
vera models                  # which models have a key
vera models --test           # send each a tiny request

# ~/.vera/config.toml  (never put keys in it; VERA refuses a config file that contains one)
default_model = "main"

[models.main]
provider = "openai-compatible"
base_url = "https://your-endpoint.example.com/v1"
model = "your-model"
api_key_env = "MY_MODEL_KEY"

Use it

vera init                        # creates .vera/config.toml (commit it, never put keys in it)
vera "fix the spacing on the login screen"
vera                             # talk with VERA in this repository
vera --continue                  # pick up your last conversation here
vera --dry-run "…"               # plan and diff only, nothing changes
vera --no-pr "…"                 # commit on a new branch, no push or pull request
vera --check "…"                 # run the tests before committing without asking
vera -m <model> "…"              # pick a model for one request
vera merge 5                     # merge PR #5 after showing every check and asking you

vera connectors                  # every app VERA can connect to, and which are on
vera connect github              # through your own gh login
vera disconnect notion

What VERA CLI will and won't do

• Nothing is written until you choose Apply. Every change is shown as a diff first
• A strict review pass checks each change for real defects before you see it
• Runs your tests after Apply (npm, pnpm, yarn, bun, pytest, cargo, go, dotnet, or your own check command). If they fail, your files go back and VERA corrects her change, up to 3 attempts
• Works on a new vera/… branch. Never commits to your base branch, never force-pushes, never rebases
• Commits only the files she changed, and won't start on uncommitted tracked changes unless you pass --allow-dirty
• Never reads secrets (.env, keys, credentials), binaries, generated folders or lockfiles, and lists every file she sends to the model
• Edits are exact search-and-replace. An edit that doesn't match is refused, never guessed
• Opens pull requests as drafts. Never deploys
• Merges only when you say yes, after showing every passing, failing and running check. Never bypasses branch protection
• Shows each terminal command and why before it runs: yes, no, or always for that exact command in this conversation
• Anything that can delete asks twice, every time. Anything unclear counts as a change
• Memory per repository lives on your computer in ~/.vera/projects/ and is never committed

Connectors

VERA CLI reaches your apps through the Model Context Protocol (MCP), with your own account: your cloud, GitHub, Vercel, Supabase, Expo and EAS, Sentry, Linear, Jira and Confluence, Microsoft 365, Slack, Notion, Asana, monday.com, Figma, Canva, Gamma, Stripe, HubSpot, Mixpanel, web search, a real browser, and Zapier for apps without a connector of their own. App Store Connect and Google Play connect through their official APIs and are read-only, except replying to a review, which asks you first. Looking runs freely and is shown; every change is shown in full and needs your yes.

VERA Vibe Coding

VERA Vibe Coding is the same VERA as VERA CLI, working in your editor. Open VS Code or Cursor on your repository, click the VERA icon in the Activity Bar to open her panel in the side bar, and ask in plain words. She reads your code, plans the change and shows the exact diff before anything is written. Prefer the terminal? Run vera in the editor's built-in terminal instead.

1. Describe it. “Add a booking page for the clinic, with the same header as the rest of the site.”
2. VERA plans it. She lists the files she read, the plan, and every change as a diff.
3. A review pass checks it for real defects before you see it, and VERA fixes those first.
4. You choose: Apply, Revise or Reject. Nothing is written before Apply.
5. Tests run. If they fail, your files go back and VERA corrects her change.
6. It lands as a draft pull request on its own vera/… branch. VERA never deploys. You merge when you're ready.

Vibe-code your model

Describe the fine-tune in plain words. VERA writes the data preparation, training and evaluation pipeline in your repository, shows every file, and shows each command with its reason before it runs on your own cloud. The pipeline lands as a pull request you review, so you can run it again whenever your data changes.

Connections

Connections let VERA work with the tools your team already uses, with your own account and your own permissions. There are two ways to connect.

You connect, from VERA CLI

Run vera connectors to see every app VERA can reach and which are on, then vera connect <app>. Sign-in apps open your browser once. Keys go to your computer's secure store, never to a file in your repository.

vera connectors             # every app VERA can connect to, and which are on
vera connect azure          # as you, through az login
vera connect github         # repositories, issues, pull requests and Actions logs, through gh auth login
vera connect vercel         # sign-in apps open the browser once
vera disconnect notion

We connect, for your organisation

For VERA for Business and the VERA platforms, we connect company systems for you: Microsoft 365 and Google, construction platforms such as Procore and Autodesk Construction Cloud, sales and finance tools such as HubSpot, Salesforce, Stripe and QuickBooks, and more. See the full list.

The same rules for every connection

• Looking runs freely, and every look is shown
• A change is shown in full (the app, the action and the details) and needs your yes
• Anything that can delete asks twice, every time
• Anything unclear counts as a change

Docs for coding assistants

Building with Cursor, Claude, Copilot or another coding assistant? Point it at veraneural.com/llms.txt, a plain-text summary of these docs written for assistants, and give it the OpenAPI file for the exact request and response shapes.

Support

Questions, a larger rate limit, or a security questionnaire: contact us and include the request_id of any request you're asking about. To start the security review, request API access.

App and product names are trademarks of their owners and are used only to say which tools VERA connects to.