DocumentazioneRiferimento API
Spazio di lavoro
Lo spazio di lavoro, il suo utilizzo, la ricerca, le competenze, le preferenze degli strumenti e i connettori.
Ogni operazione qui sotto è anche uno strumento MCP, con lo stesso nome. Le operazioni Gratis non costano nulla; quelle A pagamento usano i crediti dello spazio di lavoro, come nell'app (Quanto costa).
| Operazione | Chiamata | |
|---|---|---|
| Leggi lo spazio di lavoro | GET /workspace | Gratis |
| Leggi l'utilizzo | GET /usage | Gratis |
| Elenca le competenze | GET /skills | Gratis |
| Elenca i connettori | GET /connectors | Gratis |
| Cerca nello spazio di lavoro | POST /search | Gratis |
| Modifica lo spazio di lavoro | PATCH /workspace | Gratis |
| Attiva o disattiva una competenza | PATCH /skills/{skillId} | Gratis |
| Elenca le preferenze degli strumenti | GET /workspace/tools | Gratis |
| Elenca le preferenze degli strumenti di un sito | GET /sites/{siteId}/tools | Gratis |
| Attiva o disattiva uno strumento | PATCH /workspace/tools | Gratis |
| Scollega un connettore | DELETE /connectors/{provider} | Gratis |
| Scollega un connettore del sito | DELETE /sites/{siteId}/connectors/{provider} | Gratis |
Leggi lo spazio di lavoro
/workspaceGratisLo spazio di lavoro, il suo piano e quanta parte dei crediti del periodo è già stata usata.
- I crediti non vengono mai mostrati come numeri grezzi: solo come percentuali del periodo.
Strumento MCP get_workspace
curl https://app.semchat.io/api/v1/workspace \
-H "Authorization: Bearer sk_live_…"{
"data": {
"id": "01995d03-8ea0-79ee-8ee3-c2eed260b3bc",
"name": "Acme",
"plan": {
"id": "starter",
"name": "Starter",
"features": {
"gsc": true,
"market_data": true,
"agents": 11,
"backlinks": true,
"weekly_reports": true,
"ai_writer": true
}
},
"balance": {
"used_pct": 12.5,
"remaining_pct": 87.5,
"period_resets_at": "2026-11-12T13:26:58.000Z"
},
"settings": {
"description": null,
"custom_instructions": "Nous sommes une agence SEO lyonnaise.",
"company_name": null,
"company_website": null,
"company_siren": null,
"company_address": null
}
}
}Leggi l'utilizzo
/usageGratisL'utilizzo del periodo in corso, in percentuale, suddiviso per categoria.
Strumento MCP get_usage
curl https://app.semchat.io/api/v1/usage \
-H "Authorization: Bearer sk_live_…"{
"data": {
"period": "current",
"used_pct": 12.5,
"remaining_pct": 87.5,
"by_category_pct": {
"conversations": 2.5,
"seo_tools": 2.5,
"visuals": 2.5,
"documents": 2.5,
"site_analysis": 2.5
}
}
}Elenca le competenze
/skillsGratisLe competenze disponibili per la chat dello spazio di lavoro.
Strumento MCP list_skills
curl https://app.semchat.io/api/v1/skills \
-H "Authorization: Bearer sk_live_…"{
"data": [
{
"id": "cocon-semantique",
"name": "Topic cluster",
"when_to_use": "Quand l'utilisateur demande : cocon sémantique.",
"enabled": true
},
{
"id": "seo-audit",
"name": "SEO audit",
"when_to_use": "Quand l'utilisateur demande : audit seo.",
"enabled": true
}
]
}Elenca i connettori
/connectorsGratisGli strumenti collegati a livello di spazio di lavoro (Search Console, GA4, Slack, Notion…).
- La maggior parte delle connessioni è per sito: vedi list_site_connectors.
Strumento MCP list_connectors
curl https://app.semchat.io/api/v1/connectors \
-H "Authorization: Bearer sk_live_…"Risponde 200 con { "data": … }.
Cerca nello spazio di lavoro
/searchGratisCerca tra le conversazioni, i siti, le attività pianificate, i connettori e le competenze dello spazio di lavoro per nome, indirizzo, messaggio o account, come fa la ricerca dell'app (⌘K).
- Ogni tipo arriva con
more: true quando ce ne sono altri oltre a quelli restituiti. - Le conversazioni vengono cercate per titolo.
Strumento MCP search_workspace
| Argomento | Tipo | Descrizione |
|---|---|---|
queryobbligatorio | string | Cosa cercare, senza badare ad accenti e maiuscole. Vuoto: i più recenti di ogni tipo.fino a 100 caratteri |
limitfacoltativo | integer | Al massimo questo numero per tipo (predefinito e massimo 50).≥ 1, ≤ 50 |
curl -X POST https://app.semchat.io/api/v1/search \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"query": "…"}'Risponde 200 con { "data": … }.
Modifica lo spazio di lavoro
/workspaceGratisModifica le impostazioni dello spazio di lavoro: il nome, la descrizione, le istruzioni personalizzate per l'assistente, i dati dell'azienda.
- Solo proprietario o amministratore (il ruolo di chi ha creato la chiave): altrimenti 403 FORBIDDEN.
- Cambiano solo i campi indicati; un testo vuoto (o null) svuota un campo. Serve almeno un campo.
Strumento MCP update_workspace
| Argomento | Tipo | Descrizione |
|---|---|---|
namefacoltativo | string | 1–255 caratteri |
descriptionfacoltativo | string | null | |
custom_instructionsfacoltativo | string | null | Le istruzioni che l'assistente segue in ogni conversazione dello spazio di lavoro. |
company_namefacoltativo | string | null | |
company_websitefacoltativo | string | null | |
company_sirenfacoltativo | string | null | Il numero di registrazione dell'azienda. |
company_addressfacoltativo | string | null |
curl -X PATCH https://app.semchat.io/api/v1/workspace \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"name": "…"}'Risponde 200 con { "data": … }.
Attiva o disattiva una competenza
/skills/{skillId}GratisAttiva o disattiva una delle competenze dello spazio di lavoro per la sua chat.
- Solo proprietario o amministratore (il ruolo di chi ha creato la chiave): altrimenti 403 FORBIDDEN.
Strumento MCP set_skill
| Argomento | Tipo | Descrizione |
|---|---|---|
skillIdnel percorso | string | Il suo id. |
enabledobbligatorio | boolean |
curl -X PATCH https://app.semchat.io/api/v1/skills/{skillId} \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"enabled": true}'Risponde 200 con { "data": … }.
Elenca le preferenze degli strumenti
/workspace/toolsGratisGli strumenti dei connettori che l'assistente può usare, ognuno attivo o disattivato per lo spazio di lavoro.
- Uno strumento è attivo a meno che non sia stato disattivato. Ogni sito eredita queste scelte, a meno che non imposti le sue: vedi list_site_tool_prefs.
Strumento MCP list_tool_prefs
curl https://app.semchat.io/api/v1/workspace/tools \
-H "Authorization: Bearer sk_live_…"Risponde 200 con { "data": … }.
Elenca le preferenze degli strumenti di un sito
/sites/{siteId}/toolsGratisGli strumenti dei connettori che l'assistente può usare nelle conversazioni di questo sito, ognuno attivo o disattivato.
- La scelta del sito, se ne ha fatta una, altrimenti quella dello spazio di lavoro.
Strumento MCP list_site_tool_prefs
| Argomento | Tipo | Descrizione |
|---|---|---|
siteIdnel percorso | string | Il suo id. |
curl https://app.semchat.io/api/v1/sites/{siteId}/tools \
-H "Authorization: Bearer sk_live_…"Risponde 200 con { "data": … }.
Attiva o disattiva uno strumento
/workspace/toolsGratisAttiva o disattiva uno strumento per l'assistente, per lo spazio di lavoro o per un solo sito.
Strumento MCP set_tool_pref
| Argomento | Tipo | Descrizione |
|---|---|---|
tool_nameobbligatorio | string | Lo strumento, con il nome che gli dà list_tool_prefs.1–64 caratteri |
enabledobbligatorio | boolean | |
site_idfacoltativo | string | Solo per questo sito (predefinito: lo spazio di lavoro).almeno 1 carattere |
curl -X PATCH https://app.semchat.io/api/v1/workspace/tools \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"tool_name": "…", "enabled": true}'Risponde 200 con { "data": … }.
Scollega un connettore
/connectors/{provider}GratisScollega uno strumento collegato a livello di spazio di lavoro (il suo accesso salvato viene eliminato).
- provider come lo mostra list_connectors (google_search_console, google_analytics_4, notion, slack, wordpress, webflow, microsoft_clarity, bing_webmaster_tools, yandex_metrica).
- Le connessioni dei singoli siti non vengono toccate: vedi disconnect_site_connector. Uno strumento si collega dall'app.
Strumento MCP disconnect_connector
| Argomento | Tipo | Descrizione |
|---|---|---|
providernel percorso | string | Il suo id. |
curl -X DELETE https://app.semchat.io/api/v1/connectors/{provider} \
-H "Authorization: Bearer sk_live_…"Risponde 200 con { "data": … }.
Scollega un connettore del sito
/sites/{siteId}/connectors/{provider}GratisScollega uno strumento collegato a questo sito (il suo accesso salvato viene eliminato).
- provider come lo mostra list_site_connectors.
Strumento MCP disconnect_site_connector
| Argomento | Tipo | Descrizione |
|---|---|---|
siteIdnel percorso | string | Il suo id. |
providernel percorso | string | Il suo id. |
curl -X DELETE https://app.semchat.io/api/v1/sites/{siteId}/connectors/{provider} \
-H "Authorization: Bearer sk_live_…"Risponde 200 con { "data": … }.
Hai una domanda a cui qui non trovi risposta? Scrivici.

