Developer API Reference

Lyren API Reference for Developers

Build AI product features with Chat, always-on Memory, Tools, Knowledge Base, Business APIs, Workflows, Scheduler jobs, Calendar flows, and Connectors.

Important: POST /v1/chat/completions requires x-user-id because Developer Chat always includes Lyren Memory.

Always-on chat memory

Developer Chat automatically retrieves user-scoped memory and task context.

Standardized tools

Tools return clean result and daily cap metadata with validation and safer URL fetching.

User-scoped modules

Memory, knowledge, business, workflows, scheduler, calendar, and connectors use x-user-id.

Base URL

All public developer endpoints are relative to this base URL.

base url 
https://lyren-gateway-api.onrender.com

Authentication

Most endpoints require the x-api-key header.

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

User identity with x-user-id

Use x-user-id for user-scoped API features. Developer Chat requires it because memory is always enabled. This keeps memory, documents, jobs, connectors, and business context isolated by api_key + user_id.

http 
x-api-key: YOUR_API_KEY
x-user-id: user_123
Content-Type: application/json
Required for: /v1/chat/completions, Memory, Knowledge Base, Business, Workflows, Scheduler, Calendar, and Connectors.

GET /v1/limits

Returns plan and API limits for the current API key.

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

GET /health

Health check endpoint for confirming the API server is online.

bash 
curl https://lyren-gateway-api.onrender.com/health

POST /v1/chat/completions

Create a chat completion. Developer Chat always includes Lyren Memory, so x-user-id is required. Developers cannot disable memory. Legacy use_memory may be accepted for compatibility, but it is ignored.

bash 
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": "Continue the plan from my saved memory." }
    ],
    "temperature": 0.2,
    "max_tokens": 700,
    "memory_limit": 8,
    "task_limit": 5,
    "use_knowledge": true,
    "safe_no_context_response": true,
    "redact_output": true
  }'
json body 
{
  "model": "lyren-dev-standard",
  "messages": [
    { "role": "user", "content": "Continue the plan from my saved memory." }
  ],
  "temperature": 0.2,
  "max_tokens": 700,
  "memory_limit": 8,
  "task_limit": 5,
  "memory_project": "Lyren",
  "use_knowledge": true,
  "knowledge_top_k": 6,
  "safe_no_context_response": true,
  "redact_output": true
}
json response 
{
  "ok": true,
  "id": "chatcmpl_local_123",
  "object": "chat.completion",
  "model": "Lyren Dev Standard",
  "memory_used": true,
  "knowledge_used": false,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Here is the continuation based on the user's saved context..."
      },
      "finish_reason": "stop"
    }
  ],
  "sources": [],
  "daily_caps": {
    "kind": "chat",
    "used_today": 12,
    "limit_daily": 2500,
    "bucket_type": "user"
  },
  "meta": {
    "memory_required": true,
    "memory_always_enabled": true,
    "tasks_included_with_memory": true,
    "context_user_id_required": true,
    "used_memory": true
  }
}

Supported chat modes

text 
lyren-dev-fast
lyren-dev-standard
lyren-dev-deep

Tools API

Utility endpoints for summarizing, translating, rewriting, extracting, fetching URL text, and fetching plus summarizing. Upgraded tool routes support validation, redaction, daily cap metadata, and standardized response shapes.

routes 
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

POST /v1/tools/summarize

json 
{
  "text": "We need to ship v1 in 7 days. Backend is behind. QA has not started.",
  "redact_output": true
}

POST /v1/tools/translate

json 
{
  "text": "Hello, how are you?",
  "target_language": "Spanish",
  "redact_output": true
}

POST /v1/tools/rewrite

json 
{
  "text": "We are late on the project.",
  "style": "professional",
  "redact_output": true
}

POST /v1/tools/extract

json 
{
  "text": "Jane Doe (jane@acme.com) reported checkout error. Urgency: high.",
  "instruction": "Extract the customer name, email, issue, and urgency.",
  "redact_output": true
}

POST /v1/tools/fetch

json 
{
  "url": "https://example.com/article",
  "max_chars": 20000,
  "redact_output": true
}

POST /v1/tools/fetch_and_summarize

json 
{
  "url": "https://example.com/article",
  "max_chars": 30000,
  "redact_output": true
}

Standard tools response

json response 
{
  "ok": true,
  "plan": "growth",
  "user_id": "user_123",
  "result": {
    "summary": "The project is at risk because backend work is behind and QA has not started."
  },
  "daily_caps": {
    "kind": "tools_summarize",
    "used_today": 14,
    "limit_daily": 1500,
    "unlimited": false
  }
}

Memory API

Save, search, forget, and rank user memory. Memory is the core context layer used automatically by Developer Chat.

