Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lucid.foundation/llms.txt

Use this file to discover all available pages before exploring further.

Lucid routes messages between users and agents across multiple communication channels. All channel interactions flow through Lucid’s webhook infrastructure, ensuring every message generates a verifiable receipt.

​
Architecture

User (Telegram/Discord/Slack)
  -> Messaging platform webhook
  -> api.lucid.foundation/v1/webhooks/:provider
  -> Agent runtime (port 3100)
  -> Response
  -> Routed back to channel

​
Channel Routing Flow

When a message arrives from any channel:
  1. Webhook reception — Lucid receives the platform webhook at /v1/webhooks/:provider
  2. Identity resolution — Maps the platform user to a Lucid user (auto-provisioned if Telegram-only)
  3. Agent binding — Looks up which agent is bound to this chat/channel
  4. Message forwarding — Sends the message to the agent’s runtime
  5. Receipt creation — Every interaction produces a cryptographic receipt
  6. Response routing — Agent’s response is sent back to the originating channel

​
Telegram

The deepest integration. Users can deploy and manage agents entirely from Telegram.

​
Bot Commands

CommandDescription
/launch [slug]Interactive agent deployment wizard
/start <passport_id>Bind a chat to an existing agent
/statusCheck agent health
/listList deployed agents
/planView current plan and usage
/upgradeUpgrade plan via Stripe

​
User Provisioning

Telegram-only users are auto-provisioned: the create_telegram_user() database function creates a profile, organization, and free plan in a single transaction. Web users link their Telegram via a deep link from the dashboard (t.me/bot?start=link_TOKEN).

​
Billing Gate

Before deploying, checkLaunchAllowed() verifies the user’s plan permits additional agents:
PlanAgent Limit
Starter1
Professional10
BusinessUnlimited
InternalUnlimited

​
Discord and Slack

Bring your own bot token. Configure via environment variables at launch time: 
# Discord
DISCORD_BOT_TOKEN=your-discord-bot-token

# Slack
SLACK_BOT_TOKEN=xoxb-your-slack-token
Messages from these platforms are received via provider-specific webhook endpoints, then forwarded to the bound agent.

​
HTTP (Direct API)

Agents are always accessible via their HTTP endpoint, independent of any messaging channel: 
curl -X POST https://api.lucid.foundation/v1/chat/completions \
  -H "Authorization: Bearer lk_..." \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'