Getting Started

This guide gets a new team from first login to a working agent with the fewest wrong turns.

What Kravos.ai Does

Kravos.ai helps teams launch AI agents that can answer questions, retrieve from approved content, escalate to humans, and operate across chat and voice experiences.

In practice, most teams use it to:

• connect knowledge sources
• tune the agent's behavior
• launch a web widget or API integration
• monitor conversations and escalations
• improve quality from feedback, analytics, and real examples

Before You Start

You will move faster if you already know:

• which team owns the organization workspace
• which agent you want to launch first
• whether launch will happen through the widget, the API, or both
• which website, files, or docs should become your first Sources
• who will watch Conversations and Takeover Queue after launch

How The Product Is Organized

Organization workspace

Use the organization workspace for cross-agent work:

• viewing all agents
• creating agents
• managing billing and usage
• editing organization branding
• managing team members
• storing provider API keys for bring-your-own-key setups

Agent dashboard

Use the agent dashboard for one agent at a time:

• sources, media, interceptors, and skills
• playground and voice lab
• conversations, takeover queue, feedbacks, and users
• widget settings and agent settings
• tools, MCP servers, API keys, and API reference

Quick Start

First Week Checklist

• confirm the correct organization members have access
• add at least one high-quality source
• test the top 10 real customer questions in the playground
• create interceptors for must-handle edge cases
• decide who monitors the takeover queue
• review at least one real conversation per day after launch

Choose Your Launch Path

Widget-first launch

Choose this when you want the fastest website launch with the least custom engineering. Start with Widget Setup, test in the sandbox, then validate on a staging site.

API-first launch

Choose this when your product already has its own frontend or when you need backend control over chat flows. Start with API Keys and API Reference.

API Essentials For Automation

Everything below is the contract autonomous agents and scripts rely on. It is covered in detail in API Reference, API Keys, and MCP Org API Keys.

Base URL And Authentication

• Public REST API base URL: https://api.kravos.ai/v1
• Authenticate every request with Authorization: Bearer <key> (the x-api-key header is also accepted)
• JSON responses use { "data": ..., "meta": { "requestId": ... } }; errors use { "error": { "code", "message" } }

Origin Behavior

• Browser clients must use a key with allowedOrigins configured. The request Origin must exactly match one configured URL or the API returns 403.
• CLI and server-to-server clients send no Origin header. An empty allowedOrigins list means any origin is accepted, so server-side keys normally leave it blank.

Key Scope: Agent Keys vs Org Keys

• Agent keys (spk_...) are scoped to exactly one agent and are what /v1 routes accept. Create them in the dashboard under API Keys, or through the Platform MCP create_api_key tool with an agentId — the raw key is returned exactly once in oneTimeRawKey.
• Org keys (sk_org_...) are for organization automation and Platform MCP access. /v1 routes reject them because those routes must resolve a single agent.
• Agent-scoped keys via MCP: pass agentId to create_api_key. The key carries only the canonical agents grant for that agent, never destructive permissions, and only agent-safe permissions.

Permission Names

Canonical MCP permission names are area:verb, for example chat:write, sources:read, retrieval:read, end_users:write, docs:read. Backward-compatible legacy agent-key names are still accepted: chat, retrieve, ingest, skill_fetch, trace_read. Compatibility is directional: alias groups are bidirectional (chat ↔ chat:write, retrieve ↔ sources:read ↔ retrieval:read, ingest ↔ ingest.read ↔ ingest.write ↔ sources:write), base ingest satisfies fine-grained ingest.read/ingest.write checks, and legacy chat, retrieve, or ingest keys keep a one-way usage.read grant (never the reverse).

End Users And Memory

• POST /v1/chat (and /v1/chat/stream) accept exactly one of conversationId, endUserId, or externalEndUserId. A stable caller-defined externalEndUserId is resolved idempotently to the same internal end user, so retries never create duplicate identities. Values are trimmed and bounded to 1–200 characters on both the REST routes and the MCP create_end_user tool.
• The Platform MCP create_end_user tool exposes the same idempotent flow with externalEndUserId and returns the real internal endUser.id plus whether it was created.
• Memory workflow: set_end_user_memory stores a fact with key, value, source, and numeric confidence; get_end_user_memory reads the stored facts back.

Chat Turns

POST /v1/chat returns data.reply (always a string), data.citations, data.media, and — when an end user identity was resolved — data.endUserId. Realtime fields realtimeToken and realtimeUrl are included by default whenever a conversation exists; pass includeRealtimeToken: false to omit them. POST /v1/chat/stream streams the same turn as Server-Sent Events and sets the x-end-user-id response header when an end user identity was resolved (both x-request-id and x-end-user-id are CORS-exposed).

Model IDs And Constraints

Model IDs are provider-native strings such as openrouter/anthropic/claude-sonnet-4 or openai/gpt-4o; use list_models to see the configured catalog. Agent model settings accept maxSteps (minimum 2), temperature (0-2), and maxInputTokens (minimum 1; null or absent means Auto).

Where To Go Next

Organization Workspace

Billing, usage, team, provider keys, and agent management.

Sources

Add and monitor the content your agent retrieves from.

Skills

Create reusable instructions and attach them to agents.

Widget Setup

Customize the web widget and grab the embed code.

Playground

Validate quality before you save anything to production.