Docs

One place for setup, guides, and API reference.

Start here first. The core Veriova model is packs, shared context, rules, skills, and tooling. Reviews and blueprints are documented here as secondary validation utilities.

Base URL: https://api.veriova.com/api/v1

All authenticated endpoints accept a Authorization: Bearer cv_... header. The web app also uses a session cookie (cv_session).

Start fast

Use Veriova GPT

Open path

Connect tools

MCP clients

Open path
Works with Claude, Cursor, Codex, and ChatGPT|Live status|Security

Remote MCP connector (OAuth)

If you're using veriova inside chat products (Claude Chat / ChatGPT connectors), the connector uses OAuth against these endpoints:

For trusted OpenAI callback hosts, exact per-GPT redirect registration is not required.

GET/.well-known/oauth-protected-resource

Protected Resource Metadata used by MCP clients to discover the OAuth authorization server.

Response

{
  "resource": "https://mcp.veriova.com/mcp",
  "authorization_servers": ["https://api.veriova.com"],
  "scopes_supported": ["mcp"]
}
GET/.well-known/oauth-authorization-server

OAuth Authorization Server Metadata (issuer, endpoints, supported grants).

Response

{
  "issuer": "https://api.veriova.com",
  "authorization_endpoint": "/oauth/authorize",
  "token_endpoint": "/oauth/token",
  "registration_endpoint": "/oauth/register"
}
POST/oauth/register

Dynamic Client Registration (used by connector clients).

Request body

{
  "client_name": "My Connector",
  "redirect_uris": ["https://client.example.com/callback"]
}

Response

{
  "client_id": "uuid",
  "client_name": "My Connector",
  "redirect_uris": ["https://client.example.com/callback"],
  "token_endpoint_auth_method": "none"
}
GET/oauth/authorize

Authorization endpoint (redirects to web login if needed, then shows consent).

Response

302 Redirect to /login?next=... (if not signed in)
POST/oauth/token

Exchange authorization code for an access token. PKCE verifier is optional (required only when a code_challenge was sent at authorize time).

Request body

grant_type=authorization_code
client_id=...
redirect_uri=...
code=...
code_verifier=...

Response

{
  "access_token": "cv_...",
  "token_type": "Bearer",
  "expires_in": 31536000,
  "scope": "mcp"
}

Authentication

POST/auth/magic-link/request

Request a magic link sign-in email. Always returns 200 to avoid user enumeration.

Request body

{ "email": "dev@acme.com" }

Response

{ "message": "If this email is valid, a sign-in link has been sent." }
POST/auth/magic-link/verify

Verify a magic link token. Sets a cv_session cookie. Returns api_key only on first login.

Request body

{ "token": "cvml_..." }

Response

{
  "message": "Signed in",
  "api_key": "cv_... (first login only)",
  "project_slug": "your-default-project"
}
POST/auth/logout

Logs out the current session (clears cv_session).

Response

{ "message": "Logged out" }

Projects

GET/projectsAuth

List all projects you have access to.

Response

[
  {
    "id": "uuid",
    "slug": "my-app",
    "name": "My App",
    "created_at": "2025-01-01T00:00:00Z"
  }
]
POST/projectsAuth

Create a new project. Requires ADMIN role.

Request body

{
  "name": "My App",
  "slug": "my-app",
  "description": "Optional description"
}

Response

{
  "id": "uuid",
  "slug": "my-app",
  "name": "My App"
}
POST/me/default-projectAuth

Set (or clear) the default project for your API key.

Request body

{ "project_slug": "my-app" }

Response

{ "message": "Default project updated", "default_project_slug": "my-app" }

Session Context

Session Context is the prebuilt pack your assistant should load before it starts building, reviewing, or advising. It combines pinned and verified context with your production standards.

GET/context/sessionAuth

Load the ready-to-inject session context bundle for the current account and accessible projects.

Response

{
  "pack": "# Team Context — Veriova\n\n## Pinned Decisions & Conventions\n...",
  "memory_count": 12,
  "standards_count": 4
}

