Know Me BestJoin a game

Developers

Muse integration

The Muse connector has been submitted for approval and is not publicly available yet. Approval is pending and is not guaranteed.

This REST API is designed so an assistant can draft a Know Me Best game from what the host says, let the host review it, hand them a payment link, and follow the game to its final scores — plus the free daily challenge, where Muse locks in five guesses before the person answers. Muse is not affiliated with Know Me Best and has not endorsed it.

Base URL and auth

POST /api/public/muse/v1/games/draft
Authorization: Bearer <connector secret>
Content-Type: application/json

GET /api/public/muse/v1/games/<id>
Authorization: Bearer <connector secret>
X-Resource-Capability: <capability for that game>

The secret lives only in server environment configuration and is compared in constant time. Requests without a valid token are refused — the API fails closed if no secret is configured.

The secret proves who is calling. It never grants access to a game or a daily session on its own. Creating one returns capabilities, shown once, that every later call must present as X-Resource-Capability. Each is tied to that one game or session and to one set of powers: host (read, edit, delete, checkout, start, results), preview (read only), checkout (read plus authorized payment), player (in-app guest play, used by the game client, not the connector), daily management (predictions and result), and daily play (used by the play page, not the connector). An id is never a key, and a capability for one game is refused for every other game.

A game can carry up to four different links, each granting a different, narrower level of access:

host_management_urlFull edit and manage access for the game's host: edit questions, delete the game, start the round, read results.
review_urlRead-only review of the game. Cannot edit, delete, start or pay from this page.
checkout_urlRead-only review plus an authorized, single-use payment claim. It can display and complete payment, but editing is not possible from this page — edit questions first with PATCH /games/{id}/questions/{questionId} (or host_management_url) before requesting checkout.
join_urlGuest entry into a published game, usable only after the host has paid.

Machine-readable description: /api/public/muse/openapi.json

Daily challenge: lock, then play

Everyone gets the same five questions each day, each with four fixed choices. There is no right answer — the person's own pick is the truth. The order is fixed and enforced on our side: read today's questions, predict all five, lock them, and only then do we hand back a private play link. Guesses can never be changed, and they are not returned to the browser until the matching answer is in.

We receive question ids, choice indexes and an optional confidence number — nothing else. Know Me Best does not read Muse memories or conversations; the assistant predicts from the context it already has.

GET /dailyToday's challenge number, date and five questions.
POST /daily/sessionsStart a session. No play link until guesses are locked.
POST /daily/sessions/{sessionId}/predictionsLock all five guesses at once, then receive the private play link.
GET /daily/sessions/{sessionId}/resultProgress while playing; matches, streak and share text once finished.

Party Mode endpoints

GET /healthCheck the connector is reachable.
GET /catalogThe one game format, price, occasions and tones.
POST /games/draftDraft a game from approved fact_selections. Requires age_eligibility_confirmed: true. Never charges.
GET /games/{id}Read the game and all ten questions.
PATCH /games/{id}Update title, occasion, tone, schedule or host email.
POST /games/{id}/questionsAdd a question.
PATCH /games/{id}/questions/{questionId}Rewrite or reorder a question. This is the only way to edit a question — including after checkout has been requested — and it always requires the host capability.
DELETE /games/{id}/questions/{questionId}Remove a question from a game.
DELETE /questions/{questionId}Remove a question by id alone.
POST /games/{id}/checkoutGet checkout_url for the host to open and pay, and a read-only review_url with no payment claim. Requires the host capability.
GET /games/{id}/statusPayment state, join link, room code, player count.
GET /games/{id}/resultsWinner, podium and final scores.
DELETE /games/{id}Delete the game and everything in it.

Optional MCP endpoint

The same operations are also available as tools over MCP Streamable HTTP at /mcp (alias /api/public/muse/mcp). It is stateless: POST only, JSON responses, no session id; GET and DELETE return 405. Protocol 2026-07-28 is served statelessly (server/discover, per-request _meta, and the MCP-Protocol-Version, Mcp-Method and Mcp-Name headers). Clients on 2025-11-25, 2025-06-18 or 2025-03-26 can still use the initialize handshake. The REST API above is unchanged and remains the primary contract. Muse connector approval is pending, and whether Muse uses MCP is up to Meta.

