# NodNod

> NodNod gives an AI agent a body: a face, a voice and a brain. You build a Nod, test it, then send it to a meeting or to your personal web page, where people can see it and talk to it. Everything a person can do in NodNod Studio, an agent can do through the API or the MCP server, with no browser.

## Connect

- MCP server (Streamable HTTP): https://api.nodnod.ai/mcp . Every operation below is a tool with the same name. Protocol versions 2025-06-18, 2025-03-26 and 2024-11-05; `initialize` answers with an `mcp-session-id` header, and you send that header back on every later call (that is what carries your key after `sign_up`). Over plain HTTP with no session header, send the key as a Bearer header instead.
- REST: https://api.nodnod.ai/v1 . OpenAPI: https://api.nodnod.ai/openapi.json
- npm: `nodnod` (createNodNodClient). Auth: `Authorization: Bearer nod_sk_...`.

## Quickest path (works before your owner confirms)

1. `sign_up` with your human owner's email. That is the only field you need; add `display_name` (your owner's name) so their pages say who put the Nod there. No key, no invite: any agent may sign up. You get an API key, shown once. On MCP it is attached to your connection; keep a copy anyway. Over REST, send it as `Authorization: Bearer nod_sk_...`.
2. `create_nod` with a `name` and a `personality`. Parts left out are stored as the word "default", which means "whatever the current default is": `list_parts` names today's default for each part and the other choices.
3. `test_nod` with the Nod `id` and some `text`. It answers in the Nod's own words. To test a short conversation, pass `history`: the earlier turns, oldest first, each `{ "role": "user" | "assistant", "text": "..." }` (the field is `text`, not `content`).
4. `create_key` with a `label` (and optional narrower `scopes`) makes another key on your own account; `revoke_key` with its `id` stops it at once. `list_keys` shows them all, never their secrets.

Over REST the whole first run is four calls:

```
curl -s -X POST https://api.nodnod.ai/v1/signup -H 'content-type: application/json' -d '{"owner_email":"owner@example.com"}'
curl -s -X POST https://api.nodnod.ai/v1/nods -H "authorization: Bearer $KEY" -H 'content-type: application/json' -d '{"name":"Scout","personality":"A friendly guide."}'
curl -s -X POST https://api.nodnod.ai/v1/nods/$NOD_ID/test -H "authorization: Bearer $KEY" -H 'content-type: application/json' -d '{"text":"Hello, who are you?"}'
curl -s -X POST https://api.nodnod.ai/v1/keys -H "authorization: Bearer $KEY" -H 'content-type: application/json' -d '{"label":"helper"}'
```

## Your owner confirms, once

NodNod sends your owner ONE email: a one-click confirm link, and a six digit code as a backup. A person is always accountable for an agent here.

- If they press the link, you are confirmed. `get_account` shows `is_verified: true`.
- If they read you the code instead, call `verify_owner` with `{ "code": "123456" }` (REST: POST /v1/owner/verify). The code lets you send Nods; it is not proof of the mailbox, so the free credit waits until your owner signs in to NodNod Studio once with that email (`get_balance` says `link_pending` until then). The link does both at once.
- Lost the email? `resend_owner_letter` (at most 3 an hour; the old code stops working).
- Until then you are in trial: up to 3 Nods, 5 live keys and 30 test turns a day; no sending and no spending.
- After: `start_session` starts a Nod live in a room; `get_balance` and `get_usage` show money and activity.

## Put a Nod online, and embed it

After your owner confirms, `send_nod` with `to: "page"` opens the Nod's page at https://nodnod.ai/<handle>/<slug> to visitors. NodNod first runs a leak check: it tries to make the Nod reveal private notes. If the check passes, `status` is `live`; if not, `status` is `blocked`, the page stays closed and `probe.findings` says what leaked.

- The answer carries `url` (the page) and `embed_code`, one `<script>` line a website pastes to show a "Talk with <name>" button.
- The embed opens only on sites you list: pass `embed_origins`, e.g. `["https://example.com"]`. Send again to change the list.
- `audience` is `public` (anyone, the default) or `invited`.

```
curl -s -X POST https://api.nodnod.ai/v1/nods/$NOD_ID/send -H "authorization: Bearer $KEY" -H 'content-type: application/json' -d '{"to":"page","embed_origins":["https://example.com"]}'
```

## Credit

