Rylvo API Reference

Quick Start

Make your first API call in under a minute. You need your company_id, bot_id, and API key from the dashboard.

curl -X POST https://rylvo.com/api/v1/respond \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "company_id": "your_company_id",
    "bot_id": "your_bot_id",
    "session_id": "session_001",
    "workflow_id": "support_triage",
    "current_user_message": "I can't access my account."
  }'

Access Model

Rylvo currently exposes two surfaces. Knowing which one to use for what avoids confusion when integrating from a backend vs operating the platform day-to-day.

Sections below marked with Dashboard-only do not yet have a public REST endpoint. They remain fully functional inside the dashboard and their behavior affects the /v1/respond runtime.

Authentication

All API requests require an API key sent in the X-API-Key header. Create keys from your dashboard.

X-API-Key: rylvo_sk_live_abc123...

Provider Keys (BYOK)Dashboard-only

Every bot chat on Rylvo runs on your own LLM provider key. Rylvo never charges your provider account - the request goes directly to your chosen provider (OpenAI / Anthropic / Google / DeepSeek / xAI / OpenRouter) with your key. Manage keys in Settings → LLM Provider Keys.

Bot Tagging (Mandatory)

Bots are the primary organizational unit for your API usage. Each bot represents a distinct agent or use case (e.g. "Support Triage Bot", "Sales Qualifier Bot"). Create bots from your dashboard, then use the bot ID to tag every API call.

How it works

Example request with bot_id

{
  "company_id": "comp_001",
  "bot_id": "bot_abc123def456",
  "session_id": "sess_001",
  "workflow_id": "support_triage",
  "current_user_message": "I can't access my account."
}

Bot Chat PlaygroundDashboard-only

Test a bot's behavior end-to-end before pointing production traffic at it. The playground at /dashboard/bots/[botId]/chat assembles the full runtime exactly like /v1/respond does: system prompts, placeholders, guardrails, connectors, KB connections, and evolution rules.

Each playground turn shows the prompt stack, guardrail decisions, connector calls, evolution rules applied, stage & action chosen, verification outcome, operator whispers, token usage, and cost - all alongside the message itself.

Bot TestsDashboard-only

Define reusable test cases per bot and run them on demand or via an Automation schedule. Manage at /dashboard/bots/[botId]/tests.

Failed test cases can be converted into Edge Cases so the engine tracks them through the detect → classify → fix → verify loop.

Agent Groups (Multi-Bot Teams)Dashboard-only

Compose multiple bots into a team where one bot routes, delegates, and merges results from specialists. Useful for workflows that span domains (e.g. billing + technical support) or require parallel drafts.

Group chats record which member bots contributed to each turn and how routing decisions were made, so you can debug who said what and why.

Endpoints

Decision API

The POST /v1/respond endpoint is the core of Rylvo. Send a user message with session context, and receive a complete workflow decision including stage prediction, next action, verification result, and response text.

Request Format

{
  "company_id": "comp_001",
  "bot_id": "bot_abc123def456",
  "session_id": "sess_001",
  "workflow_id": "support_triage",
  "current_user_message": "The display shows error E42.",
  "current_structured_state": {
    "order_id": "ORD-12345-ABC",
    "identity_verified": true,
    "error_code": "E42"
  },
  "business_metadata": {
    "customer_tier": "premium"
  },
  "tool_mode": "auto",
  "memory_mode": "auto"
}

Response Format

{
  "id": "resp_a1b2c3d4e5f6",
  "workflow_id": "support_triage",
  "trace_id": "tr_def456",
  "stage_prediction": {
    "stage_id": "error_code_handling",
    "confidence": 0.92
  },
  "next_action": {
    "action_id": "lookup_error_code",
    "action_class": "tool_call",
    "confidence": 0.90,
    "rationale": "Error code detected, retrieving guidance."
  },
  "verification": {
    "status": "pass",
    "reason_codes": ["decision_verified"]
  },
  "escalation": {
    "should_escalate": false,
    "escalation_target": null,
    "reason_codes": []
  },
  "output_text": "I captured E42. Let me retrieve the matching guidance.",
  "confidence": 0.91,
  "trace_id": "tr_def456"
}

