Open API

Reverie exposes an OpenAI-compatible Chat Completions endpoint. Point any OpenAI client at it, pass a Reverie API key, and use the model field to name a character or scenario instead of an LLM. Reverie keeps the conversation, the memories and the summaries on its side, so each request only needs your new message.

Any signed-in account can use it. There is no subscription tier, waitlist or feature switch involved — you need an API key, and that's all. Create one →

Base URL and auth

https://www.reverie.im/api/device/v1
Authorization: Bearer rk_...

Settings → More → API Keys shows the exact base URL for your deployment in the API Endpoint card, with a copy button.

Quick start

curl --no-buffer https://www.reverie.im/api/device/v1/chat/completions \
  -H "Authorization: Bearer $REVERIE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary '{
  "model": "Luna [abc12345]",
  "messages": [
    {
      "role": "user",
      "content": "Hi"
    }
  ],
  "stream": true,
  "temperature": 0.8
}'

Settings → More → API Keys also has a request builder that generates these three snippets against one of your real keys and a real character.

The model field names a character

Details that decide whether a short ID resolves:

• The [...] must be at the end of the string.
• A suffix of 8 characters or fewer is matched only against characters you already have a chat with, on the web or through the API. A short ID for a character you have never opened falls through silently.
• The scenario lookup only runs when the key is pinned to a character. With a global key, a short scenario ID can never resolve.
• More than 8 characters is treated as a full ID.

Listing what you can talk to

curl https://www.reverie.im/api/device/v1/models \
  -H "Authorization: Bearer $REVERIE_API_KEY"

A global key returns your recent characters. A key pinned to a character returns that character's scenarios instead, or the character itself if it has none. Each entry looks like:

{
	"id": "Luna [abc12345]",
	"object": "model",
	"created": 1759200000,
	"owned_by": "character",
	"permission": [],
	"root": "<full character id>",
	"parent": null
}

Copy id straight into model. Errors from this endpoint use a plain error shape rather than the OpenAI envelope.

What the request body reads

Four fields are read. Everything else is accepted and silently discarded.

Ignored without warning: max_tokens, top_p, n, stop, presence_penalty, frequency_penalty, logit_bias, seed, user, response_format, tools, tool_choice, logprobs, stream_options.

How messages is handled:

• system messages are dropped. Persona and behaviour come from the character's own fields, not from the request. Prompt fields →
• There is no vision support. Content may be a string or a parts array, but only text parts are read; image parts are ignored.
• Only the last user message is added to the conversation. Earlier user messages are ignored.
• Assistant messages are used only for history sync (below).
• An empty or whitespace-only last user message returns missing_user_message.

Responses

A non-streaming response is a normal chat.completion object. finish_reason is always stop — internal tool calls are never exposed — and the usage counters are zeros, so measure tokens from the usage statistics on the API keys page rather than from the response.

A streaming response is text/event-stream:

1. Content chunks: chat.completion.chunk objects with delta.content. No initial delta: {"role": "assistant"} chunk is sent.
2. A finish chunk, with finish_reason of stop, length or content_filter. Tool-call finishes are reported as stop.
3. A usage chunk with an empty choices array.
4. data: [DONE].

If generation fails mid-stream, the stream emits data: {"error": {...}} and then [DONE].

Conversation state

Reverie stores the conversation. One chat exists per key-and-character pair, it shows up in the web app alongside your other chats, and each turn is built from the character's system prompt and scenario, world book canon, long-term memories, rolling summaries, the character's narration style, response length and NSFW settings, a language lock from your account locale, and up to the last 250 messages, trimmed to the model's context window. Memory tools run when the model supports tools.

Because the server holds the history, you do not need to replay it.

Which LLM answers

The character decides, not the request — unless you name an LLM. Precedence, lowest to highest: the default chat model, then the character's own model setting, then a Reverie model ID passed as model, and finally the per-chat model preference you set in the web app, which wins over all of them. Models →

Errors

Errors from /chat/completions use the OpenAI envelope: {"error": {"message", "type", "param": null, "code"}}.

Two cases fall outside that envelope: GET /models errors, and request bodies rejected by validation (an out-of-range temperature, for example) — both return a plain error shape.

Rate limits and quotas

There is no per-key rate limit, no concurrency cap and no request quota on this API. Two things bound your usage:

The free-model window is shared with web chat, stories, novels and the bots — it is one allowance per account, not one per surface. Free models →

Reverie sends no outbound webhooks; there is nothing to subscribe to for completion events.

Importing characters

A second endpoint, POST /api/v1/characters/import, creates a character from a character card. It needs a key with the import scope, which is not the kind of key the settings page creates. API keys → and Import characters →

Related

• API keys — create, pin, expire and monitor keys
• Models — model IDs and credit multipliers
• Limits — the other ceilings in the product
• Credits — how requests are priced