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).

OperazioneChiamata
Leggi lo spazio di lavoroGET /workspaceGratis
Leggi l'utilizzoGET /usageGratis
Elenca le competenzeGET /skillsGratis
Elenca i connettoriGET /connectorsGratis
Cerca nello spazio di lavoroPOST /searchGratis
Modifica lo spazio di lavoroPATCH /workspaceGratis
Attiva o disattiva una competenzaPATCH /skills/{skillId}Gratis
Elenca le preferenze degli strumentiGET /workspace/toolsGratis
Elenca le preferenze degli strumenti di un sitoGET /sites/{siteId}/toolsGratis
Attiva o disattiva uno strumentoPATCH /workspace/toolsGratis
Scollega un connettoreDELETE /connectors/{provider}Gratis
Scollega un connettore del sitoDELETE /sites/{siteId}/connectors/{provider}Gratis

Leggi lo spazio di lavoro

GET/workspaceGratis

Lo 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

Richiesta
curl https://app.semchat.io/api/v1/workspace \
  -H "Authorization: Bearer sk_live_…"
Risposta · 200
{
  "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

GET/usageGratis

L'utilizzo del periodo in corso, in percentuale, suddiviso per categoria.

Strumento MCP get_usage

Richiesta
curl https://app.semchat.io/api/v1/usage \
  -H "Authorization: Bearer sk_live_…"
Risposta · 200
{
  "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

GET/skillsGratis

Le competenze disponibili per la chat dello spazio di lavoro.

Strumento MCP list_skills

Richiesta
curl https://app.semchat.io/api/v1/skills \
  -H "Authorization: Bearer sk_live_…"
Risposta · 200
{
  "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

GET/connectorsGratis

Gli 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

Richiesta
curl https://app.semchat.io/api/v1/connectors \
  -H "Authorization: Bearer sk_live_…"

Risponde 200 con { "data": … }.

Cerca nello spazio di lavoro

POST/searchGratis

Cerca 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

ArgomentoTipoDescrizione
queryobbligatoriostringCosa cercare, senza badare ad accenti e maiuscole. Vuoto: i più recenti di ogni tipo.fino a 100 caratteri
limitfacoltativointegerAl massimo questo numero per tipo (predefinito e massimo 50).≥ 1, ≤ 50
Richiesta
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

PATCH/workspaceGratis

Modifica 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

ArgomentoTipoDescrizione
namefacoltativostring1–255 caratteri
descriptionfacoltativostring | null
custom_instructionsfacoltativostring | nullLe istruzioni che l'assistente segue in ogni conversazione dello spazio di lavoro.
company_namefacoltativostring | null
company_websitefacoltativostring | null
company_sirenfacoltativostring | nullIl numero di registrazione dell'azienda.
company_addressfacoltativostring | null
Richiesta
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

PATCH/skills/{skillId}Gratis

Attiva 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

ArgomentoTipoDescrizione
skillIdnel percorsostringIl suo id.
enabledobbligatorioboolean
Richiesta
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

GET/workspace/toolsGratis

Gli 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

Richiesta
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

GET/sites/{siteId}/toolsGratis

Gli 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

ArgomentoTipoDescrizione
siteIdnel percorsostringIl suo id.
Richiesta
curl https://app.semchat.io/api/v1/sites/{siteId}/tools \
  -H "Authorization: Bearer sk_live_…"

Risponde 200 con { "data": … }.

Attiva o disattiva uno strumento

PATCH/workspace/toolsGratis

Attiva o disattiva uno strumento per l'assistente, per lo spazio di lavoro o per un solo sito.

Strumento MCP set_tool_pref

ArgomentoTipoDescrizione
tool_nameobbligatoriostringLo strumento, con il nome che gli dà list_tool_prefs.1–64 caratteri
enabledobbligatorioboolean
site_idfacoltativostringSolo per questo sito (predefinito: lo spazio di lavoro).almeno 1 carattere
Richiesta
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

DELETE/connectors/{provider}Gratis

Scollega 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

ArgomentoTipoDescrizione
providernel percorsostringIl suo id.
Richiesta
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

DELETE/sites/{siteId}/connectors/{provider}Gratis

Scollega uno strumento collegato a questo sito (il suo accesso salvato viene eliminato).

  • provider come lo mostra list_site_connectors.

Strumento MCP disconnect_site_connector

ArgomentoTipoDescrizione
siteIdnel percorsostringIl suo id.
providernel percorsostringIl suo id.
Richiesta
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.

Pronto a far decollare il tuo sito?

Fai la tua prima domanda - semchat ti risponde con un piano d'azione chiaro in pochi secondi.

Gratis · senza registrazione · in 5 secondi