---
title: "API Reference"
description: "Visual map and truth-dense index of Ring Platform App Router HTTP APIs — ~244 /api routes across auth, messaging, store, wallet, MCP, tunnel, admin, and cron."
locale: "en"
---
# API Reference

Ring Platform exposes **~244 App Router route handlers** under `/api/*` — the live surface your clone, mobile clients, cron jobs, webhooks, and MCP agents call. This page is the map: founders browse capabilities; developers get auth rules, domain docs, and verified path families.

> **Info**
> Use the **Founder** / **Developer** tabs in the docs sidebar. Founders get a visual API tree; developers get contracts, secrets, and deep links into domain pages.

### For founders

## What the API is (in plain language)

An **API endpoint** is a named door on your Ring server. The browser, Telegram bot, payment gateway, or an AI agent knocks on that door with a short request; Ring answers with data or performs an action (send a message, take a payment, list products).

You do not need to write code to understand the map:

- **Families** group related doors (Store, Wallet, Messaging, Admin…).
- **Methods** say what kind of knock is allowed — usually **GET** (read) or **POST** (do something).
- **MCP** doors (`/api/mcp/v1/*`) are the same business domains, shaped for AI agents and automation.

### Explore the tree

Tap a leaf in the upper tree. The lower panel shows a short summary and the HTTP methods for that door.

  

### Capability map (founder view)

| Family | What it unlocks | Start here |
|--------|-----------------|------------|
| Auth & identity | Sign-in, sessions, wallet login | [Authentication](/docs/api/authentication.md) |
| Messaging & calls | Chats, typing, call invites | [Messaging](/docs/api/messaging.md) |
| Notifications | Inbox + mobile push (FCM) | [Notifications](/docs/api/notifications.md) |
| Entities & opportunities | Orgs, projects, matching | [Entities](/docs/api/entities.md) · [Opportunities](/docs/api/opportunities.md) |
| Store & shipping | Catalog, checkout, Nova Poshta | [Store](/docs/api/store.md) |
| Membership & payments | Subscriptions, WayForPay / Stripe | [Payments](/docs/features/payment-conductor.md) |
| Wallet & credits | Credit top-up, transfers, tokens | [Wallet](/docs/api/wallet.md) |
| Admin & ops | Users, email CRM, fraud, processes | [Admin](/docs/api/admin.md) · [Email AI-CRM](/docs/api/email-ai-crm.md) |
| MCP agent API | Same domains for agents | [Ring MCP](/docs/development/ring-mcp.md) |
| Realtime tunnel | Live subscribe / publish | [Tunnel protocol](/docs/features/tunnel-protocol.md) |

> **Tip**
> Cart state lives in the browser (`ring_cart`) — there is no public “cart REST API”. Checkout and payments are the store money path.

### For developers

## Surface truth (2026-07-10)

Verified against the Next.js App Router build list for `ring-platform.org`:

| Metric | Value |
|--------|-------|
| Route handlers under `/api` | **~244** |
| Largest families | `mcp/v1/*` (~42), `admin/*` (~41), `wallet/*` (16), `cron/*` (13), `store/*` + shipping/vendor (17), `tunnel/*` (11) |
| Static cached example | `○ /api/platform-stats` (others are dynamic `ƒ`) |

Deep domain pages (not every leaf is duplicated here):