Rules

Rules define the reusable defaults Veriova distributes across packs, tooling, and validation utilities. They turn team expectations into explicit criteria assistants can inherit everywhere.

GET/standardsAuth

List the production standards and criteria defined for the account.

Response

{
  "items": [
    {
      "id": "uuid",
      "name": "API reliability",
      "description": "What must be true before shipping backend work",
      "category": "backend",
      "criteria": [
        { "id": "uuid", "title": "Structured errors", "required": true }
      ]
    }
  ]
}
POST/standardsAuth

Create a new production standard.

Request body

{
  "name": "Security review",
  "description": "Minimum controls for public-facing features",
  "category": "security"
}

Response

{
  "id": "uuid",
  "name": "Security review",
  "description": "Minimum controls for public-facing features",
  "category": "security"
}
POST/standards/{id}/criteriaAuth

Add a required or optional criterion to an existing standard.

Request body

{
  "title": "Auth rate limiting",
  "description": "Public endpoints must be rate limited",
  "category": "security",
  "required": true
}

Response

{
  "id": "uuid",
  "standard_id": "uuid",
  "title": "Auth rate limiting",
  "required": true
}
POST/standards/seedAuth

Seed a starter standards library for a new workspace.

Response

{
  "items": [
    { "id": "uuid", "name": "Reliability" },
    { "id": "uuid", "name": "Security" }
  ]
}

Readiness Review

Reviews are the optional validation layer. They score AI-built work against your rules and return blockers, score, and next actions when you want a deeper check.

POST/prototypesAuth

Run a readiness review from a written technical description. If you pass project_slug, the review is associated with that project.

Request body

{
  "project_slug": "my-app",
  "title": "Payments v2",
  "description": "Stripe checkout flow with webhook processing, retries, and audit logging",
  "artifact_summary": "Prototype built with Claude and reviewed for backend readiness",
  "check_type": "readiness_review",
  "met_criteria_ids": []
}

Response

{
  "assessment": {
    "id": "uuid",
    "title": "Payments v2",
    "production_score": 71,
    "check_type": "readiness_review",
    "share_token": "sv_..."
  },
  "report": {
    "production_score": 71,
    "required_gaps": [{ "title": "Auth rate limiting" }],
    "optional_gaps": [],
    "gap_analysis": "Release blockers remain around edge-case security and observability."
  }
}
GET/prototypesAuth

List readiness reviews created for the account.

Response

{
  "items": [
    {
      "id": "uuid",
      "title": "Payments v2",
      "production_score": 71,
      "check_type": "readiness_review",
      "created_at": "2026-04-22T09:00:00Z"
    }
  ]
}
POST/projects/{slug}/reviews/ingestAuth

Run a readiness review from an artifact upload or GitHub repo. Use multipart/form-data with repo_url and/or archive.

Request body

Content-Type: multipart/form-data

title=Payments v2
repo_url=https://github.com/acme/payments-v2
github_token=ghp_...
notes=Prototype ready for backend review

Response

{
  "assessment": {
    "id": "uuid",
    "title": "Payments v2",
    "production_score": 64
  },
  "report": {
    "required_gaps": [{ "title": "Observability" }],
    "gap_analysis": "Good prototype, but release blockers remain."
  }
}

Blueprints

Blueprints turn a reviewed prototype into continuation material engineering can actually use: stack delta, missing pieces, continuation brief, and tooling starter content.

POST/projects/{slug}/handoff/analyzeAuth

Generate a blueprint analysis from a reviewed prototype or manual description.

Request body

{
  "prototype_name": "Payments v2",
  "description": "Checkout flow with Stripe, webhook retries, and admin refund tooling",
  "tech_used": "Next.js, TypeScript, Stripe",
  "repo_url": "https://github.com/acme/payments-v2"
}

Response

