Notiamo per gli agenti IA
Tutto ciò che serve a un agente IA per aprire un account gratuito per il suo proprietario, mettere il widget su un sito web e gestire i commenti e il lavoro, senza browser.
Il flusso
- Richieda un account per il suo proprietario: invii
POST https://my.notiamo.com/api/agent/signupconemail,name,agent,localee, se li ha,company,projectUrl(l’indirizzo del sito web) ereferral. La risposta contienerequestId,pollSecretepollAfterSeconds. - Chieda al proprietario di aprire l’e-mail di conferma inviata da Notiamo e di confermare. Finché non lo fa, non succede nulla.
- Interroghi
GET https://my.notiamo.com/api/agent/signup/{requestId}conAuthorization: Bearer <pollSecret>ognipollAfterSecondssecondi. Lo stato èpending,confirmed,expiredoreported. - Quando lo stato è
confirmed, la risposta contiene una sola volta la sua chiave (token, che inizia conntm_) emcpUrl. Conservi subito la chiave: le interrogazioni successive non la restituiscono più. La ritiri entro 7 giorni dalla conferma. - Si colleghi al server MCP all’indirizzo
https://my.notiamo.com/api/mcpcon l’intestazioneAuthorization: Bearer ntm_…. Se la Sua app supporta l’accesso MCP, può usare «Accedi con Notiamo» al posto di una chiave (vedere sotto). - Chiami
list_projects(ofind_project) per trovare il progetto creato per Lei: usa già il SuoprojectUrlcome indirizzo. Se l’indirizzo manca o è sbagliato, chiamiupdate_project_address. Poiget_install, inserisca lo snippet e chiamicheck_install. Usicreate_workspaceecreate_projectsolo quando il piano ha spazio (piani a pagamento o prova Studio);create_projectrichiede unworkspaceIddalist_workspaces. Uno spazio di lavoro raggruppa dei progetti, per esempio uno per cliente. Un progetto può non avere indirizzo web (omettaorigin): ha allora attività, lavori e notizie, ma niente widget. Dopo l’installazione,get_badgefornisce il badge del footer: un piccolo logo Notiamo per il footer del sito, che apre gli strumenti di revisione per i revisori ed è un semplice link a Notiamo per tutti gli altri, nella lingua del sito (update_project_language, oppurelanguageincreate_project). - Poi lavori sui commenti:
list_comments,get_comment,replyeset_status. Per vedere le novità, passisincealist_comments: un orario UTC che termina conZ(come2026-10-17T08:00:00Z) o ilcursordella sua ultima risposta. Riceve solo ciò che è cambiato, su un progetto o, senzaprojectId, su tutti i Suoi progetti. Conservi il nuovocursorper il controllo successivo, segua subitomore: trueed elimini i doppioni perid: un elemento può arrivare due volte. - Per un’altra organizzazione, chiami
create_organizationcon unname: il proprietario ne diventa l’amministratore e riceve un’email, e la risposta contiene un nuovotokensolo per quell’organizzazione. È gratuita se il proprietario non ha un’organizzazione gratuita, altrimenti richiede un piano: chiamiget_payment_linkcon il nuovo token, oppurestart_trialper la prova di Studio di 14 giorni (una volta per persona; il proprietario apre il link e inserisce una carta). C’è un limite giornaliero; il rifiuto dice quando può riprovare. - Per spostare un progetto in un altro spazio di lavoro (
kindproject,projectId,toWorkspaceId), o uno spazio di lavoro con i suoi progetti in un’altra organizzazione in cui il proprietario è anche amministratore (kindworkspace,workspaceId,toOrganizationId), chiamirequest_move. Per ora nulla viene spostato: il proprietario riceve un’email e deve confermare nella pagina a cui rimanda, entro 24 ore. Chiamiget_move_requestper lo stato:pending,done,cancelled,expiredofailed. - Per aggiungere lavoro che non riguarda una pagina, chiami
create_taskcon unprojectIde untitle, e facoltativamentetextepageUrl. Per cambiarne il testo, chiamiupdate_taskcon iltaskIde un nuovotitle,texto entrambi. Entrambe contano in un limite giornaliero di nuovi spazi di lavoro, progetti e attività; il rifiuto Le dice quando lo raggiunge.list_commentsmostra le attività contrassegnate con[Task]e accettatype:taskocomment. - I rapporti di lavoro (Studio, Agency e la prova) sono attività che un cliente compila su un lavoro terminato: luogo, data, cliente finale e file per fase (
before,during,after,other) con didascalie. Chiamilist_job_reports(statereadyelenca quelli che La aspettano), ne legga uno conget_commente risponda conrolearticlenella sua lingua. Solo una persona approva: le dia il link di approvazione o chiamirequest_approval. Dopo l’approvazione, risponda conrolepostsefiles(gli id dei file da usare).update_fileimposta laphaseo lacaptiondi un file;create_taskeupdate_taskaccettanojobReport. - Note vocali e IA (Studio, Agency e la prova):
get_commentelenca ogni registrazione con un link all’audio e la sua trascrizione dell’IA (e ogni trascrizione successiva, non pubblicata), ogni video di oltre 20 secondi circa con le momenti del video (m:ss–m:ssche cosa succede), e le didascalie IA segnate(AI, not checked)finché una persona non le controlla. Quando l’IA non è riuscita a elaborare un file, lo dice con le stesse parole semplici che vedono le persone, con un codice di riferimento (AI-…) per l’assistenza.list_planseget_billingindicano i minuti di voce e IA al mese.
Non interroghi più spesso di ogni pollAfterSeconds secondi. Se riceve rate_limited, attenda retryAfter secondi. Un id o un segreto sbagliato o sconosciuto restituisce 404 con {"code":"not_found"}.
Se la tua piattaforma firma le richieste con Web Bot Auth (firme dei messaggi HTTP, un Signature-Agent con una directory di chiavi) e Notiamo se ne fida, la registrazione e il server MCP ti contano per piattaforma e non per indirizzo, con limiti più alti. Le richieste non firmate funzionano come prima.
Esempio: richiedere un 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"}'Il piano gratuito
Il piano gratuito consente 1 spazio di lavoro, 1 progetto, 3 persone (membri del team, membri del cliente e inviti in sospeso, ogni e-mail contata una volta) e 1 indirizzo pubblico per progetto. Dopo il primo commento pubblico del progetto, l’indirizzo può essere cambiato una volta. Contiene 100 MB di file, 5 MB per file; oltre i 100 MB gli amministratori dell’organizzazione ricevono due e-mail, poi i file più vecchi vengono rimossi, e i commenti, le attività e le risposte restano. I caricamenti possono essere rifiutati per fermare gli abusi. Il video non è incluso: richiede Studio, Agency o la prova. Uno spazio di lavoro e un progetto esistono già quando l’account viene aperto.
Nel piano gratuito il widget mostra un badge Notiamo.
Mantenga la riga di commento sopra il tag script. Le condizioni del piano gratuito lo richiedono:
<!-- Notiamo (notiamo.com): website feedback. Free plan: keep this line. -->Un rifiuto plan_limit indica quale limite è stato raggiunto e cosa fare dopo.
Rifiuti
La registrazione e gli strumenti rispondono con un codice. I codici della registrazione sono accompagnati da uno stato HTTP:
| Codice | Stato HTTP | Significato |
|---|---|---|
signup_blocked | 403 | La rete non può registrarsi. Il proprietario si registra da sé. |
country_blocked | 403 | Notiamo non è disponibile nel paese da cui arriva la richiesta. Nemmeno il proprietario può registrarsi da lì. |
rate_limited | 429 | Troppe richieste. Attenda retryAfter secondi. |
agent_signup_paused | 503 | La registrazione da parte degli agenti è sospesa per ora. Il proprietario si registra da sé. |
agent_signup_closed | 503 | La registrazione da parte degli agenti è chiusa. Il proprietario si registra da sé. |
account_exists | 409 | Questa e-mail ha già un account. Il proprietario accede e crea una chiave in Impostazioni > Agenti IA > Token degli agenti. |
email_not_accepted | 422 | Questo indirizzo e-mail non può essere usato. Il proprietario si registra da sé. |
invalid_input | 422 | Un campo non è valido. field lo indica. |
plan_limit | 402 | È stato raggiunto un limite del piano. Restituito dagli strumenti MCP, con il passo successivo (start_trial o get_payment_link). |
read_only | 403 | Questa chiave o app è in sola lettura: può guardare ma non modificare. Restituito dagli strumenti MCP. |
permission_missing | 403 | Questa chiave o app non può farlo. permission nomina il gruppo mancante (o full). Restituito dagli strumenti MCP. |
Mostri i rifiuti al suo proprietario. Non li aggiri mai.
Accedi con Notiamo (OAuth)
Al posto di una chiave, un client MCP che supporta l’accesso può collegarsi con OAuth. I metadati del server di autorizzazione sono all’indirizzo https://my.notiamo.com/.well-known/oauth-authorization-server, e il server MCP risponde 401 con un’intestazione WWW-Authenticate che rimanda ai metadati della sua risorsa protetta (https://my.notiamo.com/.well-known/oauth-protected-resource/api/mcp, RFC 9728), i quali nominano questo server. L’intestazione suggerisce lo scope notes replies status tasks. I client si registrano da soli e usano PKCE (S256), senza segreto client.
Il Suo proprietario accede, sceglie l’organizzazione, cosa può modificare (Lavorare sui commenti è spuntato) e i progetti, e preme Consenti. Gli scope sono i gruppi di permessi qui sotto. Il Suo proprietario vede l’app in Impostazioni > Agenti IA > App collegate e può scollegarla in qualsiasi momento.
Permessi
Leggere non richiede permessi. Per modificare qualcosa, una chiave o un’app collegata ha bisogno del gruppo corrispondente:
notes replies status tasks setup invites billing moves
Sola lettura non ha alcun gruppo. Lavorare sui commenti ha notes, replies, status e tasks. Completo li ha tutti; invitare membri del team richiede Completo. Senza il gruppo, lo strumento rifiuta con permission_missing e nomina il gruppo in permission; una chiave in sola lettura riceve read_only. Lo mostri al Suo proprietario: solo lui può dare più accesso.
Pagare
list_plans mostra i piani (i prezzi sono nella pagina dei prezzi). start_trial avvia la prova, una volta per persona. Prezzi
get_payment_link crea un link di pagamento che il proprietario apre e paga. Lei non gestisce mai dati di carte.
Segnalazione
Se l’ha portata qui un badge o un link di Notiamo, indichi il suo codice nel campo referral del corpo JSON della registrazione. La forma ?via=<code> serve solo per il link di registrazione web che le persone aprono.
Gli strumenti MCP
Dopo il collegamento può chiamare:
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