Every call, including initialize and tools/list, needs Authorization: Bearer <connector token>. Browser requests from other sites are refused. Each resource tool takes the exact capability for that game or session as its capability argument; a capability for another resource, or with a weaker scope, is refused with forbidden.

  • daily_get_today: today's five questions
  • daily_start_session: returns daily_manage once
  • daily_lock_guesses: daily_manage; returns play_url
  • daily_get_result: daily_manage
  • party_create_draft: returns host + preview once
  • party_get_game: host, preview or checkout
  • party_update_game: host
  • party_edit_question: host
  • party_get_status: host, preview or checkout
  • party_get_results: host
  • party_start_checkout: host; never charges

No tool answers for a person, starts a round or takes a payment. The person answers Daily questions in their own browser, and the host approves and pays in theirs.

What the API will never do

  • Charge anyone. Drafting and editing are always free; only the host can complete a payment.
  • Touch card details. Stripe renders and processes the payment form on the host's own screen; Know Me Best never receives card data.
  • Read Muse memories or conversations, or ask for them. Predictions arrive as plain choice numbers.
  • Charge anything for the daily challenge. Daily is currently free.
  • Invent personal facts as true. Correct answers only come from the host's selections.
  • Send email, SMS or WhatsApp invitations. You get a link and copy-ready text instead.
  • Publish a game without the host's approval.
  • Automatically send Daily Challenge answers back to Muse.
  • Write to Muse memory.
  • Share Party Mode guest answers with Muse.
  • Reveal a Daily answer before the predictions are locked and the round is complete.
  • Accept sensitive personal details. Host names, titles, facts, questions, choices and reveal text that mention health, sexuality, ethnicity, politics, religion, precise location, finances, payment cards, biometrics or children are rejected with 422 validation_failed before they are stored or sent to the question writer, and the rejected text is never echoed. Screening matches common wording and cannot guarantee detection of every free-text phrasing.
  • Serve anyone under 18. The service is for adults 18+. POST /games/draft, POST /daily/sessions and the matching MCP tools require age_eligibility_confirmed: true; missing or false returns 422 validation_failed. This is self-attestation by the person, not verified age.
  • Accept free-text personalization. Drafts use fact_selections (topic and choice ids from fact_topics in GET /catalog). Free-text facts, custom questions, adding questions, and editing prompt, choices or reveal text return 422 validation_failed. Safeguards reduce risk but do not guarantee detection of every prohibited submission.

Errors

unauthorized401Missing or wrong bearer token, or a resource capability was required and none was sent.
forbidden403The resource capability is invalid, expired, consumed, has the wrong scope, or belongs to another resource.
not_found404No game or question with that id.
validation_failed422Field-level problems are listed in details.
content_rejected422The content isn't allowed in a party game.
conflict409The game has started or already holds ten questions.
rate_limited429Slow down; Retry-After tells you how long.
generation_failed502Drafting failed; retry or supply questions.
server_error500Unexpected; safe to retry.

Example prompts

  • “Create a funny game about me for my birthday.”
  • “Make a clean family version with ten questions.”
  • “Let me review the game before I buy it.”
  • “Replace question four with something about my favorite vacation.”
  • “Publish the game and give me a link to invite everyone.”
  • “Show me the final results.”
  • “Play today's Know Me Best challenge.”
  • “Do you actually know me? Lock in your guesses.”
  • “Predict how I'll answer today's five questions.”
  • “How well did you know me today?”
  • “Show me our Know Me Best streak.”

The game, in numbers

Daily: five questions, four choices each, free, one set per calendar day. Party Mode: 10 multiple-choice questions · 15 seconds each · up to 30 players · $5.99 once per published game, paid through Stripe · results available for 30 days.

Questions? Contact support.