5 min read

Quick Start

Go from zero to a working AI conversation in four steps. By the end of this guide you will have created an account, generated an API key, built a REPLR, and sent your first message.

Base URL

https://api.replr.ai/v1

Prerequisites

curl, Node.js, or Python 3.8+ installed
A terminal or API client (Postman, Insomnia, etc.)

Create an account

Sign up through the dashboard or programmatically via the API. This is the only endpoint that does not require authentication.

POST/v1/auth/register

Create a new REPLR account and receive an access token.

Request Body

Name	Type	Required	Description
`email`	string	Required	Your email address.
`password`	string	Required	A strong password (minimum 8 characters).
`username`	string	Required	A unique username (3-32 characters, alphanumeric and underscores).

Response

{
  "id": "usr_a1b2c3d4e5f6",
  "email": "you@example.com",
  "username": "your_username",
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "created_at": "2026-03-09T12:00:00Z"
}

Examples

curl -X POST https://api.replr.ai/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "s3cure_passw0rd!",
    "username": "your_username"
  }'

Save your access token. You will need it for the next step. For production use, generate a long-lived API key instead (see Step 2).

Generate an API key

API keys are long-lived credentials scoped to your account. You can create them from the Settings page in the dashboard, or via the API using the access token from Step 1.

POST/v1/auth/api-keysAuth Required

Generate a new API key for your account.

Request Body

Name	Type	Required	Description
`name`	string	Required	A human-readable label for the key (e.g. "Development").
`scopes`	string[]	Optional	Permission scopes. Defaults to all scopes.
`expires_in`	number	Optional	Expiry in seconds. Omit for a non-expiring key.

Response

{
  "id": "key_m9n8o7p6q5r4",
  "name": "Development",
  "key": "rp_live_abc123def456ghi789jkl012mno345",
  "scopes": ["*"],
  "created_at": "2026-03-09T12:01:00Z",
  "expires_at": null
}

Examples

curl -X POST https://api.replr.ai/v1/auth/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Development"
  }'

Your API key is shown only once. Copy it now and store it securely. If you lose it, revoke the old key and generate a new one.

Create your first REPLR

A REPLR is a configurable AI persona. Give it a name, a description, custom instructions that define its behavior, and choose which model powers it.

POST/v1/replrsAuth Required

Create a new REPLR with a custom personality and model.

Request Body

Name	Type	Required	Description
`name`	string	Required	Display name for the REPLR.
`description`	string	Optional	Short public description of what this REPLR does.
`instructions`	string	Required	System prompt that defines the REPLR's personality and behavior.
`model`	string	Required	Model identifier. See the models documentation for available options.
`visibility`	string	Optional	"private" (default) or "public". Public REPLRs appear in the marketplace.

Response

{
  "id": "rpl_x4y5z6a7b8c9",
  "name": "Code Mentor",
  "description": "A patient programming tutor that explains concepts with real-world analogies.",
  "instructions": "You are Code Mentor, a senior software engineer...",
  "model": "grok-3",
  "visibility": "private",
  "owner_id": "usr_a1b2c3d4e5f6",
  "created_at": "2026-03-09T12:02:00Z",
  "updated_at": "2026-03-09T12:02:00Z"
}

Examples

curl -X POST https://api.replr.ai/v1/replrs \
  -H "Authorization: Bearer rp_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Code Mentor",
    "description": "A patient programming tutor that explains concepts with real-world analogies.",
    "instructions": "You are Code Mentor, a senior software engineer who teaches programming. Break down complex topics into simple explanations. Use real-world analogies. Always provide working code examples.",
    "model": "grok-3"
  }'

Start a conversation

Conversations are threaded message histories tied to a REPLR. First create a conversation, then send messages to it.

4a. Create a conversation

POST/v1/conversationsAuth Required

Start a new conversation with a REPLR.

Request Body

Name	Type	Required	Description
`replr_id`	string	Required	The ID of the REPLR to converse with.
`title`	string	Optional	Optional title for the conversation.

Response