routes 
POST /v1/memory/save
POST /v1/memory/search
POST /v1/memory/forget
POST /v1/memory/task/save
POST /v1/memory/task/search
POST /v1/memory/ranked-context

POST /v1/memory/save

bash 
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 short answers and direct implementation steps.",
    "tags": "preferences,style",
    "memory_type": "note",
    "category": "preferences",
    "project": "Lyren",
    "importance": 8,
    "pinned": true
  }'

POST /v1/memory/search

json 
{
  "query": "How does the user like responses formatted?",
  "limit": 5,
  "ranked": true
}

POST /v1/memory/forget

json 
{
  "id": 42
}

POST /v1/memory/task/save

json 
{
  "title": "Finish API docs",
  "description": "Rewrite docs to match upgraded developer routes.",
  "project": "Lyren",
  "tags": "docs,api",
  "status": "open",
  "priority": 8,
  "pinned": true
}

POST /v1/memory/task/search

json 
{
  "query": "docs tasks",
  "limit": 5,
  "ranked": true
}

POST /v1/memory/ranked-context

json 
{
  "query": "continue the API reference rewrite",
  "memory_limit": 8,
  "task_limit": 5,
  "include_tasks": true,
  "project": "Lyren"
}

Knowledge Base API

Upload documents and ask grounded questions. Knowledge Base is user-scoped and requires x-user-id.

routes 
POST /v1/knowledge/upload
POST /v1/knowledge/ask

POST /v1/knowledge/upload

bash 
curl -X POST https://lyren-gateway-api.onrender.com/v1/knowledge/upload \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-id: user_123" \
  -F "file=@./policy.pdf"

POST /v1/knowledge/ask

json 
{
  "question": "Summarize our refund policy and list exceptions.",
  "top_k": 6,
  "redact_output": true
}

Knowledge answer response

json response 
{
  "ok": true,
  "result": {
    "answer": "The refund policy allows refunds within 30 days, with exceptions...",
    "sources": [
      {
        "doc_id": "kb_abc123",
        "chunk_index": 2,
        "score": 0.92,
        "source_name": "policy.pdf",
        "mime": "application/pdf"
      }
    ]
  },
  "daily_caps": {
    "kind": "knowledge_ask",
    "used_today": 4,
    "limit_daily": 100
  }
}

Business API

Business routes provide structured scoring and analysis for dashboards, CRM products, SaaS apps, and internal tools.

routes 
POST /v1/business/lead-score
POST /v1/business/churn-risk
POST /v1/business/revenue-leaks
GET  /v1/business/history

POST /v1/business/lead-score

json 
{
  "budget_usd": 5000,
  "company_size": 120,
  "timeline_days": 14,
  "stage": "proposal",
  "source": "inbound",
  "engagement": {
    "email_opens": 4,
    "email_replies": 1,
    "meetings": 1,
    "site_visits": 6,
    "demo_requested": true
  }
}

POST /v1/business/churn-risk

json 
{
  "usage_last_30d": [12, 11, 10, 10, 9, 8, 7],
  "tickets_last_30d": 3,
  "refunds_last_90d": 1,
  "failed_payments_last_30d": 2,
  "last_active_days": 18,
  "nps": 3
}

POST /v1/business/revenue-leaks

json 
{
  "currency": "USD",
  "events": [
    { "type": "refund", "amount": 39.99 },
    { "type": "failed_payment", "amount": 49.00 },
    { "type": "chargeback", "amount": 99.00 },
    { "type": "cancellation", "mrr": 49.00 },
    { "type": "downgrade", "mrr_delta": -30.00 }
  ]
}

GET /v1/business/history

bash 
curl https://lyren-gateway-api.onrender.com/v1/business/history \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-id: user_123"

Workflows API

Save and list reusable workflow definitions for a user.

routes 
POST /v1/workflows/save
GET  /v1/workflows/list

POST /v1/workflows/save

json 
{
  "name": "sales_followup",
  "definition": {
    "steps": [
      { "type": "rewrite", "style": "professional" },
      { "type": "extract", "instruction": "Extract action items." }
    ]
  }
}

GET /v1/workflows/list

bash 
curl https://lyren-gateway-api.onrender.com/v1/workflows/list \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-id: user_123"

Scheduler API

Create, list, inspect, and cancel scheduled jobs for the current user.

routes 
POST /v1/schedule/create
GET  /v1/schedule/list
GET  /v1/schedule/status/{job_id}
POST /v1/schedule/cancel/{job_id}

POST /v1/schedule/create

json 
{
  "run_at": "2026-03-20T18:30:00Z",
  "job_type": "webhook",
  "payload": {
    "webhook_url": "https://yourapp.com/hooks/reminder",
    "body": {
      "message": "Follow up with the lead."
    }
  }
}

