Prompt-first Setup

The fastest path: copy one prompt, paste it into your agent, and it handles everything — schema design, API calls, frontend wiring.

1. Go to the Dashboard and create a project
2. On the Overview page, click copy on the Agent Prompt block
3. Paste the prompt into your agent's context file:

The prompt contains everything: API base URL, keys, schema format reference, endpoint patterns, and auth instructions. Your agent can design and apply a schema, then build the frontend — all without reading docs.

What the agent gets

The generated prompt includes:

• Project API base URL and public key
• Full schema format reference (types, modifiers, access rules)
• REST API patterns with filter/sort syntax
• Auth endpoints (signup, login, refresh, me)
• Instructions to store the admin key in .env
• The current schema (if already set) with exact column definitions

Example workflow

# You say to the agent:
"Build a habit tracker. Users can create habits, mark them
done each day, and see streaks."

# The agent reads the MoonDB prompt from CLAUDE.md and:
# 1. Designs a schema (users, habits, completions)
# 2. PUTs it to /v1/schema
# 3. Builds the React/Vue/Svelte frontend
# 4. Wires up auth and API calls

Manual Setup

If you prefer working without a coding agent, store credentials in .env:

# .env
MOONDB_API_BASE=https://moondb.ai/p/{project_id}
MOONDB_ADMIN_KEY=sk_...
MOONDB_PUBLIC_KEY=pk_...

Client-side usage

Use the public key for browser reads. MoonDB has CORS enabled so any origin can call the API.

// Read tasks
const res = await fetch(
  `$https://moondb.ai/api/tasks?sort=created_at.desc&limit=20`,
  { headers: { 'X-Public-Key': 'pk_...' } }
);
const { data } = await res.json();

// Create task (requires auth token)
const res = await fetch(`$https://moondb.ai/api/tasks`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + userToken
  },
  body: JSON.stringify({ title: 'Buy milk', done: false })
});

Server-side usage

Use the admin key for schema changes and privileged operations. Never expose it to the client.

// Node.js / server-side
const res = await fetch(`$https://moondb.ai/v1/schema`, {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'X-Admin-Key': process.env.MOONDB_ADMIN_KEY
  },
  body: JSON.stringify({ tables: { ... } })
});

Keys & Auth

Three credential types, each with a different scope:

Alternative: Bearer token

All keys can also be passed as Authorization: Bearer {key}. MoonDB auto-detects the key type from the prefix.

Platform JWT

After login (POST /v1/accounts/login), you get a JWT. Use it as Authorization: Bearer {token} for platform operations (project management, billing). The JWT expires after 1 hour by default.

Defining Schema

The schema is a JSON object sent to PUT /p/{id}/v1/schema:

{
  "tables": {
    "users": {
      "columns": {
        "email": "string required unique",
        "display_name": "string",
        "avatar": "file",
        "role": { "type": "enum", "values": ["user", "admin"], "default": "user" }
      },
      "auth_table": true
    },
    "posts": {
      "columns": {
        "user_id": "ref users required",
        "title": "string required",
        "body": "text",
        "published": "bool default false"
      },
      "access": { "read": "public", "create": "authenticated", "update": "owner", "delete": "owner" },
      "owner_field": "user_id"
    }
  }
}

Built-in columns

Every table automatically gets these — never define them:

• id — UUID v4, primary key
• created_at — ISO 8601 timestamp, set on insert
• updated_at — ISO 8601 timestamp, updated on every change

Table options

Column Types

Column modifiers

Add after the type in short-form, or as object keys:

• required — NOT NULL
• unique — UNIQUE constraint
• index — creates an index for faster queries
• default <value> — default value

Object form

For more control, use the full object form instead of short-form strings:

{
  "price": {
    "type": "float",
    "required": true,
    "min": 0,
    "max": 99999,
    "default": 0
  },
  "status": {
    "type": "enum",
    "values": ["draft", "published", "archived"],
    "default": "draft",
    "required": true
  },
  "author_id": {
    "type": "ref",
    "ref": "users",
    "required": true,
    "on_delete": "cascade"
  }
}

Short-form Syntax

Write column definitions as space-separated strings for compact schemas:

