# Veyra — Complete Reference for AI Agents

> Veyra is commit mode for production AI agent actions.

## Core Concept

AI agents operate in two modes:
- **Explore Mode**: Read, search, simulate, draft — no restrictions
- **Commit Mode**: Write, send, deploy, delete — requires Veyra

Veyra provides the protocol for transitioning from Explore to Commit.

---

## Quickstart: Hosted MCP Pack

Connect to all 48 Veyra tools with one URL. No SDK install required.

### Claude Desktop
```json
{
  "mcpServers": {
    "veyra": {
      "url": "https://mcp.veyra.to/sse"
    }
  }
}
```

### OpenAI / Codex
```
MCP Server URL: https://mcp.veyra.to/sse
```

### Cursor
```
Settings → MCP → Add Server → https://mcp.veyra.to/sse
```

### Windsurf
```
Settings → MCP → Add Server → https://mcp.veyra.to/sse
```

### Cline
```
MCP Settings → Add → https://mcp.veyra.to/sse
```

### Any MCP Client
```
SSE endpoint: https://mcp.veyra.to/sse
```

**What you get:**
- 48 tools total: 24 free reads, 24 protected writes
- 8 tool domains: memory, notes, tasks, snippets, bookmarks, contacts, forms, webhooks
- Each domain: 3 free read tools + 3 protected write tools

**Pack endpoints:**
- SSE: https://mcp.veyra.to/sse
- Manifest: https://mcp.veyra.to/.well-known/veyra-pack.json
- Health: https://mcp.veyra.to/health
- Tools list: https://mcp.veyra.to/tools

---

## Protocol Flow

### Step 1: Trust Discovery (FREE)

```
GET https://api.veyra.to/v1/trust-status/{domain}

Response:
{
  "domain": "example.com",
  "production_mode": "trusted",
  "commit_mode": true,
  "commit_mode_provider": "veyra",
  "verify_endpoint": "https://api.veyra.to/v1/verify-token"
}
```

### Step 2: Authorize Action

```
POST https://api.veyra.to/v1/authorize-action
Headers:
  Authorization: Bearer tr_...
  Content-Type: application/json

Body:
{
  "agent_id": "agent-123",
  "action_type": "update",
  "target": "crm",
  "tool_domain": "example.com",
  "action_class": "B",
  "description": "Update contact record"
}

Response:
{
  "token": "vt_abc123...",
  "expires_at": "2026-04-15T12:00:00Z",
  "action_id": "act_xyz789"
}
```

### Step 3: Execute Write with Token

```
POST https://api.example.com/api/write
Headers:
  X-Veyra-Token: vt_abc123...
  Content-Type: application/json

Body: { ...your write payload }
```

### Step 4: Token Verification by Tool (FREE)

```
POST https://api.veyra.to/v1/verify-token
Body:
{
  "token": "vt_abc123..."
}

Response:
{
  "valid": true,
  "agent_id": "agent-123",
  "action_type": "update",
  "action_class": "B",
  "delegated_by": "org-456",
  "budget_reserved": true
}
```

### Step 5: Submit Receipt

```
POST https://api.veyra.to/v1/submit-receipt
Headers:
  Authorization: Bearer tr_...
Body:
{
  "action_id": "act_xyz789",
  "token": "vt_abc123...",
  "result": "success",
  "metadata": { "records_updated": 1 }
}

Response:
{
  "receipt_id": "rcp_def456",
  "settled": true,
  "billed_amount": "€0.02"
}
```

---

## Error Handling: VeyraCommitRequired

When a tool requires commit mode and no valid token is provided:

```json
{
  "error": "VeyraCommitRequired",
  "required_mode": "commit",
  "authorize_endpoint": "https://api.veyra.to/v1/authorize-action",
  "verify_endpoint": "https://api.veyra.to/v1/verify-token",
  "retry_strategy": "authorize_then_retry_with_x_veyra_token"
}
```