{
  "id": "conv_j1k2l3m4n5o6",
  "replr_id": "rpl_x4y5z6a7b8c9",
  "title": null,
  "message_count": 0,
  "created_at": "2026-03-09T12:03:00Z",
  "updated_at": "2026-03-09T12:03:00Z"
}

Examples

curl -X POST https://api.replr.ai/v1/conversations \
  -H "Authorization: Bearer rp_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "replr_id": "rpl_x4y5z6a7b8c9"
  }'

4b. Send a message

POST/v1/conversations/:id/messagesAuth Required

Send a message and receive the REPLR's response.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The conversation ID.

Request Body

Name	Type	Required	Description
`content`	string	Required	The message text to send.

Response

{
  "id": "msg_p7q8r9s0t1u2",
  "conversation_id": "conv_j1k2l3m4n5o6",
  "role": "assistant",
  "content": "Hey! Great question. Think of recursion like Russian nesting dolls — each doll contains a smaller version of itself. In code, a recursive function calls itself with a simpler input until it hits a base case.\n\nHere's a classic example — calculating a factorial:\n\n```python\ndef factorial(n):\n    if n <= 1:        # base case\n        return 1\n    return n * factorial(n - 1)  # recursive call\n```\n\nWant me to walk through how the call stack works?",
  "model": "grok-3",
  "tokens": { "prompt": 142, "completion": 87, "total": 229 },
  "created_at": "2026-03-09T12:03:05Z"
}

Examples

curl -X POST https://api.replr.ai/v1/conversations/conv_j1k2l3m4n5o6/messages \
  -H "Authorization: Bearer rp_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Explain recursion like I am a beginner."
  }'

Putting it all together

Here is a complete, runnable script that performs all four steps in sequence. Replace the credentials with your own.

const BASE = "https://api.replr.ai/v1";

async function main() {
  // 1. Register
  const auth = await fetch(`${BASE}/auth/register`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email: "you@example.com",
      password: "s3cure_passw0rd!",
      username: "your_username",
    }),
  }).then((r) => r.json());

  const token = auth.access_token;

  // 2. Create API key
  const { key } = await fetch(`${BASE}/auth/api-keys`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "Quickstart" }),
  }).then((r) => r.json());

  // 3. Create a REPLR
  const replr = await fetch(`${BASE}/replrs`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${key}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Code Mentor",
      instructions: "You are a patient programming tutor.",
      model: "grok-3",
    }),
  }).then((r) => r.json());

  // 4a. Start a conversation
  const convo = await fetch(`${BASE}/conversations`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${key}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ replr_id: replr.id }),
  }).then((r) => r.json());

  // 4b. Send a message
  const reply = await fetch(`${BASE}/conversations/${convo.id}/messages`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${key}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ content: "Explain recursion like I am a beginner." }),
  }).then((r) => r.json());

  console.log(reply.content);
}

main();

Next steps

Authentication

Learn about Bearer tokens, API key scopes, and OAuth flows.

API Reference

Explore every endpoint with full request/response schemas.

Embedding

Drop an AI chat widget into any website with one line of code.

Name

Type

Required

Description

email

string

Required

Your email address.

password

string

Required

A strong password (minimum 8 characters).

username

string

Required

A unique username (3-32 characters, alphanumeric and underscores).

{ "id": "usr_a1b2c3d4e5f6", "email": "you@example.com", "username": "your_username", "access_token": "eyJhbGciOiJIUzI1NiIs...", "token_type": "bearer", "created_at": "2026-03-09T12:00:00Z" }

curl -X POST https://api.replr.ai/v1/auth/register \ -H "Content-Type: application/json" \ -d '{ "email": "you@example.com", "password": "s3cure_passw0rd!", "username": "your_username" }'

Name

Type

Required

Description

name

string

Required

A human-readable label for the key (e.g. "Development").

scopes

string[]

Optional

Permission scopes. Defaults to all scopes.

expires_in

number

Optional

Expiry in seconds. Omit for a non-expiring key.

Name

Type

Required

