For AI agents — set up and use Notiamo from code

The flow

Ask for an account for your owner: send POST https://my.notiamo.com/api/agent/signup with email, name, agent, locale and, if you have them, company, siteUrl and referral. The answer holds requestId, pollSecret and pollAfterSeconds.
Tell the owner to open the confirmation email Notiamo sends and to confirm. Nothing happens until they do.
Poll GET https://my.notiamo.com/api/agent/signup/{requestId} with Authorization: Bearer <pollSecret> every pollAfterSeconds seconds (5 at the moment). The status is pending, confirmed, expired or reported.
When the status is confirmed, the answer holds your key (token, starting with ntm_) and mcpUrl, once. Store the key at once: later polls do not return it. Claim it within 7 days of the confirmation.
Connect to the MCP server at https://my.notiamo.com/api/mcp with the header Authorization: Bearer ntm_….
Call list_sites (or find_site) to find the site made for you: it already uses your siteUrl as its address. If the address is missing or wrong, call update_site_address. Then get_install, install the snippet, and check_install. Use create_client and create_site only when the plan has room (paid plans or the Studio trial); create_site needs a clientId from list_clients.
Then work on the comments: list_comments, get_comment, reply and set_status.

Poll at most 30 times per minute per request. A wrong or unknown id or secret returns 404 with {"code":"not_found"}.

Example: ask for an account

curl -X POST https://my.notiamo.com/api/agent/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","name":"Ada Owner","agent":"my-agent","locale":"en","siteUrl":"https://example.com"}'

The free plan

The free plan allows 1 client, 1 site, 3 people (team members, client members and pending invites, each email once) and 1 public address per site. After the site’s first public comment, the address can be changed once. A client and a site already exist when the account opens.

The widget shows a Notiamo badge on the free plan.

Keep the comment line above the script tag. The terms of the free plan require it:

<!-- Notiamo (notiamo.com): website feedback. Free plan: keep this line. -->

A plan_limit refusal tells you which limit you reached and what to do next.

Refusals

Sign-up and the tools answer with a code. The sign-up codes come with an HTTP status:

Code	HTTP status	What it means
`signup_blocked`	403	The network is not allowed to sign up. The owner signs up themselves.
`rate_limited`	429	Too many requests. Wait for `retryAfter` seconds.
`agent_signup_paused`	503	Sign-up by agents is paused for now. The owner signs up themselves.
`agent_signup_closed`	503	Sign-up by agents is closed. The owner signs up themselves.
`account_exists`	409	This email already has an account. The owner logs in and creates a key in Settings > Keys.
`email_not_accepted`	422	This email address cannot be used. The owner signs up themselves.
`invalid_input`	422	A field is not valid. `field` names it.
`plan_limit`	402	A plan limit was reached. Returned by the MCP tools, with the next step (`start_trial` or `get_payment_link`).

Show refusals to your owner. Never work around them.

Paying

list_plans shows the plans (see the pricing page for the prices). start_trial starts the trial, once per workspace. Pricing

get_payment_link makes a payment link that the owner opens and pays. You never handle card data.

Referral

If a Notiamo badge or link brought you here, pass its code in the referral field of the JSON body of the sign-up. The ?via=<code> form is only for the sign-up web link that people open.

The MCP tools

After connecting you can call:

whoami list_sites find_site list_comments get_comment reply set_status assign list_team get_account list_plans get_billing start_trial list_clients create_client create_site update_site_address get_install check_install invite get_payment_link

Notiamo for AI agents