URBot Developer API — Documentation

Authentication

All API requests require an API key passed via the X-API-Key header. Get your key from the API Keys page in your account.

Header

X-API-Key: your_api_key_here

Keep your key secret. Do not expose API keys in client-side JavaScript, public repositories, or URL parameters. Use server-side requests or environment variables.

Base URL

Each bot has its own subdomain. Replace professor with any bot slug to target that bot:

Base URL

https://professor.urbot.net/api/

-- Examples:
https://medic.urbot.net/api/       -- Medical bot
https://chef.urbot.net/api/        -- Culinary bot
https://legal.urbot.net/api/       -- Legal bot
https://blender.urbot.net/api/     -- 3D Modeling bot
https://unreal.urbot.net/api/      -- Game Dev bot

The main domain https://urbot.net/api/ handles cross-bot operations like product listings, checkout, and account management.

Rate Limits

Tier	Requests / Minute	Chat Messages / Hour	How to Get
Free	100	30 per bot	Sign up at /api-keys/
Pro	1,000	999 per bot	Purchase any bot (Professional tier)

When you exceed your rate limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

Endpoints

POST /api/chat Send a message to a bot and get a response

This is the primary endpoint for interacting with any URBot. Send a user message and receive the bot's AI-generated reply, along with optional emotion and suggestion data.

Request Body

Parameter	Type	Description
messagerequired	string	The user's message text
conversation_idoptional	string	Existing conversation ID to continue a thread. Omit to start a new conversation.

curl

curl -X POST https://professor.urbot.net/api/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "message": "Explain quantum entanglement in simple terms",
    "conversation_id": "conv_abc123"
  }'

Response

200 OK

{
  "reply": "Quantum entanglement is when two particles become linked...",
  "conversation_id": "conv_abc123",
  "emotion": "thinking",
  "userEmotion": "neutral",
  "suggestion": null
}

Field	Type	Description
reply	string	The bot's response text
conversation_id	string	The conversation ID (reuse to continue the thread)
emotion	string \| null	Bot's emotional state: `neutral`, `happy`, `excited`, `thinking`, `concerned`, `empathetic`, `proud`, `idea`
userEmotion	string \| null	Detected user emotion from message text
suggestion	object \| null	Evidence-backed idea suggestion (when applicable). Contains `text`, `evidence`, `confidence`.

GET /api/products List all bots with pricing

Returns the full catalog of available bots with their names, descriptions, categories, and price tiers. No authentication required.

curl

curl https://urbot.net/api/products

Response

200 OK

{
  "products": [
    {
      "id": 1,
      "bot_slug": "professor",
      "name": "Professor",
      "description": "AI education expert...",
      "category": "education",
      "tiers": [
        { "tier": "starter", "price_cents": 100 },
        { "tier": "full", "price_cents": 300 },
        { "tier": "professional", "price_cents": 500 }
      ]
    },
    // ... 136 more bots
  ],
  "total": 137
}

GET /api/products?bot_slug=professor Get info for a single bot

Filter the product list to a single bot by slug. Useful for displaying pricing on individual bot pages.

curl

curl https://urbot.net/api/products?bot_slug=medic

Response

200 OK

{
  "products": [
    {
      "bot_slug": "medic",
      "name": "Medic",
      "description": "AI health and medical information expert...",
      "category": "health",
      "tiers": [
        { "tier": "starter", "price_cents": 100 },
        { "tier": "full", "price_cents": 300 },
        { "tier": "professional", "price_cents": 500 }
      ]
    }
  ],
  "total": 1
}

POST /api/checkout Create a Stripe checkout session

Creates a Stripe Checkout session for purchasing a bot. Returns a URL to redirect the user to Stripe's hosted payment page. After successful payment, the user is redirected back to your success_url (or the bot's download page by default).

Request Body

Parameter	Type	Description
bot_slugrequired	string	The bot slug (e.g., `professor`, `medic`)
tierrequired	string	Pricing tier: `starter`, `full`, or `professional`
emailrequired	string	Customer email address (used for receipt and account linking)

curl

curl -X POST https://urbot.net/api/checkout \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "bot_slug": "professor",
    "tier": "professional",
    "email": "user@example.com"
  }'

Response

200 OK

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_...",
  "session_id": "cs_live_a1b2c3..."
}

Redirect the user to the url to complete payment.

GET /api/memories/:conversation_id Get bot memories for a conversation

Retrieves the memory context that the bot has accumulated during a conversation. Requires authentication. Only the owner of the conversation can access its memories.

curl

curl https://professor.urbot.net/api/memories/conv_abc123 \
  -H "X-API-Key: your_api_key_here"

