Rylvo API Reference

curl -X POST https://api.rylvo.com/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."
  }'

X-API-Key: rylvo_sk_live_abc123...

{
  "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."
}

{
  "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"
}

{
  "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"
}

{
  "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"
  }
}

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}}

{
  "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."
}

import requests

response = requests.post(
    "https://api.rylvo.com/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']}")

const response = await fetch("https://api.rylvo.com/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);

// Create a prompt via the Rylvo dashboard Firestore SDK
import { createPrompt } from "@/lib/db/prompts";

const { promptId } = await createPrompt(orgId, userId, {
  name: "Support Triage System Prompt",
  description: "Main system prompt for the support triage bot",
  agentCategory: "response_composer",
  content: "You are a support agent for {{company_name}}...\n\nRespond in {{language}}.",
  placeholders: [
    { key: "company_name", label: "Company", description: "Customer company", defaultValue: "Acme", required: true },
    { key: "language", label: "Language", description: "Response language", defaultValue: "English", required: false },
  ],
  botId: "bot_abc123",
  botName: "Support Bot",
  tags: ["support", "triage"],
});

console.log("Created prompt:", promptId);

// Enable self-improving optimization
import { updateOptimizationConfig } from "@/lib/db/prompts";

await updateOptimizationConfig(orgId, promptId, {
  enabled: true,
  strategy: "opro",
  evaluationMetric: "success_rate",
  runFrequency: "daily",
  autoPromote: false,
});

// Manually trigger optimization
import { runOptimization } from "@/lib/services/promptOptimizer";

const result = await runOptimization(orgId, promptId, userId);
console.log("Improved:", result.improved);
console.log("Best score:", result.bestVariantScore);
console.log("Current score:", result.currentScore);

curl -X POST https://api.rylvo.com/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" }
  }'

from core.connectors.sdk import ConnectorSDK

sdk = ConnectorSDK(base_url="https://api.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")

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"])