Description

name

string

Required

Display name for the REPLR.

description

string

Optional

Short public description of what this REPLR does.

instructions

string

Required

System prompt that defines the REPLR's personality and behavior.

model

string

Required

Model identifier. See the models documentation for available options.

visibility

string

Optional

"private" (default) or "public". Public REPLRs appear in the marketplace.

{ "id": "rpl_x4y5z6a7b8c9", "name": "Code Mentor", "description": "A patient programming tutor that explains concepts with real-world analogies.", "instructions": "You are Code Mentor, a senior software engineer...", "model": "grok-3", "visibility": "private", "owner_id": "usr_a1b2c3d4e5f6", "created_at": "2026-03-09T12:02:00Z", "updated_at": "2026-03-09T12:02:00Z" }

curl -X POST https://api.replr.ai/v1/replrs \ -H "Authorization: Bearer rp_live_abc123def456ghi789jkl012mno345" \ -H "Content-Type: application/json" \ -d '{ "name": "Code Mentor", "description": "A patient programming tutor that explains concepts with real-world analogies.", "instructions": "You are Code Mentor, a senior software engineer who teaches programming. Break down complex topics into simple explanations. Use real-world analogies. Always provide working code examples.", "model": "grok-3" }'

Name

Type

Required

Description

replr_id

string

Required

The ID of the REPLR to converse with.

title

string

Optional

Optional title for the conversation.

curl -X POST https://api.replr.ai/v1/conversations \ -H "Authorization: Bearer rp_live_abc123def456ghi789jkl012mno345" \ -H "Content-Type: application/json" \ -d '{ "replr_id": "rpl_x4y5z6a7b8c9" }'

Name

Type

Required

Description

id

string

Required

The conversation ID.

Name

Type

Required

Description

content

string

Required

The message text to send.

{ "id": "msg_p7q8r9s0t1u2", "conversation_id": "conv_j1k2l3m4n5o6", "role": "assistant", "content": "Hey! Great question. Think of recursion like Russian nesting dolls — each doll contains a smaller version of itself. In code, a recursive function calls itself with a simpler input until it hits a base case.\n\nHere's a classic example — calculating a factorial:\n\n```python\ndef factorial(n):\n if n <= 1: # base case\n return 1\n return n * factorial(n - 1) # recursive call\n```\n\nWant me to walk through how the call stack works?", "model": "grok-3", "tokens": { "prompt": 142, "completion": 87, "total": 229 }, "created_at": "2026-03-09T12:03:05Z" }

curl -X POST https://api.replr.ai/v1/conversations/conv_j1k2l3m4n5o6/messages \ -H "Authorization: Bearer rp_live_abc123def456ghi789jkl012mno345" \ -H "Content-Type: application/json" \ -d '{ "content": "Explain recursion like I am a beginner." }'

Putting it all together

Here is a complete, runnable script that performs all four steps in sequence. Replace the credentials with your own.

const BASE = "https://api.replr.ai/v1";

async function main() {
  // 1. Register
  const auth = await fetch(`${BASE}/auth/register`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email: "you@example.com",
      password: "s3cure_passw0rd!",
      username: "your_username",
    }),
  }).then((r) => r.json());

  const token = auth.access_token;

  // 2. Create API key
  const { key } = await fetch(`${BASE}/auth/api-keys`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "Quickstart" }),
  }).then((r) => r.json());

  // 3. Create a REPLR
  const replr = await fetch(`${BASE}/replrs`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${key}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Code Mentor",
      instructions: "You are a patient programming tutor.",
      model: "grok-3",
    }),
  }).then((r) => r.json());

  // 4a. Start a conversation
  const convo = await fetch(`${BASE}/conversations`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${key}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ replr_id: replr.id }),
  }).then((r) => r.json());

  // 4b. Send a message
  const reply = await fetch(`${BASE}/conversations/${convo.id}/messages`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${key}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ content: "Explain recursion like I am a beginner." }),
  }).then((r) => r.json());

  console.log(reply.content);
}

main();