# String with modifiers
"email": "string required unique"
# equivalent to:
"email": { "type": "string", "required": true, "unique": true }

# With default
"streak": "int default 0"
"is_active": "bool default true"

# Reference to another table
"user_id": "ref users required"

# Reference with cascade delete
"post_id": "ref posts required on_delete cascade"

# Indexed column
"slug": "string required index"

Full example

{
  "tables": {
    "users": {
      "columns": {
        "email": "string required unique",
        "name": "string required",
        "bio": "text",
        "avatar": "file",
        "streak": "int default 0"
      },
      "auth_table": true
    },
    "habits": {
      "columns": {
        "user_id": "ref users required on_delete cascade",
        "name": "string required",
        "color": "string default #3b82f6",
        "archived": "bool default false"
      },
      "access": { "read": "owner", "create": "authenticated", "update": "owner", "delete": "owner" },
      "owner_field": "user_id"
    },
    "completions": {
      "columns": {
        "habit_id": "ref habits required on_delete cascade",
        "user_id": "ref users required",
        "date": "date required"
      },
      "access": { "read": "owner", "create": "authenticated", "update": "owner", "delete": "owner" },
      "owner_field": "user_id",
      "unique": [["habit_id", "date"]]
    }
  }
}

Schema Updates

Always send the full schema. MoonDB diffs it against the current version and generates migrations automatically.

Non-destructive changes

Applied immediately, no confirmation needed:

• Add a new table
• Add a new column (nullable or with default)
• Add new enum values
• Add an index
• Change access rules

Destructive changes

Returns a preview first. Add "confirm_destructive": true to apply:

• Drop a table
• Drop a column
• Remove enum values
• Make a nullable column required

PUT /p/{id}/v1/schema
{
  "tables": { ... },
  "confirm_destructive": true
}

Useful endpoints

GET  /p/{id}/v1/schema           # current schema + version
POST /p/{id}/v1/schema/validate   # dry-run without applying

REST Endpoints

Every table gets full CRUD automatically:

GET    /p/{id}/api/{table}              # List (with filters)
GET    /p/{id}/api/{table}/{row_id}     # Get one
POST   /p/{id}/api/{table}              # Create
PATCH  /p/{id}/api/{table}/{row_id}     # Update
DELETE /p/{id}/api/{table}/{row_id}     # Delete
POST   /p/{id}/api/{table}/bulk         # Bulk create (array body)

Response format

// List response
{
  "data": [ { "id": "...", "title": "...", ... } ],
  "meta": { "total": 42, "limit": 20, "offset": 0 }
}

// Single item
{ "data": { "id": "...", "title": "...", ... } }

// Error
{ "error": { "code": "...", "message": "...", "suggestion": "..." } }

Bulk insert

Send an array of objects. Atomic — all succeed or all fail:

POST /p/{id}/api/tasks/bulk
[
  { "title": "Task 1", "done": false },
  { "title": "Task 2", "done": true }
]

Filtering & Sorting

Add filters as query params: field=op.value

# Equals
GET /api/posts?published=eq.true

# Comparison
GET /api/posts?created_at=gte.2025-01-01

# Pattern match
GET /api/posts?title=like.Hello%

# Multiple values
GET /api/posts?status=in.draft,published

# Null checks
GET /api/posts?deleted_at=is_null

# Combine filters
GET /api/posts?published=eq.true&created_at=gte.2025-01-01&sort=created_at.desc

Sorting

GET /api/posts?sort=created_at.desc
GET /api/posts?sort=title.asc,created_at.desc

Pagination

# Offset-based
GET /api/posts?limit=20&offset=40

# Cursor-based (use next_cursor from response meta)
GET /api/posts?limit=20&cursor=eyJ...

Field selection & includes

# Select specific fields
GET /api/posts?select=id,title,created_at

# Include related records (via ref columns)
GET /api/posts?include=user_id

End-user Auth

Mark a table as auth_table: true to get built-in email/password auth.

# Sign up
POST /p/{id}/auth/signup
{ "email": "user@example.com", "password": "secret123" }
# -> { token, refresh_token, user }

# Log in
POST /p/{id}/auth/login
{ "email": "user@example.com", "password": "secret123" }