{
  "compatibility_score": 78,
  "stack_delta": [{ "area": "payments", "severity": "medium" }],
  "missing_pieces": ["Runbook", "Monitoring dashboards"],
  "continuation_brief": "Engineering should harden webhook idempotency and error handling...",
  "ai_config_content": "# CLAUDE.md\n..."
}
POST/projects/{slug}/handoff/starter-packAuth

Generate a starter blueprint from pinned and verified project context for continued AI work.

Response

{
  "content": "# Starter Pack\n\nProject: my-app\n...",
  "project_slug": "my-app",
  "item_count": 7,
  "generated_at": "2026-04-22T09:00:00Z"
}

Shared Context

Memory items are the primitives underneath shared context. They capture decisions, conventions, patterns, and lessons so every future session, pack, and tooling rollout starts better informed.

POST/memory/candidatesAuth

Store context candidates. Items are embedded and stored for review. Types: decision, convention, pattern, lesson, snippet, reference.

Request body

{
  "project_slug": "my-app",
  "items": [
    {
      "type": "decision",
      "title": "Use PostgreSQL",
      "content": "Chose PostgreSQL for pgvector support.",
      "importance": 8,
      "tags": ["database", "infrastructure"]
    }
  ]
}

Response

{ "candidate_ids": ["uuid1", "uuid2"] }
POST/memory/searchAuth

Semantic search across context items using vector similarity.

Request body

{
  "project_slug": "my-app",
  "query": "which database did we choose?",
  "k": 5
}

Response

{
  "results": [
    {
      "id": "uuid",
      "title": "Use PostgreSQL",
      "type": "decision",
      "score": 0.92,
      "status": "verified"
    }
  ]
}
GET/memory?project=my-appAuth

List stored context items with optional filters: status, type.

Response

{
  "items": [...],
  "total": 42,
  "page": 1
}
GET/memory/{id}Auth

Get a single stored context item by ID.

Response

{
  "id": "uuid",
  "type": "decision",
  "title": "Use PostgreSQL",
  "content": "...",
  "status": "verified",
  "importance": 8,
  "tags": ["database"],
  "created_at": "2025-01-01T00:00:00Z"
}
POST/memory/{id}/verifyAuth

Mark a context item as verified. Requires REVIEWER role.

Response

{ "message": "Memory verified" }
POST/memory/{id}/pinAuth

Pin a context item so it always appears in session packs. Requires REVIEWER role.

Response

{ "message": "Memory pinned" }
POST/memory/{id}/deprecateAuth

Deprecate a context item. Requires REVIEWER role.

Response

{ "message": "Memory deprecated" }

Knowledge Sources

Knowledge Sources let you index external repositories (starting with GitHub) and search them semantically/keyword. This is a paid feature (pro/team/enterprise).

GET/integrations/github/startAuth

Start GitHub OAuth from the dashboard (stores a token encrypted at rest). Redirect-based flow.

Response

(redirect to GitHub)
POST/integrations/github/startAuth

Fetch-friendly start endpoint: sets an HttpOnly state cookie and returns the GitHub OAuth URL.

Response

{ "url": "https://github.com/login/oauth/authorize?..." }
GET/integrations/github/reposAuth

List repositories accessible to your connected GitHub account.

Response

{
  "repos": [
    { "full_name": "owner/repo", "html_url": "https://github.com/owner/repo", "private": false, "default_branch": "main" }
  ]
}
POST/knowledge-sourcesAuth

Create a GitHub knowledge source. The backend will enqueue an initial sync run.

Request body

{
  "provider": "github",
  "name": "veriova repo",
  "config": {
    "repo": "ajibadedapo/veriova",
    "ref": "main"
  }
}

Response

{
  "id": "uuid",
  "provider": "github",
  "name": "veriova repo",
  "status": "ACTIVE",
  "last_sync_at": null
}
POST/knowledge-sources/{id}/syncAuth

Trigger a re-sync (enqueue a new sync run).

Response

{ "id": "uuid", "status": "PENDING" }
POST/knowledge/searchAuth

Search indexed knowledge chunks. Uses semantic search when embeddings exist, keyword fallback otherwise.

Request body

