Lyren Docs for Developers

Overview

Lyren runs as an HTTP gateway. Your backend calls Lyren using x-api-key. User-scoped features also use x-user-id.

Getting started

Call Lyren from your backend over HTTPS. Every request includes x-api-key. For user-scoped features, also include x-user-id.

Install

Lyren is an HTTP API. Store your credentials in environment variables and send requests from your backend.

Install (Python)

Use an HTTP client such as httpx.

pip install httpx

export LYREN_BASE_URL="https://YOUR_DOMAIN"
export LYREN_API_KEY="YOUR_API_KEY"
export LYREN_USER_ID="user_123"

import os
import httpx

BASE = os.getenv("LYREN_BASE_URL", "").rstrip("/")
KEY = os.getenv("LYREN_API_KEY", "")
USER_ID = os.getenv("LYREN_USER_ID", "user_123")

def headers(user_scoped: bool = False):
    h = {"x-api-key": KEY, "Content-Type": "application/json"}
    if user_scoped:
        h["x-user-id"] = USER_ID
    return h

def chat(prompt: str):
    r = httpx.post(
        f"{BASE}/v1/chat/completions",
        headers=headers(False),
        json={
            "model": "lyren",
            "messages": [{"role": "user", "content": prompt}],
            "temperature": 0.4,
            "max_tokens": 350
        },
        timeout=30
    )
    r.raise_for_status()
    return r.json()

if __name__ == "__main__":
    res = chat("Say hello from Lyren.")
    print(res["choices"][0]["message"]["content"])

Install (Node.js)

Node 18+ includes fetch.

export LYREN_BASE_URL="https://YOUR_DOMAIN"
export LYREN_API_KEY="YOUR_API_KEY"
export LYREN_USER_ID="user_123"

const BASE = (process.env.LYREN_BASE_URL || "").replace(/\/+$/, "");
const KEY = process.env.LYREN_API_KEY || "";
const USER_ID = process.env.LYREN_USER_ID || "user_123";

function headers(userScoped = false) {
  const h = { "x-api-key": KEY, "Content-Type": "application/json" };
  if (userScoped) h["x-user-id"] = USER_ID;
  return h;
}

async function chat(prompt) {
  const r = await fetch(`${BASE}/v1/chat/completions`, {
    method: "POST",
    headers: headers(false),
    body: JSON.stringify({
      model: "lyren",
      messages: [{ role: "user", content: prompt }],
      temperature: 0.4,
      max_tokens: 350
    })
  });

  if (!r.ok) throw new Error(await r.text());
  return r.json();
}

(async () => {
  const res = await chat("Say hello from Lyren.");
  console.log(res.choices[0].message.content);
})();

Install (cURL)

Use cURL for quick testing.

curl -X POST https://YOUR_DOMAIN/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "model": "lyren",
    "messages": [{ "role": "user", "content": "Write 3 bullets about what Lyren can do." }],
    "temperature": 0.4,
    "max_tokens": 220
  }'

Quickstart

1. Send a request to POST /v1/chat/completions
2. Add x-user-id for user-scoped features
3. Use API reference for exact request and response details

curl -X POST https://YOUR_DOMAIN/v1/memory/save \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-id: user_123" \
  -d '{
    "content": "User prefers concise answers and bullet points.",
    "tags": "preferences,formatting,style"
  }'

Authentication

Every request uses your API key in the x-api-key header.

User identity headers

Memory, Knowledge Base, Business, Workflows, Scheduler, Calendar, and Connectors can be tied to a user. Pass a stable application user id through x-user-id.

Chat

Use Chat for question answering, drafting, explanation, planning, and general assistant behavior in your product.

Tools

Tools provide consistent utility actions such as summarize, translate, rewrite, extract, fetch, and fetch plus summarize.

Memory

Memory stores user preferences and long-term facts. It is user-scoped with /v1/memory/save, /v1/memory/search, and /v1/memory/forget.

Knowledge Base

Upload documents and ask grounded questions from those documents. See the exact developer endpoints in API reference.

Business

Business endpoints return structured insights from your own data, such as lead scoring, churn risk, and revenue leak analysis.

Workflows

Workflows let developers save reusable multi-step definitions for repeated actions inside their apps.

Scheduler

Scheduler lets developers create jobs that run later, such as reminders, follow-ups, and webhook actions.

Calendar

Calendar features support scheduling-related actions such as free/busy lookup, event creation, and booking flows.

Connectors

Connectors let developers store and manage source configurations such as sitemaps, RSS feeds, URL lists, and similar ingestion sources.

Models

The default model name used in examples is lyren.

Errors

Errors return an HTTP status plus a JSON body such as { "error": "...", "message": "..." }.

Limits

Limits are plan-based. When exceeded, the API commonly returns 429.