Workflow Stages (13)

Error Handling

// Error response format
{
  "error": {
    "type": "authentication_error",
    "message": "Missing X-API-Key header."
  }
}

Multi-Turn Example

Rylvo tracks conversation state across turns using the session_id. Each turn builds on the previous state automatically.

curl -X POST https://rylvo.com/api/v1/respond \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"company_id":"comp_001","bot_id":"bot_abc123","session_id":"conv_001","workflow_id":"support_triage","current_user_message":"My subscription renewal failed."}'
# → stage: identity_collection, action: verify_identity

curl -X POST https://rylvo.com/api/v1/respond \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"company_id":"comp_001","bot_id":"bot_abc123","session_id":"conv_001","workflow_id":"support_triage","current_user_message":"My serial is SN-98765-XYZ"}'
# → stage: serial_validation, action: run_serial_validation

curl -X POST https://rylvo.com/api/v1/respond \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"company_id":"comp_001","bot_id":"bot_abc123","session_id":"conv_001","workflow_id":"support_triage","current_user_message":"I want to talk to a real person."}'
# → stage: escalation, action: handoff_to_human, escalation: true

Webhooks

Receive async notifications after each decision by including a callback object in your request.

{
  "callback": {
    "target_url": "https://your-app.com/hooks/rylvo",
    "event_type": "workflow.decision.completed",
    "headers": { "Authorization": "Bearer your-token" },
    "include_full_response": true,
    "shared_secret": "hmac-signing-secret"
  }
}

Rate Limits

These limits apply to direct POST /v1/respond calls. Bot chat launched from the dashboard uses your own BYOK provider key and is NOT rate-limited by Rylvo. Architect Credits (Workspace Architect, Agent Evolution, Prompt Auto-Optimization, Red Team) are metered separately by USD wallet - see pricing · credits.

Usage headers are included in every response: X-Plan-Requests-Remaining, X-RateLimit-Remaining

Billing & Usage

Rylvo has a dual billing model: a monthly subscription plan covers platform capacity (bots, prompts, guardrails, KB sources, connectors, observability, SLA). On top of that, two independent wallets meter the work that actually runs:

Cost formula (Backend API)

cost_usd = (input_tokens  × model.price_per_input_token)
         + (output_tokens × model.price_per_output_token)

Request lifecycle

Response headers on /v1/respond

Top-up & ledger Dashboard-only

Top up in any amount from $5 to $10,000 at Dashboard → Billing. Every debit and credit is recorded in an immutable transactions ledger you can review and export from the Billing page (per-bot breakdown, model breakdown, date range, CSV).

Traces & Analytics

Every decision is traced. You can re-run any past decision (replay), list every turn in a session, and pull rollup analytics per company. These endpoints are public REST - they work with the same X-API-Key as /v1/respond.

Endpoints

Replay example

curl https://rylvo.com/api/v1/traces/tr_def456/replay \
  -H "X-API-Key: YOUR_API_KEY"

Dashboard note: richer per-chat traces (prompt stack, guardrail decisions, connector payloads, evolution rules applied, operator whispers) are stored alongside each playground/group chat message and are not yet exposed over REST. See Bot Chat Playground.

SDKs & Libraries

import requests

response = requests.post(
    "https://rylvo.com/api/v1/respond",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "company_id": "comp_001",
        "bot_id": "bot_abc123def456",
        "session_id": "sess_001",
        "workflow_id": "support_triage",
        "current_user_message": "I can't access my account.",
    },
)

data = response.json()
print(f"Stage: {data['stage_prediction']['stage_id']}")
print(f"Action: {data['next_action']['action_id']}")
print(f"Response: {data['output_text']}")

const response = await fetch("https://rylvo.com/api/v1/respond", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    company_id: "comp_001",
    bot_id: "bot_abc123def456",
    session_id: "sess_001",
    workflow_id: "support_triage",
    current_user_message: "I can't access my account.",
  }),
});