# Refresh token
POST /p/{id}/auth/refresh
{ "refresh_token": "..." }

# Get current user
GET /p/{id}/auth/me
Authorization: Bearer {token}

# Logout
POST /p/{id}/auth/logout
Authorization: Bearer {token}

Using the token

Pass the JWT in subsequent requests:

Authorization: Bearer eyJhbGci...

Email verification

Add "verify_email": true to the auth table. Users receive a verification email on signup.

GET  /p/{id}/auth/verify?token=...
POST /p/{id}/auth/resend-verification
     Authorization: Bearer {token}

Signup with extra fields

If your auth table has custom columns, pass them in the signup body:

POST /p/{id}/auth/signup
{
  "email": "user@example.com",
  "password": "secret123",
  "display_name": "Alice",
  "role": "user"
}

Access Control

Set per-operation access rules in the schema:

"access": {
  "read": "public",
  "create": "authenticated",
  "update": "owner",
  "delete": "admin"
},
"owner_field": "user_id"

Common patterns

File Storage

Upload files to R2 storage via multipart form:

# Upload
POST /p/{id}/storage/upload
Content-Type: multipart/form-data
Authorization: Bearer {token}

# -> { url, key, size, content_type }

# Download
GET /p/{id}/storage/{key}

# Delete
DELETE /p/{id}/storage/{key}
X-Admin-Key: sk_...

Using with file columns

Use file type columns in your schema. Upload the file first, then store the returned URL in the column:

# 1. Upload
POST /p/{id}/storage/upload  ->  { "url": "https://..." }

# 2. Save to record
PATCH /p/{id}/api/users/{user_id}
{ "avatar": "https://..." }

AI Endpoints

MoonDB includes built-in AI endpoints powered by Cloudflare Workers AI. Define endpoints in your schema, call them via the REST API, and pay with credits.

Defining AI endpoints

Add an ai_endpoints section to your schema:

{
  "tables": { ... },
  "ai_endpoints": {
    "summarize": {
      "model": "gemma",
      "prompt": "Summarize this text in 2 sentences: {{text}}",
      "access": "auth"
    },
    "generate_avatar": {
      "model": "flux-schnell",
      "prompt": "A minimal avatar for a user named {{name}}, flat design",
      "access": "auth"
    }
  }
}

Template parameters ({{name}}) are filled from the request body at call time.

Available models

Calling an endpoint

POST /p/{project_id}/ai/{endpoint_name}
Authorization: Bearer {token}
Content-Type: application/json

{
  "text": "MoonDB is a DBaaS built for coding agents..."
}

Response

Text models return:

{ "type": "text", "result": "...", "model": "gemma", "credits_used": 3 }

Image models return base64-encoded data:

{ "type": "image", "image": "data:image/png;base64,...", "model": "flux-schnell", "credits_used": 10 }

Access control

Each endpoint has an access field:

• "public" — no auth required.
• "auth" (default) — end-user JWT or API key required.
• "admin" — admin key only.

Credits

Each plan includes free credits per month. When exhausted, buy more via POST /v1/billing/ai-credits. Check your balance in Dashboard → AI.

Agent Integration

MoonDB generates project-specific context files so your coding agent knows the exact schema, endpoints, and auth flow.

Option 1: Dashboard prompt (recommended)

Dashboard → Overview → copy the Agent Prompt. Paste into your agent's context file. This is the fastest way.

Option 2: Download context files

Dashboard → Agent Files has downloadable files:

• .cursorrules — for Cursor
• CLAUDE.md — for Claude Code
• LLM context — for any agent

Option 3: Fetch at runtime

# Text format
GET /p/{id}/v1/llm-context

# JSON format
GET /p/{id}/v1/llm-context?format=json

# Agent-specific
GET /p/{id}/v1/cursor-rules
GET /p/{id}/v1/claude-md

Tips

• Always include the schema in context — prevents guessing column names
• Store admin key in .env as MOONDB_ADMIN_KEY
• After schema changes, re-fetch LLM context to stay in sync
• Error suggestion fields are designed for agents to self-correct

MCP Server

MoonDB exposes an MCP endpoint at POST /mcp so AI agents can manage projects through a single JSON-RPC 2.0 interface instead of crafting individual REST calls.

