Authentication & conventions
- All authenticated endpoints take an OAuth2/OIDC Bearer token issued by the platform's Keycloak realm (auth.vegaduta.ai/realms/agentic-ai). Interactive sign-in uses PKCE; service integrations use the client-credentials flow on a confidential client.
- Tenant isolation is enforced below the API: every tenant reads and writes its own database schema. No endpoint accepts a tenant id from the caller to cross tenants.
- Rate limits are enforced per-IP on public endpoints and per-tenant on authenticated ones; 429 responses carry a Retry-After header.
Bearer JWTPublicWebhook signatureDevice token
Agents
Create and operate agents: personas, provider/model settings, sessions, versions, schedules, triggers and share links.
| Method | Path | Auth | Description |
|---|---|---|---|
| GET POST | /api/agents | Bearer JWT | List and create agents. |
| GET PUT DELETE | /api/agents/{id} | Bearer JWT | Read, update or retire one agent. |
| GET | /api/agents/{id}/versions | Bearer JWT | Immutable version history; every save is a new version. |
| GET POST | /api/agents/{id}/triggers | Bearer JWT | Event/webhook triggers that start this agent. |
| GET PUT | /api/agents/{id}/schedule | Bearer JWT | Cron-style schedule for autonomous runs. |
| POST | /api/agents/{id}/share | Bearer JWT | Mint a read-only public share link (/a/<id>). |
| GET | /api/agents/{id}/guardrails | Bearer JWT | Guardrail rules bound to this agent. |
| GET POST | /api/agents/{id}/quality/* | Bearer JWT | Eval datasets, runs and the quality gate verdict. |
Sessions & feedback
Chat sessions, assisted replies and the turn-level feedback stream that powers RL exports and the resolution meter.
| Method | Path | Auth | Description |
|---|---|---|---|
| GET POST | /api/session | Bearer JWT | Open and list chat sessions. |
| POST | /api/assist | Bearer JWT | One-shot assist completions outside a session. |
| POST | /api/rl | Bearer JWT | Record a feedback signal (THUMBS_UP/DOWN, RATING, EDIT, RESOLVED, UNRESOLVED) for a turn. |
| GET | /api/agents/{id}/sessions/{sessionId}/llm-usage | Bearer JWT | Token/cost rollup for one session. |
Workflows
Multi-step deterministic automations an agent can trigger; runs can pause for human input and resume.
| Method | Path | Auth | Description |
|---|---|---|---|
| GET POST | /api/workflows | Bearer JWT | List and create workflows. |
| GET PUT | /api/workflows/{id} | Bearer JWT | Read or update a workflow definition. |
| GET POST | /api/workflows/input-requests | Bearer JWT | Pending human-input questions and their answers. |
| POST | /api/workflows/{id}/share | Bearer JWT | Mint a read-only public share link (/w/<id>). |
Channels (omnichannel)
Connect WhatsApp, Telegram, Slack, Teams, Discord, email, voice and social channels; route inbound conversations to agents with human handoff.
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/channels | Bearer JWT | Configured channels and their state. |
| GET | /api/channels/status | Bearer JWT | Per-channel connectivity health. |
| GET PUT | /api/channels/routing | Bearer JWT | Which agent answers which channel/session. |
| POST | /api/channels/pairing | Bearer JWT | Pair an end-user session to an agent (pairing codes). |
| POST | /api/channels/{channel}/credential | Bearer JWT | Store channel credentials (encrypted at rest). |
| POST | /api/channels/whatsapp-qr/* | Bearer JWT | QR-session lifecycle for the self-hosted WhatsApp service. |
| GET POST | /api/handoff | Bearer JWT | Operator inbox: take over or release a live conversation (AGENT/AWAITING_HUMAN/HUMAN). |
MCP & tool ecosystem
Model Context Protocol server registrations, the tool registry, and the agent-facing A2A surface. Dynamic STDIO registrations run sandboxed (see the security changelog).
| Method | Path | Auth | Description |
|---|---|---|---|
| GET POST DELETE | /api/mcp/registrations | Bearer JWT | Dynamic MCP server registrations (reviewed before use). |
| GET | /api/mcp/registry | Bearer JWT | Tools exposed to this tenant's agents. |
| GET POST | /api/mcpserver/grants | Bearer JWT | Grant an agent access to an MCP server. |
| GET | /.well-known/agent-card.json | Public | A2A agent card describing this deployment's agents. |
| POST | /api/a2a | Bearer JWT | Agent-to-agent JSON-RPC endpoint. |
| GET POST | /api/tools/* | Bearer JWT | Tool classifications, OpenAPI-imported tools, script tools, code tools. |
Knowledge
Document collections, connectors and ingestion jobs behind retrieval-augmented answers.
| Method | Path | Auth | Description |
|---|---|---|---|
| GET POST | /api/knowledge/collections | Bearer JWT | Collections of ingested documents. |
| GET POST | /api/knowledge/connectors | Bearer JWT | External sources (drives, buckets, sites) feeding collections. |
| GET | /api/knowledge/jobs | Bearer JWT | Ingestion job state and history. |
Billing & resolutions
Subscriptions, outcome-based resolution metering, and provider webhooks. Resolution events are the billable unit of outcome-priced plans.
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/tenant/subscription | Bearer JWT | Current plan, seats and billing state. |
| GET | /api/tenant/resolutions/summary | Bearer JWT | Outcome counts + billable total for a period (PERM_MANAGE_BILLING). |
| GET | /api/tenant/resolutions | Bearer JWT | The underlying resolution events, newest first. |
| POST | /api/tenant/resolutions | Bearer JWT | Explicitly record a resolution the sweep cannot see (idempotent on dedupeKey). |
| POST | /api/tenant/resolutions/{id}/dispute | Bearer JWT | Contest a billable event; the row stays, billing flips off. |
| POST | /api/billing/webhook/* | Webhook signature | Provider (Razorpay/Stripe) delivery endpoints; deduped on a durable ledger. |
| POST | /api/budget/top-up | Bearer JWT | Add prepaid budget for usage-billed features. |
Devices & edge
Claim-and-poll device pairing and the edge gateway that runs turns close to the user.
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/devices/claim | Public | Claim a device pairing code (no session exists yet - same posture as /api/signup). |
| POST | /api/devices/poll | Device token | Long-poll for commands addressed to this device. |
| POST | /api/devices/commands/{id}/result | Device token | Report a command result back. |
| POST | /api/edge/turns | Bearer JWT | Execute a turn through the edge gateway. |
Operations & administration
Tenant administration, platform-level operations, and the public liveness/status probes.
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/public/status | Public | Component-level platform status feeding /status (names + status codes only). |
| GET | /api/system/status/live | Public | Bare liveness probe: {"status":"UP"}. |
| GET | /api/system/status | Bearer JWT | Full internal dashboard status (pool, JVM, MCP inventory). |
| GET PUT | /api/tenant/settings | Bearer JWT | Tenant-scoped settings. |
| GET POST | /api/tenant/sso | Bearer JWT | SSO/SCIM enterprise identity configuration. |
| * | /api/platform/* | Bearer JWT | Platform-operator surface (tenants, plan limits, abuse monitor, MCP review) - requires the platform-admin role. |
| POST | /webhook/* | Webhook signature | Inbound channel webhooks (WhatsApp/Telegram/Slack/…), verified per provider. |
Ship something on it
The Free plan needs no card - sign up, create an agent, and every endpoint above is live against your tenant. Live platform health is on the status page.
