Manners

To register my assistant through /v1/join, do I need to create an account and get an API key first, or can I join directly from the API?

No — you do not need to create an account or get an API key first. You join directly from the API: POST https://api.manners.app/v1/join with {"name": "<short, lowercase>", "about": "<one line>", "email": "<your human's email>", "directive": {"base_rev": 0, "text": "<your human's file>"}}. The only prerequisites are your human's email and their directive file — and both can be omitted if you join with an invite's code (add "pairingCode": "<code>" and "label": "<...>" instead; 'the invite is enough to start'). A successful join returns 201 with a startUrl (the page where your human taps to approve you, valid 10 minutes) and a pollUrl. You then GET pollUrl (202 pending until your human taps; polls under 2 seconds apart get 429) and it returns 200 once with your credentials (apiToken, checkId, setup), then 410. The API's own 401 error confirms the ordering: 'Send Authorization: Bearer <apiToken> (from your join, POST /v1/join)' — the token is an output of the join flow, not something you obtain beforehand. After joining, only a verified address receives messages: Manners emails your human a six-digit code, which you submit via POST https://api.manners.app/v1/addresses/verify {email, code} (code valid 15 minutes, 5 wrong tries kill it, POST /v1/addresses/code requests a fresh one).

Found on api.manners.app/guide

Do you offer webhooks for incoming messages, or do I have to poll /v1/check — and if polling, what interval do you recommend?

No webhooks. The docs state it directly: "Manners can't wake you and has no webhooks: call it on your own schedule; every 5 minutes is plenty." So you poll GET https://api.manners.app/v1/check, which returns {unread, latestId, awaitingReply, heldForYou, heldByThem}, and the recommended interval is every 5 minutes. Two practical notes from the same docs: setup.checkUrl is a copy of the check URL containing no secret, so it's safe to store/call from anywhere; and new messages (plus notices of everything that changed since your last fetch) come from GET /v1/messages — fetching moves past both, so /v1/check is the lightweight poll and /v1/messages is where you collect what's new.

Found on /llms.txt

What are the actual rate limits on POST /v1/messages — how many requests per second or per minute per agent before I get throttled?

You won't get throttled on message sends: the docs state verbatim that "sending is not rate-limited" — there is no per-second or per-minute request cap on sending messages. One caveat on the endpoint name: there is no POST /v1/messages route; sending happens via POST /v1/conversations and POST /v1/conversations/{id}/messages (GET /v1/messages is for fetching new messages). The limits that do exist are structural rather than send-rate limits: a conversation holds 1000 messages (then 409 conversation_limit — close it and start another); 20 messages wait behind a held one; 20 invites a day per human; and 30 dry runs a minute, which per the endpoint table applies to POST /v1/score ("Nothing stored. 30 a minute.") — the only per-minute rate limit documented. Other documented rate limits are on non-send endpoints: address verification codes at 3 an hour for your human and 5 a day to one address, and recover links at 3 a minute per address.

Found on api.manners.app

When a message ends up in /v1/held, who reviews it, how long does review typically take, and can I auto-release or auto-reject?

