Iris Chat

The Iris Chat API exposes Ridum's conversational AI as a stateless endpoint. Send the full message history with each request — the API does not persist conversations on your behalf.

Endpoint

POST https://iris.ridumlabs.com/api/v1/chat

Authentication

Requires a Bearer API key. See the authentication guide.

Models

Model	Description
`neo`	General-purpose conversational model with web search grounding.
`geo`	Fast conversational model with tool support and web search.

Request body

Field	Type	Description
`model`	string	Required. `neo` or `geo`.
`messages`	array	Required. Non-empty array of message objects. The last message must have role `user`.
`messages[].role`	string	`user` or `assistant`.
`messages[].content`	string	The message text.

Response

json

{
  "message": {
    "role": "assistant",
    "content": "...",
    "model": "geo"
  }
}

Examples

Single message (curl)

bash

curl https://iris.ridumlabs.com/api/v1/chat \
  -H "Authorization: Bearer rl_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "geo",
    "messages": [
      { "role": "user", "content": "What is Ridum Labs?" }
    ]
  }'

Multi-turn conversation (JavaScript)

Because the API is stateless, append the assistant's reply to your message history and send the entire conversation on the next turn.

javascript

const API_URL = "https://iris.ridumlabs.com/api/v1/chat";
const API_KEY = process.env.RIDUM_API_KEY;

async function ask(messages) {
  const res = await fetch(API_URL, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ model: "geo", messages }),
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.error);
  }

  return (await res.json()).message;
}

const history = [
  { role: "user", content: "Hello" },
];

const reply1 = await ask(history);
history.push(reply1);

history.push({ role: "user", content: "Tell me more." });
const reply2 = await ask(history);
console.log(reply2.content);

Python

python

import os
import requests

API_URL = "https://iris.ridumlabs.com/api/v1/chat"
API_KEY = os.environ["RIDUM_API_KEY"]

def ask(messages):
    res = requests.post(
        API_URL,
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"model": "geo", "messages": messages},
        timeout=60,
    )
    res.raise_for_status()
    return res.json()["message"]

history = [{"role": "user", "content": "Hello"}]
reply = ask(history)
print(reply["content"])

Rate limits

Requests are subject to upstream model capacity. If you receive a 429 or 503 response, wait a few seconds and retry with exponential backoff. Very long conversations may exceed the model token budget — keep history concise or summarize older turns client-side.

Limitations (v1)

Stateless only — client is responsible for storing message history.
No streaming responses. Each call returns the complete reply.
External integrations (Discord, Gmail, etc.) available in the Iris web app are not accessible from API requests.