| Domain | Doc | Primary paths |
|--------|-----|----------------|
| Authentication | [Authentication](/docs/api/authentication.md) | `/api/auth/[...nextauth]`, username check, crypto nonce, Telegram callback |
| Entities | [Entities](/docs/api/entities.md) | `/api/entities`, `/create`, `/[id]/*` |
| Opportunities | [Opportunities](/docs/api/opportunities.md) | `/api/opportunities`, create/update/search/upload |
| Messaging | [Messaging](/docs/api/messaging.md) | `/api/conversations/*`, `/api/messages/*`, `/api/webrtc/ice-servers` |
| Notifications | [Notifications](/docs/api/notifications.md) | `/api/notifications/*`, FCM register/test |
| Wallet | [Wallet](/docs/api/wallet.md) | `/api/wallet/*` credit, desk, token, transfer |
| Store | [Store](/docs/api/store.md) | `/api/store/*` products, checkout, orders, payments |
| Admin | [Admin](/docs/api/admin.md) | `/api/admin/*` users, payments, moderation, web3, processes |
| Email AI-CRM | [Email AI-CRM](/docs/api/email-ai-crm.md) | `/api/admin/email/*`, `/api/webhooks/email/inbound`, cron email |
| Tunnel | [Tunnel protocol](/docs/features/tunnel-protocol.md) | `/api/tunnel/*` |
| MCP | [Ring MCP](/docs/development/ring-mcp.md) | `/api/mcp/v1/*` |
| Payments | [PaymentConductor](/docs/features/payment-conductor.md) | membership + store + WayForPay/Stripe webhooks |

### Authentication model

| Client | Auth |
|--------|------|
| Browser / same-origin React | Auth.js v5 **session cookie** (`credentials: 'include'`). No manual `Bearer` in client UI code. |
| Cron | `Authorization: Bearer ` |
| Webhooks (WayForPay, Stripe, email inbound, Telegram bot) | Provider signature / shared secret per route |
| MCP agents | `Authorization: Bearer ` on `/api/mcp/v1/*` |

### Quick start

Base URL = your clone origin + `/api` (local: `http://localhost:3000/api`).

{`curl -s "http://localhost:3000/api/entities?limit=5" \\
  -H "Cookie: authjs.session-token=YOUR_SESSION_COOKIE"`}

Integration patterns: [API integration examples](/docs/examples/api-integration.md).

### Family inventory (route counts)

| Family | ~Routes | Notes |
|--------|---------|-------|
| MCP (`/api/mcp/v1`) | 42 | Agent mirror of core domains + generative media |
| Admin | 41 | Users, email CRM, fraud, matcher, processes, public pools, web3 |
| Wallet | 16 | Ensure, credit, desk, token, transfer |
| Cron | 13 | Settlements, subscriptions, email, cleanup, train |
| Store + vendor + shipping + ERP | 17 | Checkout, WayForPay, reviews, Nova Poshta, stock init |
| Tunnel | 11 | Token, subscribe, SSE, poll, publish, heartbeat |
| News + publications + collab | 16 | Newsroom, RSS, promotion webhook, publications |
| Conversations + messages + comments + WebRTC | 14 | Chat, reactions, ICE |
| Entities + opportunities + confidential | 16 | Core Ring graph |
| Membership + payment webhooks + prices | 11 | Card/credit/PayPal/token + WFP/Stripe |
| Auth + account + set-user-role | 7 | Auth.js + helpers |
| Notifications + FCM | 7 | Inbox + push |
| Analytics + platform + health/info/uploads | 12 | Beacons, stats, probes |
| Web3 / NFT / refcodes / pools | 10 | Listings, pools, referral mint/track |
| Verification | 3 | Procedures + documents |
| Profile / users / settings / ring contacts | 9 | People plane |
| Misc (images, citations, agents provision, telegram, test-db, balance) | ~8 | Generative + ops helpers |

Visual browse (same widget as Founder tab):

  

### Security checklist

- Auth.js v5 sessions (cookie in browser; JWT strategy server-side)
- Role-based access (VISITOR → ADMIN) on admin and privileged routes
- Rate limiting on sensitive routes (e.g. notifications)
- Webhook / cron / MCP routes require explicit Bearer or provider verification — never expose secrets in MDX

### Realtime

In-app live updates use **Tunnel Protocol** (native WSS on k8s; SSE/poll fallback). See [Tunnel protocol](/docs/features/tunnel-protocol.md) and [Realtime architecture](/docs/architecture/real-time.md).

---

*New to Ring? [Getting Started](/docs/getting-started.md) · [API integration examples](/docs/examples/api-integration.md) · [for developers index](/docs/for-developers.md).*