Authentication

Pass your API key as X-API-Key: mk_... or Authorization: Bearer mk_.... All tools operate on projects owned by the authenticated account.

Protocol

Every request is a JSON-RPC 2.0 envelope:

POST /mcp
Content-Type: application/json
X-API-Key: mk_...

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "create_project", "arguments": { "name": "my-app" } } }

Available tools

Supported methods

• initialize — returns server info and capabilities.
• tools/list — returns the tool definitions above.
• tools/call — executes a tool with provided arguments.

Example: full flow

# 1. Create project
{ "jsonrpc":"2.0", "id":1, "method":"tools/call",
  "params":{"name":"create_project","arguments":{"name":"todo-app"}} }

# 2. Set schema
{ "jsonrpc":"2.0", "id":2, "method":"tools/call",
  "params":{"name":"set_schema","arguments":{
    "project_id":"...",
    "schema":{"tables":{"tasks":{"columns":{"title":"string required","done":"bool default=false"}}}}
  }} }

# 3. Insert data
{ "jsonrpc":"2.0", "id":3, "method":"tools/call",
  "params":{"name":"insert","arguments":{
    "project_id":"...","table":"tasks","data":{"title":"Buy milk"}
  }} }

Deploy Frontend

MoonDB is the backend. Your frontend can be deployed anywhere.

Vercel

# .env.local or Vercel dashboard
NEXT_PUBLIC_MOONDB_URL=https://moondb.ai/p/{project_id}
NEXT_PUBLIC_MOONDB_PUBLIC_KEY=pk_...
MOONDB_ADMIN_KEY=sk_...  # server-side only

Netlify

# netlify.toml or dashboard
[build.environment]
  VITE_MOONDB_URL = "https://moondb.ai/p/{project_id}"
  VITE_MOONDB_PUBLIC_KEY = "pk_..."

Cloudflare Pages

# wrangler.toml or Pages dashboard
[vars]
VITE_MOONDB_URL = "https://moondb.ai/p/{project_id}"
VITE_MOONDB_PUBLIC_KEY = "pk_..."

Render / Railway / Fly.io

# Set in platform dashboard:
MOONDB_URL=https://moondb.ai/p/{project_id}
MOONDB_PUBLIC_KEY=pk_...
MOONDB_ADMIN_KEY=sk_...

Static hosting (any)

MoonDB has CORS enabled, so any static site can call the API from the browser:

const API = 'https://moondb.ai/p/{project_id}';
const PK = 'pk_...';

const res = await fetch(API + '/api/tasks', {
  headers: { 'X-Public-Key': PK }
});
const { data } = await res.json();

External Auth

Use Clerk, Auth0, Supabase, or any OIDC provider instead of MoonDB's built-in auth.

PUT /p/{id}/v1/auth-config
X-Admin-Key: sk_...

{
  "provider": "external",
  "jwks_url": "https://your-provider.com/.well-known/jwks.json",
  "user_id_claim": "sub",
  "audience": "your-audience",
  "issuer": "https://your-issuer"
}

After configuration, users authenticate with your provider and pass their JWT to MoonDB. MoonDB validates the token against the JWKS endpoint.

How it works

1. User logs in via Clerk/Auth0/etc.
2. Your frontend gets a JWT from the provider
3. Pass that JWT to MoonDB as Authorization: Bearer {token}
4. MoonDB validates it via JWKS and extracts the user ID

Error Handling

Every error includes a suggestion field — actionable instructions for agents and developers.

{
  "error": {
    "code": "FK_NOT_FOUND",
    "message": "Foreign key 'user_id' references row 'abc' which does not exist",
    "suggestion": "Create the referenced user first, then retry."
  }
}

HTTP status codes

Plans & Limits

Upgrade anytime from Dashboard → Billing. Downgrades take effect at the end of the billing period.

What happens when limits are exceeded?

• Rate limit (RPM) — returns 429 with retry-after. Requests resume next minute.
• Monthly reads/writes — returns 429 after 110% of quota. Resets on the 1st of each month.
• Storage — uploads blocked when full. Existing files remain accessible.
• Projects — cannot create new projects. Existing ones keep working.