Response

200 OK

{
  "conversation_id": "conv_abc123",
  "bot_slug": "professor",
  "memories": [
    {
      "key": "user_interest",
      "value": "quantum physics",
      "created_at": "2026-04-01T14:30:00Z"
    }
  ],
  "count": 1
}

POST /api/signup Newsletter signup

Subscribe an email address to the URBot newsletter. No authentication required. Duplicate emails are silently accepted (idempotent).

Request Body

Parameter	Type	Description
emailrequired	string	Email address to subscribe
sourceoptional	string	Where the signup came from (e.g., `"homepage"`, `"builder"`, `"api"`)

curl

curl -X POST https://urbot.net/api/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "source": "api"
  }'

Response

200 OK

{
  "success": true,
  "message": "Subscribed successfully"
}

SDKs

We provide official SDK libraries for JavaScript and Python to simplify integration.

JavaScript

Include the SDK via a script tag or import it in your bundler:

HTML

<!-- Script tag -->
<script src="https://urbot.net/sdk/urbot.js"></script>

<!-- Usage -->
<script>
  const bot = new URBot('professor', { apiKey: 'your_key' });
  const reply = await bot.chat('What is photosynthesis?');
  console.log(reply.text);
</script>

Python

# Install
pip install urbot

# Usage
from urbot import URBot

bot = URBot("professor", api_key="your_key")
reply = bot.chat("What is photosynthesis?")
print(reply.text)

MCP Protocol

URBot supports the Model Context Protocol (MCP), enabling integration with MCP-compatible AI tools and agents.

Property	Value
Endpoint	`/api/mcp`
Protocol	JSON-RPC 2.0
Version	`2024-11-05`
Transport	HTTP + SSE (Server-Sent Events)

Available MCP Tools (5)

Tool	Description
chat	Send a message to the bot and receive a response
list_bots	List all available bots with descriptions
get_memories	Retrieve bot memories for a conversation
search_knowledge	Search a bot's knowledge base by topic
get_bot_info	Get detailed info about a specific bot

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "chat",
    "arguments": {
      "message": "Explain the Krebs cycle"
    }
  }
}

Embed Widget

Add a URBot chat widget to any website with a single line of HTML. The widget loads asynchronously and does not block your page rendering.

HTML

<!-- One-line embed: adds a floating chat button -->
<script
  src="https://urbot.net/embed/urbot-embed.js"
  data-bot="professor"
></script>

Configuration Attributes

Attribute	Default	Description
data-bot	required	Bot slug (e.g., `professor`, `medic`, `chef`)
data-theme	`"dark"`	Widget color theme: `dark`, `light`, or `auto`
data-position	`"bottom-right"`	Widget position: `bottom-right`, `bottom-left`
data-greeting	Bot default	Custom greeting message shown when widget opens
data-api-key	none	Your API key (enables higher rate limits for embed users)

Full Example

<script
  src="https://urbot.net/embed/urbot-embed.js"
  data-bot="chef"
  data-theme="light"
  data-position="bottom-left"
  data-greeting="What should we cook today?"
></script>

Attribution: Embeds include a small "Powered by URBot" link. This is required under the API & Developer Terms.

Webhooks

Configure webhook endpoints at /api-keys/ to receive real-time event notifications. Webhooks are delivered as HTTP POST requests with a JSON body. Each request includes an X-URBot-Signature header for verification.

Available Events

Event	Fired When
`purchase.completed`	A customer completes a purchase (Stripe checkout finishes)
`chat.message`	A message is sent to one of your embedded bots (opt-in only)

Webhook Payload

{
  "event": "purchase.completed",
  "timestamp": "2026-04-01T18:00:00Z",
  "data": {
    "bot_slug": "professor",
    "tier": "professional",
    "email": "user@example.com",
    "amount_cents": 500
  }
}

Verify signatures. Always verify the X-URBot-Signature header before processing webhook events. Unverified webhooks could be spoofed by a third party.

Error Codes

The API uses standard HTTP status codes. Error responses include a JSON body with an error field describing the issue.

Code	Meaning	Common Cause
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Missing required field, invalid JSON, or bad parameter value
401	Unauthorized	Missing or invalid API key
403	Forbidden	Valid API key but insufficient permissions for this resource
404	Not Found	Bot slug does not exist, or resource ID not found
429	Rate Limited	Too many requests. Check `Retry-After` header.
500	Internal Error	Something went wrong on our end. Try again or contact support.

Error Response

{
  "error": "Invalid bot_slug: 'nonexistent' not found",
  "status": 404
}