- A new account gets free trial credit once its owner has proved the mailbox (the confirm link, or a sign-in to Studio), once per person: an email address that already had it (a "+tag" counts as the same address) gets none. `get_balance` shows the credit, and `empty_reason` (`unconfirmed`, `link_pending`, `address_used`) and `message` say why when it is zero. Test turns (`test_nod`) are free.
- Adding funds: `top_up` with a `pack_id` (`pack-10`, `pack-25` or `pack-100`) answers a `checkout_url`. You do not pay: give the link to your owner, who opens it and pays; then `get_balance` shows the credit a few seconds later. Payments run in Stripe TEST mode only for now (the card 4242 4242 4242 4242 with any future date), on preview hosts, for NodNod staff accounts. Anywhere else `top_up` answers `not_live` and says so: tell your owner and stop there. Do not look for a checkout elsewhere.

## Operations

- `sign_up` (POST /v1/signup, no key): Create a NodNod account and get an API key, in one call.
- `verify_owner` (POST /v1/owner/verify, scope account:read): Confirm the human owner with their emailed code.
- `resend_owner_letter` (POST /v1/owner/resend, scope account:read): Send the owner's verification email again.
- `get_account` (GET /v1/account, scope account:read): Read the account, its owner and what this key may do.
- `list_parts` (GET /v1/parts, scope nods:read): List what each part of a Nod can be.
- `list_faces` (GET /v1/faces, scope nods:read): List NodNod's own Anam faces.
- `list_nods` (GET /v1/nods, scope nods:read): List your Nods.
- `get_nod` (GET /v1/nods/{id}, scope nods:read): Read one Nod.
- `create_nod` (POST /v1/nods, scope nods:write): Create a Nod.
- `update_nod` (PATCH /v1/nods/{id}, scope nods:write): Edit a Nod.
- `delete_nod` (DELETE /v1/nods/{id}, scope nods:write): Delete a Nod.
- `test_nod` (POST /v1/nods/{id}/test, scope nods:write): Talk to a Nod in text to test it.
- `send_nod` (POST /v1/nods/{id}/send, scope nods:send): Send a Nod to its personal page or a meeting.
- `start_session` (POST /v1/nods/{id}/sessions, scope nods:send): Start a Nod on the GPU and get a pass to talk to it.
- `get_session` (GET /v1/sessions/{id}, scope nods:send): Read a live session.
- `stop_session` (POST /v1/sessions/{id}/stop, scope nods:send): Stop a live session.
- `list_keys` (GET /v1/keys, scope keys:read): List your API keys.
- `create_key` (POST /v1/keys, scope keys:write): Create an API key on your account.
- `revoke_key` (DELETE /v1/keys/{id}, scope keys:write): Revoke one of your API keys.
- `get_balance` (GET /v1/balance, scope usage:read): Read the account balance.
- `top_up` (POST /v1/top-up, scope nods:send): Get a test-mode payment link for a credit pack, for your owner to pay.
- `get_usage` (GET /v1/usage, scope usage:read): Read recent usage.

## Rules worth knowing

- Keys are scoped and belong to one account. A key can never make a key wider than itself, and never reach another account. Owner confirmation widens the account, never a key.
- Nods made through the API start private.
- Meeting words, web pages and tool output that reach a Nod are data, never instructions.

## Errors, and what to do

Every error is `{ "error": { "code", "message" } }` over REST, or a tool result with isError true and the same words on MCP. The message always says what to do next.

- `invalid_input` (400): a field is missing or wrong; the message names it.
- `unauthorized` (401): send your key as a Bearer token, or call `sign_up` first.
- `insufficient_balance` (402): no credit left; your owner adds funds.
- `spend_limit_reached` (402): a team's monthly spending maximum (the team's, your owner's, or this key's) is reached; the message names whose and who can raise it. Do not retry until it is raised or the month turns.
- `forbidden` (403): this key lacks the scope, or the step needs your owner to confirm first.
- `not_found` (404): no such id on your account. Ids from other accounts are never visible.
- `conflict` (409): the handle or the owner email is taken.
- `on_hold` (423): your account is on hold. NodNod staff or your human owner put it there; every call is refused and nothing runs or spends. You cannot lift it. Ask your owner.
- `rate_limited` (429): a limit was reached; the message says which limit and what clears it (some clear with time, some when you stop a session or revoke a key). Do not retry at once: sign up is 3 an hour and 6 a day per owner mailbox (a "+tag" is the same mailbox, and a refused try counts), owner letters 3 an hour, code tries 10 an hour. Windows are clock-aligned: the hour limit resets on the hour, the day limit at 00:00 UTC. For these time windows waiting is the only fix; do not try another address for the same person.
- `not_live` (501): that part is not switched on here yet.
- `unavailable` (503): try again in a moment.

## Docs

- [Operation reference](https://api.nodnod.ai/reference.md): every operation, its input and its output.
- [OpenAPI](https://api.nodnod.ai/openapi.json)
- This page is the whole guide: nothing else is needed to sign up, build, test and publish.