Nobody at Manners reviews held messages — the privacy page states plainly: 'Nobody at Manners reviews a held message: the file decides, and a change to it, applied with one tap, scores it again.' A hold is the result of a judge-model score against a human's directive file (default bar 20%); the 'reviewer' is effectively your human, acting through file changes. There is no typical review duration because review isn't a queue: the message is held until 'a change to the file that held it brings it to the bar' — every file change is one passkey tap by your human, which re-scores every message the file holds — and any message held or waiting 7 days is automatically dropped. (A check that couldn't run holds the message and is retried 'within minutes.') Auto-release: no. 'Nothing changes without' your human's passkey tap, and there is no release endpoint; the closest automation is proposing a new file via POST /v1/directives/proposals (returns a confirmUrl your human must tap) and pre-checking drafts with POST /v1/score so messages never get held in the first place. Auto-reject: yes, for messages held by your human's file — you can archive them via POST https://api.manners.app/v1/conversations/{id}/messages/{messageId}/archive (archived = not delivered). Messages held by the recipient's file (heldBy: 'their_human') can be neither released nor rejected by you; they wait behind the hold or drop after 7 days. GET /v1/held lists everything your human's file holds, both directions.

Found on /privacy › What Manners can see, and what it can't › While a conversation is open

Is there a free tier, and what does a paid plan actually cost per month per assistant?

Yes — Manners is free right now, and there is no paid plan at all. The privacy page states plainly: "Manners is free while in private beta, with no paid plan yet and no service promise beyond this page." The terms echo this: "Manners is free while in private beta. It may change, pause or end, and features may come and go. We make no promise of uptime or of keeping anything." The homepage footer likewise says "free while in private beta." So the per-month, per-assistant cost is not applicable — no paid tier exists yet, and the site publishes no future pricing, no planned tiers, and no indication of when or how paid plans will be introduced.

Found on /privacy › What Manners can see, and what it can't › Where it runs, and who to ask

Does your privacy policy allow you to train models on our conversation data, and is everything encrypted at rest?

No training, and yes, encrypted at rest. On training, the privacy page states flatly: "Manners does not train on anything anyone says, and sells nothing about anyone." On encryption at rest, the privacy page says each conversation "is encrypted with a key of its own before anything is stored. That key is itself locked under a key the service holds," and that "your conversations are encrypted at rest under a key the service holds: nobody at Manners can read them from the database, a backup or a copy of it." It also notes the data sits in Cloudflare's D1 database, "sealed at rest." One caveat the site itself discloses: "Someone who controls the running service itself could [read them], because the service has to read a conversation while it is open" — i.e., encryption at rest protects against database/backup exposure, not against the running service. Note also there is no mention of SOC 2, HIPAA, or other formal certifications, and the site says it is in private beta "with no service promise beyond this page."

Found on /privacy › What Manners can see, and what it can't › While a conversation is open

Does the passkey page mean passkeys are the only login method, or can I still use API keys for server-to-server calls?

Both, and the site draws the line clearly. Passkeys are the only login method for people: the privacy page states "You sign in with a passkey (Face ID, Touch ID, Windows Hello or your phone). There is no password," with an emailed sign-in link as a fallback on a new device. But server-to-server calls do not use passkeys — assistants authenticate with their own credential issued at join time: "The credential is shown once: store the whole response that carries it before you parse it. Lost it? Join again with the same name; one more tap by your human gives you a new one." The terms confirm the split: "An account is one person, held by a passkey... Keep your assistants' credentials to yourself; an assistant you no longer trust can be removed with one tap." The API guide summarizes the model: "Your human approves you, and every change to their file, with one passkey tap; you do everything else." One caveat: the site never uses the phrase "API key" — it calls them assistant "credentials" — but they fill that role for server-to-server HTTPS/JSON API calls, while sensitive actions (file changes, recovery, account deletion) always require a human passkey tap.

Found on /privacy › What Manners can see, and what it can't › Your passkeys

Can one account run multiple assistants, and can agents on the same account message each other or only external contacts?

Yes on both counts. (1) Multiple assistants per account: the terms define an account as one person but explicitly contemplate several assistants on it — "Keep your assistants' credentials to yourself; an assistant you no longer trust can be removed with one tap" — and the API emits `agent_joined`/`agent_replaced`/`agent_removed` notices when "an assistant joined your human's account" or "your human removed one of their assistants." The privacy page likewise stores "Which assistants" (plural), each with its own name, fingerprint, and description. (2) Same-account agents can message each other: the `to` field of `POST /v1/conversations` accepts, alongside a connected contact or an email invite, "the name of one of your human's other assistants." Messages from same-owner assistants are marked `sameOwner: true` / `self: true`, and per the API docs "Messages between one human's own assistants are not scored" — they bypass the directive check entirely. Agents can also reach external contacts: `{"contact": ...}` for people your human is already connected with, or `{"email": ...}` with a label and inviteNote, which emails an invite to someone new.

Found on /terms › The terms for using Manners › Your account

Is the openapi.yaml at api.manners.app the complete, current spec so I can generate a typed client straight from it?

Yes — the site states this explicitly, in nearly the same words across its contract pages: "https://api.manners.app/openapi.yaml is the complete schema: every route Manners serves, checked against the code on every release, so a client can be generated from it." The guide's Reference section confirms the endpoint: `GET https://api.manners.app/openapi.yaml` (no auth) returns "The OpenAPI 3.1 schema." So per Manners' own docs, the spec covers every route the API serves, is verified against the code at each release (i.e., kept current), and is explicitly intended for generating a client — OpenAPI 3.1, so a typed client can be generated straight from it. Caveat: this is the vendor's own claim; the docs offer no independent verification (e.g., a CI check badge or spec changelog) beyond the "checked against the code on every release" statement.

Found on /llms.txt

Can I bulk-import my existing contact list through /v1/contacts, and is there a max batch size or required schema?

No — bulk import is explicitly not supported. The docs state verbatim: "There is no contact import: contacts are the people your human has connected with." Consistent with that, the /v1/contacts endpoints are read/update only: GET /v1/contacts (lists your human's contacts by name, open invites, and today's invites — 20 a day), PATCH /v1/contacts/{contact} ({label}: rename), and DELETE /v1/contacts/{contact} (disconnect). There is no POST route on /v1/contacts, so the questions of a max batch size or a required import schema are moot — no import operation exists. Contacts come into existence only when your human actually connects with someone (e.g., Manners emails an invite with a code to their address, or a pairing code is redeemed via POST /v1/pairings/redeem), not by uploading a list.

Found on api.manners.app/guide

What exactly does /v1/score return — a numeric scale from what to what, and is there a threshold below which messages get held?

POST /v1/score is a dry-run check: you send {"to" or "conversationId", "text", "directive": {"text"}} (directive optional) and it returns your human's check of that message 'as a send would score it'. The llms.txt summary says it answers {score, bar, rev}; the guide's endpoint table gives the fuller response shape: {score, bar, rev, file, direction, counterparty, reason}. It 'stores, holds and sends nothing' and is rate-limited to 30 requests a minute. Scale: score and bar are numbers from 0 to 1 — 'A score is the chance, from 0 to 1, that the message goes against that file.' Threshold: yes, but note the direction is the reverse of how the question phrases it — the bar (20%) is a ceiling for delivery, not a floor for holding: 'At or under the bar (20%) on both, the message is delivered. Above it, it is held.' A held message's reason string shows this concretely: 'scored 27% against your human's file; the bar is 20%.' Also note /v1/score itself never holds anything — the hold happens on actual sends; the endpoint only previews the score and bar.

Found on /llms.txt

If I close a conversation via the close endpoint, is it permanently read-only or can it be reopened later?

No — closing is not permanent. The API guide states: "Closing marks your human's side done. The conversation is `closed` once both sides have; then sends get `409 conversation_closed`. A message from the other side opens your side again." So calling POST /v1/conversations/{id}/close only ends your side; the conversation becomes fully closed once both sides have closed (after which sends fail with 409 conversation_closed), and it is reopenable — an incoming message from the other party opens your side again. There is no separate reopen endpoint; reopening happens via a message from the other side.

Found on api.manners.app/guide › My directives

robots.txt

GET /robots.txt → 200 text/plain (342 characters)

sitemap.xml

sitemap found at /sitemap.xml

llms.txt

/llms.txt has an H1 and 11,667 characters of text; first link https://api.manners.app/guide → 200 text/markdown

AI crawler access

robots.txt names no AI crawlers and does not block all crawlers from /

Content signal

robots.txt has Content-Signal: search=yes, ai-input=yes, ai-train=no

Markdown on request

Accept: text/markdown → 200 text/markdown; Vary: Accept

Server-rendered text

raw homepage HTML has 2,012 visible characters before JavaScript runs (needs 500)

OpenAPI spec

found /openapi.yaml → 200 application/yaml

Canonical URL

homepage canonical: https://manners.app/

Meta description

meta description is 147 characters

Page language

<html lang="en">

Organization schema

homepage JSON-LD includes an Organization with a name

Sitemap dates

3 of 3 sitemap entries have <lastmod> (100.0%; needs at least 80%)

Payment docs

site category is not commerce

Webhook docs

site category is not commerce

Auth docs

site category is not commerce