GET /v1/schedule/list

bash 
curl https://lyren-gateway-api.onrender.com/v1/schedule/list \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-id: user_123"

GET /v1/schedule/status/{job_id}

bash 
curl https://lyren-gateway-api.onrender.com/v1/schedule/status/JOB_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-id: user_123"

POST /v1/schedule/cancel/{job_id}

bash 
curl -X POST https://lyren-gateway-api.onrender.com/v1/schedule/cancel/JOB_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-id: user_123"

Calendar API

Calendar routes are user-scoped and should be shown when enabled in your deployed backend.

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

POST /v1/calendar/book

json 
{
  "title": "SEO Audit Call",
  "starts_at": "2026-03-20T18:30:00Z",
  "ends_at": "2026-03-20T19:00:00Z",
  "timezone": "America/New_York",
  "attendee_name": "Jane Doe",
  "attendee_email": "jane@example.com",
  "webhook_url": "https://yourapp.com/hooks/calendar"
}

Connectors API

Connectors store user-scoped source configurations such as sitemap, website, RSS, docs, API, webhook, and custom connectors.

routes 
POST /v1/connectors/create
GET  /v1/connectors/list

POST /v1/connectors/create

json 
{
  "name": "Main Sitemap",
  "kind": "sitemap",
  "config": {
    "url": "https://example.com/sitemap.xml"
  }
}

GET /v1/connectors/list

bash 
curl https://lyren-gateway-api.onrender.com/v1/connectors/list \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-id: user_123"
Allowed kinds: sitemap, website, rss, docs, api, webhook, custom.

Portal endpoints

Portal endpoints belong to the developer portal service, not the public /v1 API modules.

routes 
POST /api/auth/signup
POST /api/auth/login
POST /api/auth/logout
GET  /api/me
GET  /api/keys/me
POST /api/keys/regenerate
POST /api/billing/checkout
POST /api/billing/portal
POST /api/billing/webhook
POST /api/auth/forgot-password
POST /api/auth/reset-password

Errors

Lyren returns JSON errors with predictable fields.

json 
{
  "error": "missing_user_id",
  "message": "x-user-id is required for /v1/chat/completions because Developer Chat always includes memory."
}
common errors 
unauthorized
forbidden
invalid_request
missing_user_id
rate_limit_exceeded
daily_cap_exceeded
tool_execution_failed
url_fetch_failed
chat_model_request_failed
safety_blocked
safety_cooldown

Frequently Asked Questions

Common questions about Lyren API authentication, always-on chat memory, tools, user identity, limits, and developer modules.

What is the Lyren API Reference?

The Lyren API Reference is the developer documentation page for public Lyren API routes, authentication, user identity, chat, tools, memory, knowledge base, business, workflows, scheduler, calendar, and connectors.

What is the base URL for Lyren API?

The Lyren API base URL is https://lyren-gateway-api.onrender.com.

How do I authenticate requests to Lyren API?

Send your API key in the x-api-key header. JSON requests should also include Content-Type: application/json.

Is x-user-id required for Lyren Developer Chat?

Yes. Developer Chat always includes Lyren Memory, so x-user-id is required for POST /v1/chat/completions. Memory is scoped by api_key + user_id.

Can developers disable memory in chat completions?

No. Developer Chat always includes memory. Legacy request fields such as use_memory may be accepted for compatibility, but memory remains enabled.

What chat models are available?

The public developer chat modes are lyren-dev-fast, lyren-dev-standard, and lyren-dev-deep.

What can the Tools API do?

The Tools API can summarize, translate, rewrite, extract information, fetch URL text, and fetch plus summarize URL content. Tool responses use standardized result and daily cap metadata.

What is Lyren Memory?

Lyren Memory stores user-scoped notes, preferences, project facts, and task context so AI features can respond with continuity across sessions.

What is the Knowledge Base API?

The Knowledge Base API lets developers upload documents and ask grounded questions against a user’s uploaded files.

What business APIs are included?

Lyren includes business routes for lead scoring, churn risk, revenue leak analysis, and business history when enabled in the backend.

What are workflows and scheduler routes for?

Workflows store reusable automation definitions. Scheduler routes create, list, inspect, and cancel scheduled jobs such as webhook actions and reminders.

What are connectors in Lyren API?

Connectors store user-scoped source configurations such as sitemap, website, RSS, docs, API, webhook, and custom connectors.

What does a standard successful response include?

Many upgraded Lyren routes return ok, result, meta, and daily_caps fields so developers can parse responses consistently.

What does an error response look like?

Lyren returns JSON errors with fields such as error and message. Common errors include unauthorized, forbidden, invalid request, rate limit exceeded, daily cap exceeded, missing user ID, and backend failure.