**Agent behavior**: When receiving this error:
1. Call `authorize_endpoint` to obtain a token
2. Retry the original request with `X-Veyra-Token` header
3. Submit receipt after successful execution

---

## SDK Reference

### Installation
```bash
npm install @veyrahq/sdk-node
```

### For Tool Builders
```js
import { requireTrustedWrite } from '@veyrahq/sdk-node'

// Protect write endpoints — reads stay open
app.post('/api/write', requireTrustedWrite(), handler)
```

### For Agent Developers
```js
import {
  commitAwareFetch,
  checkTrustStatus,
  authorizeAction,
  handleCommitRequired,
  submitReceipt
} from '@veyrahq/sdk-node'

// Recommended: one-call commit
const res = await commitAwareFetch(toolUrl, init, {
  apiKey: 'tr_...',
  agentId: 'agent-123',
  actionType: 'update',
  target: 'crm'
})
```

### Auto-Recovery Pattern
```js
const res = await fetch(toolUrl, { method: 'POST', body })
if (await isVeyraCommitRequired(res)) {
  const retry = await handleCommitRequired(res, {
    apiKey: 'tr_...',
    agentId: 'agent-123',
    actionType: 'update',
    target: 'crm'
  })
  await retry.retryFetch(toolUrl, { method: 'POST', body })
}
```

---

## Discovery Layers

Veyra supports 4 discovery mechanisms (checked in priority order):

1. **DNS TXT**: `_veyra.{domain}` — checked before any HTTP connection
2. **HTTP Header**: `X-Veyra-Commit` — parsed from any HTTP response
3. **Well-Known**: `/.well-known/veyra.json` — analogous to robots.txt
4. **Error Recovery**: `VeyraCommitRequired` — returned by protected tools

---

## Reference Tools

8 tool domains, each available as a standalone MCP server or via the hosted pack:

| Tool | Description |
|------|-------------|
| veyra-memory | Persistent key-value store |
| veyra-notes | Note-taking with tags |
| veyra-tasks | Task management |
| veyra-snippets | Code snippet storage |
| veyra-bookmarks | Bookmark manager |
| veyra-contacts | Contact management |
| veyra-forms | Form builder |
| veyra-webhooks | Webhook sender |

All tools: reads free, writes require Veyra commit mode.
Hosted pack (recommended): https://mcp.veyra.to/sse

---

## Action Classes & Pricing

| Class | Description | Price |
|-------|------------|-------|
| A | Low-risk writes (drafts, notes) | €0.005/action |
| B | Business-critical writes (CRM, email) | €0.02/action |
| C | High-risk writes (deploy, delete) | €0.10/action |
| D | Cross-org writes (multi-tenant) | €0.25/action |

Trust discovery, token verification, and all read tools are free.

---

## All API Endpoints

| Endpoint | Method | Cost |
|----------|--------|------|
| /v1/capability | GET | Free |
| /v1/trust-status/{domain} | GET | Free |
| /v1/authorize-action | POST | Free |
| /v1/verify-token | POST | Free |
| /v1/submit-receipt | POST | Settlement |
| /v1/settle-action | POST | Settlement |
| /v1/public/stats | GET | Free |

Base URL: https://api.veyra.to

---

## Machine-Readable Discovery Files

| File | URL |
|------|-----|
| llms.txt | https://veyra.to/llms.txt |
| llms-full.txt | https://veyra.to/llms-full.txt |
| OpenAPI | https://veyra.to/openapi.json |
| MCP Server Card | https://veyra.to/.well-known/mcp.json |
| Veyra Discovery | https://veyra.to/.well-known/veyra.json |
| MCP Pack Manifest | https://mcp.veyra.to/.well-known/veyra-pack.json |

---

## Key Principles

1. **Explore is free**: Read, search, and simulate without restrictions
2. **Commit runs through Veyra**: Productive writes are authorized, verified, and settled
3. **Machine-readable**: All signals are structured JSON
4. **Auto-recovery**: Rejected writes include retry instructions
5. **One URL**: Hosted MCP Pack at https://mcp.veyra.to/sse