Notiamo for AI agents
Everything wey AI agent need to open free account for im owner, put the widget for website and handle the comments and the work, without browser.
The flow
- Ask for account for your owner: send
POST https://my.notiamo.com/api/agent/signupwithemail,name,agent,localeand, if you get dem,company,projectUrl(the website address) andreferral. The answer go carryrequestId,pollSecretandpollAfterSeconds. - Tell the owner make e open the confirmation email wey Notiamo send and confirm. Nothing go happen until e do am.
- Poll
GET https://my.notiamo.com/api/agent/signup/{requestId}withAuthorization: Bearer <pollSecret>everypollAfterSecondsseconds. The status napending,confirmed,expiredorreported. - When the status na
confirmed, the answer go carry your key (token, wey start withntm_) andmcpUrl, one time. Store the key at once: later polls no dey return am. Claim am within 7 days of the confirmation. - Connect to the MCP server for
https://my.notiamo.com/api/mcpwith the headerAuthorization: Bearer ntm_…. If your app support MCP sign-in, e fit use Sign in with Notiamo instead of key (see below). - Call
list_projects(orfind_project) to find the project wey dem make for you: e don already use yourprojectUrlas im address. If the address no dey or e wrong, callupdate_project_address. Thenget_install, install the snippet, andcheck_install. Usecreate_workspaceandcreate_projectonly when the plan get room (paid plans or the Studio trial);create_projectneedworkspaceIdfromlist_workspaces. Workspace dey group projects, for example one for each client. Project fit no get web address (leaveoriginout): then e go get tasks, work and news, but no widget. After di install,get_badgego give you di footer badge: small Notiamo logo for di website footer wey go open di review tools for reviewers and na ordinary link to Notiamo for everybody else, for di website language (update_project_language, orlanguageforcreate_project). - Then work on the comments:
list_comments,get_comment,replyandset_status. To check for news, passsincetolist_comments: UTC time wey end withZ(like2026-10-17T08:00:00Z), or thecursorfrom im last answer. You go get only wetin change, for one project or, withoutprojectId, for all your projects. Keep the newcursorfor the next check, followmore: trueat once, and dedupe byid: item fit come two times. - For another organization, call
create_organizationwithname: the owner go be the admin and go get email, and the answer go carry newtokenfor that organization only. E dey free if the owner no get free organization, else e need plan: callget_payment_linkwith the new token, orstart_trialfor the 14-day Studio trial (one time per person; the owner go open the link and put card). Daily limit dey; the refusal go tell you when you fit try again. - To move project go another workspace (
kindproject,projectId,toWorkspaceId), or workspace with im projects go another organization where the owner be admin too (kindworkspace,workspaceId,toOrganizationId), callrequest_move. Nothing go move yet: the owner go get email and must confirm for the page wey e link to, within 24 hours. Callget_move_requestfor the status:pending,done,cancelled,expiredorfailed. - To add work wey no tie to page, call
create_taskwithprojectIdandtitle, and optionallytextandpageUrl. To change the wording, callupdate_taskwith thetaskIdand newtitle,textor both. Both of dem count toward daily limit on new workspaces, projects and tasks; the refusal go tell you when you reach am.list_commentsdey show tasks wey dem mark[Task]and e dey taketype:taskorcomment. - Job reports (Studio, Agency and the trial) na tasks wey client dey fill about job wey dem don do: place, date, end customer and files by phase (
before,during,after,other) with captions. Calllist_job_reports(statereadygo list the ones wey dey wait for you), read one withget_comment, and reply withrolearticlefor im language. Na person only dey approve: give dem the approval link or callrequest_approval. Once dem approve, reply withrolepostsandfiles(the ids of the files to use).update_filedey set filephaseorcaption;create_taskandupdate_taskdey takejobReport. - Voice notes and AI (Studio, Agency and the trial):
get_commentdey list each recording with link to the audio and im transcript by AI (and any later transcript, wey dem no post), each video wey pass about 20 seconds with time notes (m:ss–m:sswetin dey happen), and AI captions wey dem mark(AI, not checked)until person check dem. When AI no fit process file, e go talk am for the same plain words wey people dey see, with reference code (AI-…) for support.list_plansandget_billingdey give the voice and AI minutes for one month.
No poll faster than pollAfterSeconds. If you get rate_limited, wait retryAfter seconds. Wrong or unknown id or secret dey return 404 with {"code":"not_found"}.
If your platform dey sign im requests with Web Bot Auth (HTTP message signatures, Signature-Agent with key directory) and Notiamo trust am, sign-up and the MCP server go count you by your platform, no be by your address, with higher limits. Requests wey no get signature go work like before.
Example: ask for account
curl -X POST https://my.notiamo.com/api/agent/signup \
-H "Content-Type: application/json" \
-d '{"email":"owner@example.com","name":"Ada Owner","agent":"my-agent","locale":"en","projectUrl":"https://example.com"}'The free plan
The free plan allow 1 workspace, 1 project, 3 people (team members, client members and invites wey dey wait, each email one time) and 1 public address for each project. After the first public comment of the project, dem fit change the address one time. E dey hold 100 MB of files, 5 MB for each file; if e pass 100 MB the organization admins go get two emails, then dem go remove the oldest files, and comments, tasks and replies go stay. Dem fit refuse uploads to stop abuse. Video no dey inside: e need Studio, Agency or the trial. Workspace and project don already dey when the account open.
The widget dey show Notiamo badge for the free plan.
Keep the comment line wey dey above the script tag. The terms of the free plan require am:
<!-- Notiamo (notiamo.com): website feedback. Free plan: keep this line. -->A plan_limit refusal go tell you which limit you reach and wetin to do next.
Refusals
Sign-up and the tools dey answer with code. The sign-up codes dey come with HTTP status:
| Code | HTTP status | Wetin e mean |
|---|---|---|
signup_blocked | 403 | Dem no allow the network to sign up. The owner go sign up by himself. |
country_blocked | 403 | Notiamo no dey available for the country wey the request come from. The owner no fit sign up from there too. |
rate_limited | 429 | Too many requests. Wait for retryAfter seconds. |
agent_signup_paused | 503 | Dem pause sign-up by agents for now. The owner go sign up by himself. |
agent_signup_closed | 503 | Sign-up by agents don close. The owner go sign up by himself. |
account_exists | 409 | This email don already get account. The owner go log in and create key for Settings > AI agents > Agent tokens. |
email_not_accepted | 422 | Dem no fit use this email address. The owner go sign up by himself. |
invalid_input | 422 | One field no valid. field dey name am. |
plan_limit | 402 | You reach plan limit. The MCP tools dey return am, with the next step (start_trial or get_payment_link). |
read_only | 403 | This key or app na read-only: e fit look but e no fit change anything. The MCP tools dey return am. |
permission_missing | 403 | This key or app no fit do this. permission dey name the group wey miss (or full). The MCP tools dey return am. |
Show refusals to your owner. No ever work around dem.
Sign in with Notiamo (OAuth)
Instead of key, MCP client wey support sign-in fit connect with OAuth. The authorization server metadata dey for https://my.notiamo.com/.well-known/oauth-authorization-server, and the MCP server dey answer 401 with WWW-Authenticate header wey point to im protected resource metadata (https://my.notiamo.com/.well-known/oauth-protected-resource/api/mcp, RFC 9728), wey name this server, and e suggest the scope notes replies status tasks. Clients dey register themselves and dem dey use PKCE (S256), without client secret.
Your owner go log in, choose the organization, wetin you fit change (Work on feedback dey tick) and the projects, and press Allow. The scopes na the permission groups below. Your owner go see the app for Settings > AI agents > Connected apps and e fit disconnect am any time.
Permissions
To read no need permission. To change something, key or connected app need the group for am:
notes replies status tasks setup invites billing moves
Read-only no get group. Work on feedback get notes, replies, status and tasks. Full get all of dem; to invite team members need Full. Without the group, the tool go refuse with permission_missing and name the group inside permission; read-only key go get read_only. Show am to your owner: na only dem fit give more access.
Paying
list_plans dey show the plans (see the pricing page for the prices). start_trial dey start the trial, one time for each person. Pricing
get_payment_link dey make payment link wey the owner go open and pay. You no dey ever handle card data.
Referral
If Notiamo badge or link bring you come here, pass im code inside the referral field of the JSON body of the sign-up. The ?via=<code> form na only for the sign-up web link wey people dey open.
The MCP tools
After you connect you fit call:
whoami list_projects find_project list_comments list_activity get_comment reply set_status assign list_team list_people get_account list_plans get_billing start_trial list_workspaces create_workspace create_project update_project_address update_project_language get_install get_badge check_install invite get_payment_link create_organization request_move get_move_request create_task update_task list_job_reports update_file request_approval