# Kadoink — full reference for agents > Kadoink gathers people in real time. Put up to 9 people in a grid, press one > button, and everyone is reached at once — video, voice, SMS, push, email, or a > plain join link. "To kadoink" is to gather. This is the EXPANDED reference: every MCP tool, every REST endpoint, every command verb, and the error contract, so you can learn the whole surface in one fetch. The short index is at https://www.kadoink.com/llms.txt. This document is generated from the running server, so it always matches what is actually deployed. ## How to connect MCP (preferred for agents): POST JSON-RPC to https://www.kadoink.com/mcp — Streamable HTTP, stateless, 14 tools. REST: https://www.kadoink.com/api/v1, 168 operations. Authenticate either way with `Authorization: Bearer kdk_...`. Unauthenticated requests to /mcp answer 401 with an RFC 9728 `WWW-Authenticate` header pointing at https://www.kadoink.com/.well-known/oauth-protected-resource, from which you can run the full OAuth 2.1 flow: dynamic client registration (https://www.kadoink.com/oauth/register), then authorize with PKCE S256, then exchange the code at https://www.kadoink.com/oauth/token. Discovery without parsing HTML: every response carries an RFC 8288 `Link` header (service-desc, service-doc, api-catalog, mcp-server, describedby), and https://www.kadoink.com/.well-known/api-catalog is an RFC 9727 linkset. `HEAD` works on every GET route, so you can read those headers without downloading a body. Any page also answers `Accept: text/markdown` with markdown instead of HTML. ## Permissions — read this before acting Tokens carry scopes. Connectors get `read write` by default; `outreach` is granted only when a human explicitly approves it. - `read` — GET anything the user can see. - `write` — create and update on the user's behalf. - `outreach` — place real phone calls and send real SMS. This spends the user's money and rings other people's phones. Confirm the exact action with your user before every outreach call, every time. Whatever the scope, an MCP tool call is executed through /api/v1 in-process, so you inherit the same rate limits, validation and permission gates as the phone app. You can never do something the signed-in user could not do themselves. ## MCP tools (14) ### Read tools Safe to call while exploring; no side effects. - `get_command_guide()` The reference for run_command's DSL: every verb (call, text, kadoink, status, iblast, …) with syntax and examples. Read this before composing a run_command line you haven't used in this conversation. - `get_feed(limit?, before_id?)` Read the signed-in user's follow feed (status posts from people they follow, newest first). Use before_id (the smallest id from the previous page) to page further back; has_more says whether another page exists. - `get_inbox(limit?, offset?)` Read the signed-in user's unified inbox (texts, voicemails, videomail, missed calls), newest first, with unread counts. Call when the user asks what's new, what they missed, or about a specific message. - `get_profile(ktag)` Fetch a person's public profile by their ktag (identity tag name, without the * sigil — e.g. 'benji'). Call after search_people when the user asks about a specific person: bio, modules, media, live signals. - `list_widgets()` List the signed-in user's widgets (countdowns, birthday, super-call, phone-cast, music-call, ID card, group buzz — each with its embed URL). Call before anything widget-related so you reference real widget ids. - `search_people(query)` Search Kadoink people/tags by name (partial match). Call this when the user names a person or tag you don't have an exact ktag for. Returns public tags plus discoverable protected accounts (is_protected=true shows a lock; follow requests to those need approval). - `whoami()` Get the signed-in user's own account: username, identity tag, profile fields, settings. Call this first when you need to know who you are acting as, or to check account state before other calls. ### Write tools These change the user's account. Confirm intent before calling. - `create_event(title, schedule, description?, all_day?, duration_minutes?, place?, rrule?)` Create a calendar event for the signed-in user. schedule is an ISO datetime (UTC or with offset — e.g. '2026-08-01T18:00:00Z'). place is a free-text venue/address (geocoded to a map pin best-effort). rrule is an optional iCal recurrence like 'FREQ=WEEKLY;BYDAY=MO'. Confirm date, time, and timezone intent with the user before creating. - `follow(ktag_id)` Follow a tag/person by ktag id (from search_people or get_profile). Returns state 'following' (public) or 'requested' (protected account — the owner must approve). Safe to repeat. - `post_status(body, media_url?)` Post a status to the signed-in user's timeline (their followers see it in their feeds). Call when the user asks to post, share, or announce something. media_url optionally attaches a direct image/audio/video link or a YouTube/Vimeo URL. Confirm wording with the user before posting. - `reply_to_status(post_id, body)` Reply to a status post (the author is notified). Use post ids from get_feed. Confirm wording with the user before sending. - `send_dm(to, message)` Send a private direct message to a person by their ktag/username. Opens (or reuses) the 1:1 thread: mutual follows chat immediately; otherwise the thread lands as a pending request on their side (capped at 3 messages until they accept). Confirm wording with the user before sending. Returns the thread plus the posted message. - `unfollow(ktag_id)` Stop following a tag/person by ktag id. Safe to repeat. ### Outreach tools These reach REAL PEOPLE and spend the user's calling budget. They require the `outreach` scope, which is granted only by explicit human consent. Restate exactly what will happen and get confirmation before every call. - `run_command(command)` Run one line of the Kadoink command DSL as the signed-in user — the same language as the SMS/voice interface. This is the doorway to REAL OUTREACH: verbs like 'call', 'text', 'kadoink', and 'iblast' place actual phone calls / send actual SMS to real people, drawing from the user's telephony budget. ALWAYS restate exactly what will happen and get the user's explicit confirmation before running an o ## The command DSL `run_command` speaks Kadoink's command language — the same one the SMS and voice interfaces use. Verbs that reach people need the `outreach` scope. - **add** Ring another person (contact name, username, number, or *tag) into the call you're already on. Syntax: `add WHO` Example: `add *bob` - **block** Block a user — they can't follow your tags or interact with you. Syntax: `block *who` Example: `block *spammy` - **call** (aliases: ccall, rcall) Call one or more people — contact names, group names, usernames, phone numbers and *tags, in any mix and order (`call fam bob 5551234567`). A plain word is looked up in your contacts and groups first, then as a Kadoink username. Bridges you and them. Schedule with `at` (your local time). Syntax: `call WHO [WHO ...] [at TIME]` Example: `call alice at 5pm` - **eshare** Email a media tag link to every follower of your tag who has an email on file. Syntax: `eshare *MYTAG.MEDIA` Example: `eshare *me.demo` - **follow** (aliases: sub, subscribe) Subscribe to broadcasts from a public tag. Syntax: `follow *who` Example: `follow *alice` - **help** (aliases: ?, h) Get a short reminder of available commands. Syntax: `help` Example: `help` - **iblast** Text every follower of your tag at once. Syntax: `iblast *MYTAG MESSAGE` Example: `iblast *me studio session at 8pm tonight` - **ishare** Share an audio media tag with every follower of your tag. Syntax: `ishare *MYTAG.MEDIA` Example: `ishare *me.demo` - **kadoink** (aliases: dk) Kadoink someone — reach them everywhere at once (app notification, text, and email) with a link where THEY choose how to connect: join with video, get a phone call, or just chat. Nothing rings. Same targets as `call` (name, number, *tag, or a group). Schedule with `at` (your local time). Syntax: `kadoink WHO [at TIME]` Example: `kadoink family` - **record** Kadoink calls you. Press 1 to start recording, # to finish. Syntax: `record [TAGNAME]` Example: `record demo1` - **share** Send a recipient a link to play a public media tag. Syntax: `share *who.MEDIA to *recipient` Example: `share *alice.song to *bob` - **sharelocation** (aliases: shareloc, sharemylocation) Get a public link that shows your LIVE spot on a mini map — anyone holding it can video, call, or message you through it. Expires after the duration (default 1 hour); revoke any time on /location. Syntax: `sharelocation [15m|1h] [LABEL]` Example: `sharelocation 1h for Mom` - **status** Set or read a tag's status. With no args, returns your own. Syntax: `status [MESSAGE | *who]` Example: `status at the coffee shop` - **text** (aliases: t, txt) Send a text to one or more tags / phone numbers. Schedule with `at` (your local time). Syntax: `text *who [*who2 ...] BODY [at TIME]` Example: `text *alice meeting moved to 4pm` - **unblock** Reverse a previous block. Syntax: `unblock *who` Example: `unblock *spammy` - **unfollow** (aliases: bye, drop, end, leave, quit, stop, unsub, unsubscribe) Stop following a tag. Syntax: `unfollow *who` Example: `unfollow *alice` - **vcall** (aliases: vc, videocall) Start a VIDEO call — same targets as `call` (name, number, *tag, or a group), but opens an app/browser video room. You join via the link in the reply; they're rung in-app or texted a link. Schedule with `at` (your local time). Syntax: `vcall WHO [at TIME]` Example: `vcall *alice at 5pm` - **vrecord** (aliases: videorecord, vrec) Record yourself on VIDEO in the app — the reply gives you a one-tap link to a private recording room. When you finish, the clip is saved to your account, and tagged as *TAG media on your profile if you gave a *tag. Syntax: `vrecord [*TAG]` Example: `vrecord *dailyrant` ## REST API (168 operations) Base: https://www.kadoink.com/api/v1 — bearer auth, JSON in and out. Full schema: https://www.kadoink.com/openapi.json. Human reference: https://www.kadoink.com/apidocs. Conventions: - Errors always carry `error.code` (machine) and `error.message` (human). - Lists return `items` plus `has_more`; feeds page backwards with `before_id`, address-book style lists with `limit`/`offset`. - Every response carries `X-Request-Id`; quote it when reporting a problem. - Money-spending POSTs accept `Idempotency-Key` so a retried request cannot place a second set of calls. - Timestamps are UTC ISO-8601 with a `Z` suffix. Phone numbers are E.164. - Identity tags ("ktags") serialize without their `*` sigil. Error codes you should handle: - `token_missing` / `token_invalid` — authenticate, or refresh the token. - `insufficient_scope` — the token lacks `read`, `write` or `outreach`; `meta.required_scope` names which. Do not retry without a new grant. - `mobile_unverified` — the account must finish phone verification in the app before resource endpoints work. Nothing you can fix from here. - `rate_limited` — back off; `Retry-After` and `meta.retry_after_seconds` say how long. - `validation_failed` — `fields` maps each bad field to the reason. - `payload_too_large` — `meta.max_bytes` is the ceiling. - `not_found` — also returned for resources the caller doesn't own, so it never reveals whether something exists. ### /abuse-reports - `POST /api/v1/abuse-reports` — Submit Abuse Report ### /auth - `POST /api/v1/auth/forgot` — Forgot - `POST /api/v1/auth/login` — Login - `POST /api/v1/auth/login/resend` — Login Resend - `POST /api/v1/auth/login/verify` — Login Verify - `POST /api/v1/auth/logout` — Logout - `POST /api/v1/auth/magic-link` — Magic Link - `POST /api/v1/auth/magic-link/consume` — Magic Link Consume - `POST /api/v1/auth/refresh` — Refresh - `POST /api/v1/auth/register` — Register - `POST /api/v1/auth/register/resend` — Register Resend - `POST /api/v1/auth/register/verify` — Register Verify - `POST /api/v1/auth/reset` — Reset - `DELETE /api/v1/auth/sessions` — Revoke All Sessions - `GET /api/v1/auth/sessions` — List Sessions - `DELETE /api/v1/auth/sessions/{session_id}` — Revoke Session - `GET /api/v1/auth/username-available` — Username Available ### /blocks - `GET /api/v1/blocks` — List Blocks - `POST /api/v1/blocks` — Create Block - `DELETE /api/v1/blocks/{blocked_user_id}` — Delete Block ### /calendar - `GET /api/v1/calendar/events` — Calendar Events List - `POST /api/v1/calendar/events` — Calendar Event Create - `DELETE /api/v1/calendar/events/{event_id}` — Calendar Event Delete - `PATCH /api/v1/calendar/events/{event_id}` — Calendar Event Update - `POST /api/v1/calendar/events/{event_id}/exdates` — Calendar Event Add Exdate - `DELETE /api/v1/calendar/events/{event_id}/share` — Calendar Event Share Revoke - `POST /api/v1/calendar/events/{event_id}/share` — Calendar Event Share - `DELETE /api/v1/calendar/feed` — Calendar Feed Revoke - `GET /api/v1/calendar/feed` — Calendar Feed Get - `POST /api/v1/calendar/feed/regenerate` — Calendar Feed Regenerate - `POST /api/v1/calendar/sync` — Calendar Sync - `POST /api/v1/calendar/sync/ack` — Calendar Sync Ack ### /call-history - `GET /api/v1/call-history` — Call History - `GET /api/v1/call-history/{conference_id}/chat` — Call Transcript ### /calls - `POST /api/v1/calls` — Start Call - `DELETE /api/v1/calls/active` — End Call - `GET /api/v1/calls/active` — Active Call - `PATCH /api/v1/calls/active` — Update Call - `POST /api/v1/calls/active/bridge-phone` — Add Bridge Phone - `POST /api/v1/calls/active/participants` — Add Call Participant - `POST /api/v1/calls/{join_code}/call-me` — Call Me - `GET /api/v1/calls/{join_code}/chat` — Call Chat Scrollback - `POST /api/v1/calls/{join_code}/chat` — Call Chat Post - `POST /api/v1/calls/{join_code}/chat/media` — Call Chat Post Media - `POST /api/v1/calls/{join_code}/chat/typing` — Call Chat Typing - `POST /api/v1/calls/{join_code}/sfu-grant` — Sfu Grant ### /commands - `POST /api/v1/commands` — Run Command - `GET /api/v1/commands/guide` — Command Guide - `POST /api/v1/commands/voice` — Transcribe Command ### /contacts - `GET /api/v1/contacts` — Contacts List - `POST /api/v1/contacts` — Contact Create - `POST /api/v1/contacts/import` — Import Commit - `POST /api/v1/contacts/import/preview` — Import Preview - `GET /api/v1/contacts/imports` — Imports List - `POST /api/v1/contacts/imports/{batch_id}/rollback` — Imports Rollback - `DELETE /api/v1/contacts/{contact_id}` — Contact Delete - `GET /api/v1/contacts/{contact_id}` — Contact Detail - `PATCH /api/v1/contacts/{contact_id}` — Contact Update ### /dm - `GET /api/v1/dm/threads` — Dm Threads - `POST /api/v1/dm/threads` — Dm Open - `GET /api/v1/dm/threads/{thread_id}` — Dm Thread Get - `POST /api/v1/dm/threads/{thread_id}/accept` — Dm Accept - `GET /api/v1/dm/threads/{thread_id}/chat` — Dm Chat List - `POST /api/v1/dm/threads/{thread_id}/chat` — Dm Chat Post - `DELETE /api/v1/dm/threads/{thread_id}/chat/{message_id}` — Dm Chat Delete - `POST /api/v1/dm/threads/{thread_id}/decline` — Dm Decline - `GET /api/v1/dm/unread-count` — Dm Unread Count ### /feed - `GET /api/v1/feed` — Feed ### /files - `POST /api/v1/files/{file_id}/stream-token` — Mint Stream Token - `GET /api/v1/files/{id}/stream` — File Stream ### /follow-requests - `GET /api/v1/follow-requests` — List Incoming Follow Requests - `GET /api/v1/follow-requests/count` — Follow Requests Count - `GET /api/v1/follow-requests/outgoing` — List Outgoing Follow Requests - `PUT /api/v1/follow-requests/{request_id}` — Act On Follow Request ### /followers - `GET /api/v1/followers` — My Followers - `DELETE /api/v1/followers/{follower_user_id}` — Remove My Follower ### /follows - `GET /api/v1/follows` — Follows List ### /grid - `GET /api/v1/grid` — Grid - `DELETE /api/v1/grid/calls` — End Grid Call - `POST /api/v1/grid/calls` — Start Grid Call - `POST /api/v1/grid/members` — Grid Add Member - `DELETE /api/v1/grid/members/{contact_id}` — Grid Remove Member ### /group-invites - `POST /api/v1/group-invites/{invite_id}/accept` — Group Invite Accept - `POST /api/v1/group-invites/{invite_id}/decline` — Group Invite Decline ### /groups - `GET /api/v1/groups` — Groups List - `POST /api/v1/groups` — Group Create - `DELETE /api/v1/groups/{group_id}` — Group Delete - `GET /api/v1/groups/{group_id}` — Group Detail - `PATCH /api/v1/groups/{group_id}` — Group Update - `GET /api/v1/groups/{group_id}/chat` — Group Chat List - `POST /api/v1/groups/{group_id}/chat` — Group Chat Post - `DELETE /api/v1/groups/{group_id}/chat/{message_id}` — Group Chat Delete - `DELETE /api/v1/groups/{group_id}/members/{contact_id}` — Group Remove Member - `PUT /api/v1/groups/{group_id}/members/{contact_id}` — Group Add Member - `GET /api/v1/groups/{group_id}/widgets` — Group Widgets List ### /home - `GET /api/v1/home` — Home Dashboard - `GET /api/v1/home/group-chat` — Home Group Chat ### /inbox - `GET /api/v1/inbox` — Inbox List - `GET /api/v1/inbox/unread-count` — Inbox Unread Count - `DELETE /api/v1/inbox/{message_id}` — Inbox Delete - `PATCH /api/v1/inbox/{message_id}` — Inbox Update ### /invites - `POST /api/v1/invites` — Create Invite - `DELETE /api/v1/invites/{invite_id}` — Revoke Invite ### /ktags - `GET /api/v1/ktags` — Ktags List - `POST /api/v1/ktags` — Ktag Create - `GET /api/v1/ktags/search` — Ktags Search - `DELETE /api/v1/ktags/{ktag_id}` — Ktag Delete - `GET /api/v1/ktags/{ktag_id}` — Ktag Detail - `PATCH /api/v1/ktags/{ktag_id}` — Ktag Update - `DELETE /api/v1/ktags/{ktag_id}/follow` — Ktag Unfollow - `PUT /api/v1/ktags/{ktag_id}/follow` — Ktag Follow - `GET /api/v1/ktags/{ktag_id}/followers` — Ktag Followers - `POST /api/v1/ktags/{ktag_id}/media` — Ktag Add Media - `DELETE /api/v1/ktags/{ktag_id}/media/{file_id}` — Ktag Remove Media ### /location - `GET /api/v1/location/config` — Location Config - `GET /api/v1/location/discover` — Location Discover - `GET /api/v1/location/links` — List Location Links - `POST /api/v1/location/links` — Create Location Link - `DELETE /api/v1/location/links/{link_id}` — Revoke Location Link - `GET /api/v1/location/people` — Location People - `POST /api/v1/location/report` — Report Location - `GET /api/v1/location/settings` — Get Location Settings - `PUT /api/v1/location/settings` — Put Location Settings ### /me - `DELETE /api/v1/me` — Delete Account - `GET /api/v1/me` — Me - `PATCH /api/v1/me` — Update Me - `POST /api/v1/me/avatar` — Set Avatar - `GET /api/v1/me/im-identities` — List Im Identities - `POST /api/v1/me/im-identities` — Add Im Identity - `DELETE /api/v1/me/im-identities/{im_id}` — Delete Im Identity - `GET /api/v1/me/invites` — List Invites - `GET /api/v1/me/mobile` — Get Mobile - `PUT /api/v1/me/mobile` — Set Mobile - `POST /api/v1/me/mobile/codes` — Send Mobile Code - `POST /api/v1/me/mobile/verify` — Verify Mobile - `PUT /api/v1/me/password` — Change Password - `PUT /api/v1/me/timezone` — Report Timezone ### /notifications - `GET /api/v1/notifications` — Notifications List - `POST /api/v1/notifications/read-all` — Notifications Read All - `GET /api/v1/notifications/unread-count` — Notifications Unread Count - `DELETE /api/v1/notifications/{note_id}` — Notifications Delete - `PATCH /api/v1/notifications/{note_id}` — Notifications Update ### /profiles - `GET /api/v1/profiles/{ktag}` — Public Profile - `GET /api/v1/profiles/{ktag}/comments` — List Comments - `POST /api/v1/profiles/{ktag}/comments` — Post Comment - `DELETE /api/v1/profiles/{ktag}/comments/{comment_id}` — Delete Comment - `GET /api/v1/profiles/{ktag}/live` — Public Profile Live ### /push-token - `POST /api/v1/push-token` — Register Push Token ### /realtime - `POST /api/v1/realtime/grant` — Realtime Grant ### /recordings - `GET /api/v1/recordings` — List Recordings ### /scheduled-jobs - `GET /api/v1/scheduled-jobs` — Scheduled Jobs List - `DELETE /api/v1/scheduled-jobs/{job_id}` — Scheduled Job Cancel ### /statuses - `GET /api/v1/statuses` — Status List - `POST /api/v1/statuses` — Status Create - `DELETE /api/v1/statuses/replies/{reply_id}` — Reply Delete - `DELETE /api/v1/statuses/{post_id}` — Status Delete - `PATCH /api/v1/statuses/{post_id}` — Status Update - `GET /api/v1/statuses/{post_id}/replies` — Reply List - `POST /api/v1/statuses/{post_id}/replies` — Reply Create ### /videomail - `POST /api/v1/videomail/{handle}` — Videomail Send ### /widgets - `GET /api/v1/widgets` — Widgets List - `POST /api/v1/widgets` — Widget Create - `DELETE /api/v1/widgets/{widget_id}` — Widget Delete - `PATCH /api/v1/widgets/{widget_id}` — Widget Update - `GET /api/v1/widgets/{widget_id}/chat` — Widget Chat List - `POST /api/v1/widgets/{widget_id}/chat` — Widget Chat Post - `DELETE /api/v1/widgets/{widget_id}/chat/{message_id}` — Widget Chat Delete - `GET /api/v1/widgets/{widget_id}/embed` — Widget Embed ## Pages - https://www.kadoink.com/ — home - https://www.kadoink.com/about — what Kadoink is - https://www.kadoink.com/howitworks — the grid, the channels, the kadoink - https://www.kadoink.com/people — public directory of profiles and identity tags - https://www.kadoink.com/videos — short guide videos - https://www.kadoink.com/download — mobile and desktop apps - https://www.kadoink.com/apidocs — REST reference - https://www.kadoink.com/commandGuide — the command language - https://www.kadoink.com/mediakit — brand assets - https://www.kadoink.com/privacy, https://www.kadoink.com/termsofuse, https://www.kadoink.com/rulesoftheroad