{
  "query": "where is the deployment workflow defined?",
  "k": 5
}

Response

{
  "semantic_used": true,
  "results": [
    {
      "path": ".github/workflows/deploy.yml",
      "score": 0.83,
      "content": "..."
    }
  ]
}

Context Pack

POST/context-packAuth

Generate a context pack-a token-budgeted bundle of relevant memories ready to inject into your LLM prompt.

Request body

{
  "project_slug": "my-app",
  "query": "how do we handle authentication?",
  "max_tokens": 2000
}

Response

{
  "pack": "## Project Context\n\n### Decisions\n- Use JWT for auth...",
  "token_count": 1850,
  "truncated": false,
  "items": [...]
}

Usage

GET/usage?project=my-appAuth

Get per-project usage counters (memory count, artifact bytes, knowledge indexed bytes) plus plan limits for the current tier.

Response

{
  "tier": "pro",
  "usage": {
    "project_id": "uuid",
    "memory_items_count": 128,
    "artifacts_count": 3,
    "artifacts_bytes": 10485760,
    "knowledge_sources_count": 1,
    "knowledge_chunks_count": 420,
    "knowledge_chunk_bytes": 7340032,
    "updated_at": "2026-02-15T00:00:00Z"
  },
  "limits": {
    "knowledge_sources_max": 5,
    "knowledge_chunk_bytes_max": 52428800
  }
}

API Keys

POST/api-keysAuth

Create a new API key. Requires ADMIN role. Roles: READER, REVIEWER, ADMIN.

Request body

{
  "name": "ci-pipeline",
  "role": "READER",
  "allowed_projects": ["my-app"]
}

Response

{
  "id": "uuid",
  "key": "cv_...",
  "prefix": "cv_abc12",
  "name": "ci-pipeline",
  "role": "READER",
  "message": "Save this key-it cannot be recovered"
}
GET/api-keysAuth

List all API keys. Requires ADMIN role.

Response

[
  {
    "id": "uuid",
    "prefix": "cv_abc12",
    "name": "ci-pipeline",
    "role": "READER",
    "last_used_at": "2025-01-01T00:00:00Z"
  }
]
DELETE/api-keys/{id}Auth

Revoke an API key. Requires ADMIN role.

Response

{ "message": "API key revoked" }

Health

GET/health

Check server health. Returns status of database, pgvector, and object storage.

Response

{
  "status": "ok",
  "checks": {
    "db": "ok",
    "pgvector": "ok",
    "storage": "ok"
  }
}

Agent service

Base URL: https://api.veriova.com/openclaw

GET/openclaw/health

Checks Agent service health and reports planner/memory availability.

Response

{
  "status": "ok",
  "service": "openclaw",
  "version": "0.2.0",
  "shell_enabled": false,
  "openai_planner_enabled": true,
  "veriova_enabled": true
}
POST/openclaw/api/v1/agent/run

Runs the agent synchronously. Use mode=plan for planning only, or mode=execute for full execution.

Request body

{
  "goal": "Fetch API health and summarize result",
  "mode": "execute",
  "use_memory": true
}

Response

{
  "ok": true,
  "mode": "execute",
  "planner": "openai",
  "plan": [{ "id": "step-1", "tool": "http" }],
  "execution": { "steps": [] },
  "summary": "Run completed"
}
POST/openclaw/api/v1/agent/jobs

Queues an asynchronous agent job.

Request body

{
  "goal": "Collect status from internal services",
  "mode": "execute"
}

Response

{
  "job_id": "uuid",
  "status": "queued"
}
GET/openclaw/api/v1/agent/jobs/{id}

Retrieves a single job state and output/error once done.

Response

{
  "id": "uuid",
  "status": "completed",
  "input": { "goal": "..." },
  "output": { "ok": true }
}
GET/openclaw/api/v1/agent/memory/status

Reports whether Veriova memory integration is enabled for Agent.

Response

{
  "enabled": true,
  "base_url": "https://api.veriova.com",
  "project": "my-project"
}