const data = await response.json();
console.log("Stage:", data.stage_prediction.stage_id);
console.log("Action:", data.next_action.action_id);
console.log("Response:", data.output_text);

PromptsDashboard-only

Prompts are the instructions your agents follow at runtime. Create them from the Prompts dashboard, assign them to bots, and optionally enable self-improving optimization.

Key Concepts

Creating a Prompt

Placeholder Syntax

Placeholders use double-brace syntax: {{key}}. At runtime, they are resolved with values from the API request or defaults.

You are a support agent for {{company_name}}.

Greet the user as {{user_name}} in a {{tone}} tone.
Respond in {{language}}. Keep replies under {{max_length}} tokens.

{{context}}

Version History

Every edit to a prompt creates a new version. Versions are tracked as manual or auto_optimized. You can view, compare, and promote any version to active from the prompt detail panel.

Resource VersioningDashboard-only

Every runtime-affecting resource is versioned - not just prompts. Prompts, guardrails, connectors, evolution rules, and KB blueprints all track an immutable version history plus the source of each edit. You can diff, preview, promote, and rollback from the dashboard.

Edit sources

What's versioned

What you can do from the dashboard

• View the full edit history for any resource (who, what, when, why)
• Diff any two versions side by side
• Preview a version before promoting it to active
• Promote any past version back to active in one click (rollback)
• Filter history by source - manual, architect, auto-generated, etc.

Every runtime decision records which version was active when it ran, so you can correlate performance changes with specific edits - not just which resource was used, but which version of it.

Self-Improving PromptsDashboard-only

Rylvo implements research-backed automatic prompt optimization. When enabled, the system continuously generates, evaluates, and selects better prompt variants using real performance data.

Optimization Strategies

Four research-backed strategies are available. Each uses a different approach to prompt improvement.

Configuration Options

Enabling Self-Improvement

Prompt API Usage

Use prompts programmatically by including a prompt_id in your API requests. The system resolves the active prompt version, substitutes placeholders, and uses the resulting text.

Using a Prompt in API Requests

Add the prompt_id field to your POST /v1/respond request. Optionally pass prompt_overrides to override placeholder defaults.

{
  "company_id": "comp_001",
  "bot_id": "bot_abc123def456",
  "session_id": "sess_001",
  "workflow_id": "support_triage",
  "prompt_id": "prompt_xyz789",
  "prompt_overrides": {
    "company_name": "Acme Corp",
    "tone": "empathetic",
    "language": "Spanish",
    "max_length": "512"
  },
  "current_user_message": "I can't access my account."
}

Prompt Resolution Flow

Python Example

import requests

response = requests.post(
    "https://rylvo.com/api/v1/respond",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "company_id": "comp_001",
        "bot_id": "bot_abc123def456",
        "session_id": "sess_001",
        "workflow_id": "support_triage",
        "prompt_id": "prompt_xyz789",
        "prompt_overrides": {
            "company_name": "Acme Corp",
            "tone": "empathetic",
            "language": "English",
        },
        "current_user_message": "My subscription renewal failed.",
    },
)

data = response.json()
print(f"Used prompt version: v{data.get('prompt_version', 'N/A')}")
print(f"Response: {data['output_text']}")

JavaScript / Node.js Example

const response = await fetch("https://rylvo.com/api/v1/respond", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    company_id: "comp_001",
    bot_id: "bot_abc123def456",
    session_id: "sess_001",
    workflow_id: "support_triage",
    prompt_id: "prompt_xyz789",
    prompt_overrides: {
      company_name: "Acme Corp",
      tone: "empathetic",
      language: "English",
    },
    current_user_message: "My subscription renewal failed.",
  }),
});

const data = await response.json();
console.log("Prompt version:", data.prompt_version);
console.log("Response:", data.output_text);

Email DeliveryDashboard-only

Rylvo handles its own transactional emails (welcome, team invites, scheduled reports, operational alerts) automatically. Templates are branded and theme-aware - there is nothing for you to set up.

To send your own emails on workflow events (e.g. notify a human when a session escalates), use an Event Connector or add an Email channel in Automation.

Webhook Connectors

