Lyren Docs for Developers

Overview

Lyren runs as an HTTP API gateway. Your backend calls Lyren using x-api-key. User-scoped features use x-user-id. Developer Chat always uses Memory, so it also requires x-user-id.

Getting started

Start with the public base URL, your API key, and a stable user ID from your application.

Install

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

Python quickstart

Use an HTTP client such as httpx.

pip install httpx

export LYREN_BASE_URL="https://lyren-gateway-api.onrender.com"
export LYREN_API_KEY="YOUR_API_KEY"
export LYREN_USER_ID="user_123"

import os
import httpx

BASE = os.getenv("LYREN_BASE_URL", "https://lyren-gateway-api.onrender.com").rstrip("/")
KEY = os.getenv("LYREN_API_KEY", "")
USER_ID = os.getenv("LYREN_USER_ID", "user_123")

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

def chat(prompt: str):
    response = httpx.post(
        f"{BASE}/v1/chat/completions",
        headers=headers(user_scoped=True),
        json={
            "model": "lyren-dev-standard",
            "messages": [
                {"role": "user", "content": prompt}
            ],
            "memory_limit": 8,
            "task_limit": 5,
            "redact_output": True
        },
        timeout=45
    )
    response.raise_for_status()
    return response.json()

if __name__ == "__main__":
    result = chat("Say hello from Lyren and remember this user context.")
    print(result["choices"][0]["message"]["content"])

Node.js quickstart

Node 18+ includes fetch.

export LYREN_BASE_URL="https://lyren-gateway-api.onrender.com"
export LYREN_API_KEY="YOUR_API_KEY"
export LYREN_USER_ID="user_123"

const BASE = (process.env.LYREN_BASE_URL || "https://lyren-gateway-api.onrender.com").replace(/\/+$/, "");
const KEY = process.env.LYREN_API_KEY || "";
const USER_ID = process.env.LYREN_USER_ID || "user_123";

function headers(userScoped = true) {
  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 response = await fetch(`${BASE}/v1/chat/completions`, {
    method: "POST",
    headers: headers(true),
    body: JSON.stringify({
      model: "lyren-dev-standard",
      messages: [
        { role: "user", content: prompt }
      ],
      memory_limit: 8,
      task_limit: 5,
      redact_output: true
    })
  });

  if (!response.ok) {
    throw new Error(await response.text());
  }

  return response.json();
}

(async () => {
  const result = await chat("Say hello from Lyren and use my saved memory.");
  console.log(result.choices[0].message.content);
})();

cURL quickstart

Use cURL for quick testing.

curl -X POST https://lyren-gateway-api.onrender.com/v1/chat/completions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-id: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lyren-dev-standard",
    "messages": [
      { "role": "user", "content": "Write 3 bullets about what Lyren can do." }
    ],
    "memory_limit": 8,
    "task_limit": 5,
    "redact_output": true
  }'

Quickstart flow

1. Store your API key server-side.
2. Set LYREN_BASE_URL to https://lyren-gateway-api.onrender.com.
3. Pass x-api-key with every protected request.
4. Pass x-user-id for Developer Chat and user-scoped modules.
5. Call POST /v1/chat/completions with lyren-dev-standard.
6. Use API Reference for exact request and response details.

curl -X POST https://lyren-gateway-api.onrender.com/v1/memory/save \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-id: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers concise answers and implementation steps.",
    "tags": "preferences,formatting,style",
    "memory_type": "note",
    "category": "preferences",
    "project": "Lyren",
    "importance": 8,
    "pinned": true
  }'

Authentication

Protected Lyren API requests use your API key in the x-api-key header.

x-api-key: YOUR_API_KEY
Content-Type: application/json

User identity headers

Send a stable x-user-id to keep user-scoped data isolated. Developer Chat requires it because memory is always enabled.

x-api-key: YOUR_API_KEY
x-user-id: user_123
Content-Type: application/json

Security checklist

• Store API keys in backend environment variables.
• Never expose keys in frontend JavaScript.
• Use x-user-id for user-scoped routes.
• Regenerate exposed keys immediately.
• Use redact_output where available.
• Use server-side proxies for browser-facing apps.

Chat

Use Chat for product assistants, support copilots, drafting, explanation, planning, and user-aware experiences. Developer Chat always includes Lyren Memory, so every chat completion is scoped to a user.

Tools

Tools provide utility actions such as summarize, translate, rewrite, extract, URL fetch, and fetch plus summarize. Upgraded tools support safer validation, optional redaction, max character controls, metadata, and daily cap details.

• POST /v1/tools/summarize
• POST /v1/tools/translate
• POST /v1/tools/rewrite
• POST /v1/tools/extract
• POST /v1/tools/fetch
• POST /v1/tools/fetch_and_summarize

Memory

Memory stores user preferences, project facts, long-term notes, and task context. Developer Chat automatically uses ranked memory and task context.

• POST /v1/memory/save — save user memory
• POST /v1/memory/search — search user memory
• POST /v1/memory/forget — delete memory
• POST /v1/memory/task/save — save task memory
• POST /v1/memory/task/search — search task memory
• POST /v1/memory/ranked-context — retrieve ranked context

Knowledge Base

Knowledge Base lets developers upload documents and ask grounded questions from those documents. It is user-scoped and requires x-user-id.

• POST /v1/knowledge/upload — upload a document
• POST /v1/knowledge/ask — ask document-grounded questions

Business

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

Workflows

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

• POST /v1/workflows/save — save or update workflow definition
• GET /v1/workflows/list — list workflow definitions

Scheduler

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

• POST /v1/schedule/create — create a scheduled job
• GET /v1/schedule/list — list scheduled jobs
• GET /v1/schedule/status/{job_id} — inspect a job
• POST /v1/schedule/cancel/{job_id} — cancel a job

Calendar

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

• GET /v1/calendar/providers
• POST /v1/calendar/freebusy
• POST /v1/calendar/create-event
• POST /v1/calendar/book

Connectors

Connectors let developers store and manage user-scoped source configurations such as sitemaps, websites, RSS feeds, docs, APIs, webhooks, and custom sources.

• POST /v1/connectors/create — create connector
• GET /v1/connectors/list — list connectors

Models

Developer Chat supports these public chat modes:

• lyren-dev-fast — concise and fast responses
• lyren-dev-standard — balanced default mode
• lyren-dev-deep — deeper reasoning and implementation detail

Response shape

Many upgraded Lyren routes return consistent fields so developers can parse responses more easily.

{
  "ok": true,
  "result": {},
  "meta": {},
  "daily_caps": {
    "kind": "chat",
    "used_today": 12,
    "limit_daily": 2500,
    "remaining_today": 2488
  }
}

Errors

Errors return an HTTP status plus a JSON body.

{
  "error": "missing_user_id",
  "message": "x-user-id is required for /v1/chat/completions because Developer Chat always includes memory."
}

• 401 — missing or invalid API key
• 400 — invalid request or missing user ID
• 403 — feature not allowed for plan
• 429 — rate limit or daily cap exceeded
• 502 — backend model/tool failure

Limits

Limits are plan-based. Use GET /v1/limits to check the current plan and limits for your API key.

curl https://lyren-gateway-api.onrender.com/v1/limits \
  -H "x-api-key: YOUR_API_KEY"