Developer Docs

API Overview

VStok exposes a session JWT API for the web app plus a read-only Agency API (v1) and MCP-style tools authenticated with API keys.

Base URL

Production: https://api.vstok.net · Development: http://localhost:4000

OpenAPI spec: /openapi.json

API key authentication (Agency)

Create read-only keys in project settings on the Agency plan. Send the key as a Bearer token. Keys start with vstok_live_.

Authorization: Bearer vstok_live_<your_key>

Agency API v1

Read-only REST endpoints scoped to projects your API key can access. Same auth as MCP tools.

• GET /api/v1/projects/:projectId/overview
• GET /api/v1/projects/:projectId/visibility-history?days=30
• GET /api/v1/projects/:projectId/audits/latest

MCP read-only tools

Minimal MCP-style HTTP surface wrapping the same Agency data. Authenticate with an API key, then call tools via REST or JSON-RPC.

• GET /api/mcp/tools
• POST /api/mcp (methods: tools/list, tools/call)
• POST /api/mcp/get_visibility_overview
• POST /api/mcp/list_opportunities
• POST /api/mcp/get_latest_audit

POST /api/mcp
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_visibility_overview","arguments":{"projectId":"<uuid>"}}}

Session authentication

Include a Supabase JWT in the Authorization header for authenticated web-app endpoints.

Authorization: Bearer <supabase_access_token>

Projects

Create and manage brand projects with competitors and prompts.

GET /api/projects
POST /api/projects
GET /api/projects/:id

Audits

Start an AI visibility audit for a project. Requires Redis worker running.

POST /api/projects/:id/audits/start

Webhooks

Stripe and YooKassa webhooks update subscription state.

POST /api/webhooks/stripe
POST /api/webhooks/yookassa