Connectors let Rylvo call your systems during workflow execution. Register webhook endpoints for tool calls, state sync, or event notifications - Rylvo handles auth, retry, and signing.

Three connector types

Register a tool connector

curl -X POST https://rylvo.com/api/v1/connectors \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{
    "company_id": "comp_001",
    "connector_type": "tool",
    "name": "Salesforce Case Creator",
    "auth": {
      "auth_type": "api_key",
      "api_key_header": "X-Salesforce-Key",
      "api_key_value": "your_salesforce_api_key"
    },
    "tool_config": {
      "tool_name": "create_salesforce_case",
      "tool_description": "Create a case in Salesforce",
      "input_schema": { "type": "object", "properties": { "issue_summary": { "type": "string" } } }
    },
    "endpoint": { "url": "https://your-app.com/rylvo/tools/create-case", "method": "POST" }
  }'

API endpoints

7 authentication methods

10 subscribable event types

Connector Python SDK

Typed convenience methods for all connector operations. Sync and async variants included.

from core.connectors.sdk import ConnectorSDK

sdk = ConnectorSDK(base_url="https://rylvo.com", api_key="rylvo_sk_live_...")

# Register a tool connector
connector = sdk.create_tool_connector(
    company_id="comp_001",
    name="Salesforce Case Creator",
    endpoint_url="https://your-app.com/rylvo/tools/create-case",
    tool_name="create_salesforce_case",
    tool_description="Create a case in Salesforce",
    auth_type="api_key",
    api_key_header="X-Salesforce-Key",
    api_key_value="your_salesforce_api_key",
)

# Test + activate
test = sdk.test_connector("comp_001", connector["connector_id"])
if test["success"]:
    sdk.activate("comp_001", connector["connector_id"])

# List available tools
tools = sdk.list_available_tools("comp_001")
print(f"{tools['total']} webhook tools available")

Async variant

from core.connectors.sdk import AsyncConnectorSDK

async with AsyncConnectorSDK(base_url="...", api_key="...") as sdk:
    connector = await sdk.create_event_connector(
        company_id="comp_001",
        name="Slack Alerts",
        endpoint_url="https://hooks.slack.com/...",
        event_types=["workflow.escalation.triggered"],
    )
    await sdk.activate("comp_001", connector["connector_id"])

Error handling

MCP HubDashboard-only

The MCP Hub is Rylvo's Model Context Protocol registry - a curated catalog of MCP servers your bots can use as tools. Manage from Dashboard → MCP Hub.

Workspace ArchitectDashboard-only

The Architect is a conversational setup agent that turns a plain-English brief into a working workspace: bots, prompts, guardrails, connectors, KB connections, evolution rules, and tests. It runs at /dashboard (Architect tab) and also powers natural-language edit mode and bot cloning.

8-phase agent loop

Other architect capabilities

• Edit mode - change an existing bot with a sentence ("make it more empathetic, prefer email over phone")
• Bot cloning - duplicate a bot with modifications (industry, language, tone)
• Bot testing - architect can run tests and iterate until a readiness threshold is met
• Industry templates - 20+ starting points (SaaS support, fintech KYC, healthcare intake, etc.)
• Org profile prefill - reuses defaults you set once in your organization profile

Knowledge BaseDashboard-only

Connect your data sources to Rylvo for grounded, evidence-backed decisions. The KB system provides hybrid retrieval with 12 pre-built blueprints covering common enterprise patterns.

How it works

Built-in blueprints

Dashboard features

Conversation StorageDashboard-only

Bring Your Own Database (BYODB). Every conversation event Rylvo processes can be pushed to a database or webhook endpoint you own — so your conversations live permanently in infrastructure you control. Rylvo also maintains a time-bounded operational copy for Mission Control, traces, agent evolution, and edge-case detection. Manage from Dashboard → Conv. Storage.

Audience HubDashboard-only

The central operator workspace for managing every end-user across every bot in your organization. Replace scattered user lists with a scalable hub: paginated people browsing, saved filter segments, aggregate analytics, consent governance, CSV import/export, and retention policy controls. Manage from Dashboard → Audience.