API
The app, HQ, the AI, outside AIs and any other client use the same Convex functions under the same permissions. There is no back door: a call can do exactly what the caller could do by tapping. The generated list of every public function, with what each does, is in the Catalog.
Every function works on the space the caller has open (see People) and checks a permission verb. A mutation a role can't use throws Your role in this space can't do that; a query returns empty instead.
import { useMutation, useQuery } from "convex/react";
import { api } from "../convex/_generated/api";
const space = useQuery(api.blueprint.get);
const add = useMutation(api.records.add);
await add({ collection: "orders", data: { item: "Mug", qty: 2 } });Three ways in #
| Way | For | How |
|---|---|---|
| Convex functions | The app, and your own app on the same backend | useQuery / useMutation with a signed-in person |
| MCP server | Any AI (Claude Desktop, Claude Code, Cursor…) | {CONVEX_SITE_URL}/mcp with an access token (docs/CAPABILITIES.md) |
| Proposals | Anything that changes the blueprint | blueprint.change (people) or propose_change (AIs), then approve |
Sign-in #
Convex Auth (convex/auth.ts), email and password: signIn("password", { email, password, flow: "signUp" | "signIn" }), signOut(). A new person goes through blueprint.me / blueprint.onboard (their name and their own space). Apple and Google come before release. TVs sign in as their own account through pairing (screens.*).
The core functions #
The space (blueprint.*)
| Function | Needs | Does |
|---|---|---|
get | signed in | The open space as this person sees it: { blueprint, workspaceId, version, role, can, member, me, own }. Hidden pages and blocks are already removed. |
me / onboard | signed in | Where the person is in onboarding; finish it in one step (name, purpose, space name, look, kits, or a starter template) |
ensure({ style? }) | signed in | Makes the person's own space on first sign-in (or returns it) |
change({ summary, ops }) | manage | Applies JSON Patch ops at once, checked, saved as a version |
history / restore({ version }) | manage | The last 30 versions; undo by saving an old one again |
pending / approve / discard | manage | The AI's proposals waiting for approval |
addKit({ kit }) / removeKit({ kit }) | manage | Adds or takes out a kit, as one version |
The AI (ai.*): messages and send({ text }), both manage.
Records (records.*)
| Function | Needs | Does |
|---|---|---|
list({ collection, limit? }) | view | Newest first, 200 by default, 500 at most; each with mine and canChange |
count({ collection }) | view | How many (up to 10,000) |
add({ collection, data }) | add | Checks and cleans every field, then saves |
update({ id, data }) / remove({ id }) | add (own) or edit | Changes or deletes |
People (members.*): list, mySpaces, open, visit, home, explore, setName; setRole and removeMember (manage, or yourself to leave); createInvite, invites, revokeInvite, requests, answerRequest (invite); peek and join (an invite code); joinOpen (a visitor joins an open space or asks to join).
The engines' functions #
| Module | Engine | Functions |
|---|---|---|
kits.talk.talk | Spaces, Lifecycle | Reading: conversation, posts, post, inbox, typing, reactors, people. Writing: send, edit, remove, react, pin, read, setSeat (mute, pin), setTyping, review (held posts). Direct and groups: openDirect, createGroup, addToGroup, leaveGroup, renameGroup, setGroupAdmin. Queues: openCase, cases, myCases, setCase (status, assignee), team. Drafts and later: draft, drafts, saveDraft, schedule, cancelScheduled, sendNow |
kits.structure.structure | Structure | placements, place, unplace, join, mine |
friends | Spaces | list, status, ask, answer, remove, spaces |
dms | Spaces | list, send, remove, conversations |
streams | Spaces, Time | list, send, remove, schedule, cancelScheduled, scheduledList, writable |
kits.ledger.ledger | Ledger, Structure | balances, history, leaderboard, levels, marks, rights, holders, open, send, issue, take, buyLevel, grant, revoke |
kits.social.posts | Spaces (feeds) | timeline, thread, pending, create, edit, remove, moderate (approve, hide, show) |
kits.social.reactions | Spaces (feeds) | react, reactors, repost, save, saved |
kits.social.people | Spaces (feeds) | me, byHandle, view, handleFree, saveProfile, follow, list, suggested |
kits.social.activity, .search, .sources | Spaces (feeds) | list, unseen, markSeen; posts, trending; status, pullNow (outside feeds) |
rounds.quick | Rounds | vote, poll, spin, wheel |
rounds.sessions | Rounds | create, join, leave, setPlayer, setOpen, act (every move), view, screen({ sessionId }), live({ gameId }), current |
bookings | Time | slots, days, book, cancel, upcoming |
events | Events | track, summary, leaders |
calls | Rooms | targets, start (ring), incoming, current, answer, decline, hangUp |
rooms, livekit | Rooms | rooms.status; livekit.join, joinCall (passes), moderate, record |
media | Files | list, latest, uploadTarget, save, remove, rename, can, byIds |
screens | Screens | open, pending, pair, mine, ping, list, show, disconnect |
kits.templates.templates | Templates | apply({ template }), overview({ days }) (manage), recentCalls (Templates) |
kits.photobook.books | Photo books | read({ block, book?, album?, upTo?, all? }), photos({ feed?, tag?, before? }) (manage), shelf({ block }). Each read names the block showing the book, so a book is exactly as private as its page |
kits.reviews.reviews | Spaces (reviews) | Reading: summary, stars, list, top, subjects, queue. Writing: write, remove, vote, reply, report, moderate (Engines) |
kits.search.search | Search | everywhere({ q, sources?, collection?, stream?, feed?, limit? }) (docs/SEARCH.md) |
kits.ailimits.limits | AI limits | allowance (the signed-in person's), usage (HQ report, managers) (AI limits) |
kits.sharing.library | Templates and kits | preview, saveMine, publish, unpublish, forget, mine, browse, details, add, added, takeOut, rate, report; admins queue, source, accept, reject, remove, restore, dismissReports (Templates) |
push | register, unregister (a phone's push token) | |
capabilities.vault | Capabilities | list (names only), save, setScopes, remove |
capabilities.tokens | Capabilities | list, create (shown once), revoke |
capabilities.connections | Capabilities | test |
Each engine's deep doc says who may call what: docs/LIVE.md, docs/SOCIAL.md, docs/CAPABILITIES.md, convex/kits/talk/README.md, convex/kits/structure/README.md, convex/kits/ledger/README.md.
Planned #
- Webhooks in and out ("when a record is added, call this URL"), through the Automations kit.
- Stripe Checkout and its webhook for card payments.