DocumentationAPI reference

Workspace

The workspace, its usage, search, skills, tool preferences and connectors.

Every operation below is also an MCP tool, under the same name. Free operations cost nothing; Billed ones use the workspace’s credits, as in the app (What it costs).

OperationCall
Get workspaceGET /workspaceFree
Get usageGET /usageFree
List skillsGET /skillsFree
List connectorsGET /connectorsFree
Search workspacePOST /searchFree
Update workspacePATCH /workspaceFree
Set skillPATCH /skills/{skillId}Free
List tool prefsGET /workspace/toolsFree
List site tool prefsGET /sites/{siteId}/toolsFree
Set tool prefPATCH /workspace/toolsFree
Disconnect connectorDELETE /connectors/{provider}Free
Disconnect site connectorDELETE /sites/{siteId}/connectors/{provider}Free

Get workspace

GET/workspaceFree

The workspace, its plan and how much of the period’s credits is used.

  • Credits are never shown as raw numbers: only percentages of the period.

MCP tool get_workspace

Request
curl https://app.semchat.io/api/v1/workspace \
  -H "Authorization: Bearer sk_live_…"
Response · 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
    }
  }
}

Get usage

GET/usageFree

The current period’s usage, in percent, split by category.

MCP tool get_usage

Request
curl https://app.semchat.io/api/v1/usage \
  -H "Authorization: Bearer sk_live_…"
Response · 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
    }
  }
}

List skills

GET/skillsFree

The skills available to the workspace’s chat.

MCP tool list_skills

Request
curl https://app.semchat.io/api/v1/skills \
  -H "Authorization: Bearer sk_live_…"
Response · 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
    }
  ]
}

List connectors

GET/connectorsFree

Tools connected at workspace level (Search Console, GA4, Slack, Notion…).

  • Most connections are per site: see list_site_connectors.

MCP tool list_connectors

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

Answers 200 with { "data": … }.

Search workspace

POST/searchFree

Searches the workspace’s conversations, sites, scheduled tasks, connectors and skills by name, address, message or account, as the app’s search (⌘K) does.

  • Each kind comes with more: true when there are others than those returned.
  • Conversations are searched by their title.

MCP tool search_workspace

ArgumentTypeDescription
queryrequiredstringWhat to look for, accents and case aside. Empty: the newest of each kind.up to 100 characters
limitoptionalintegerAt most this many of each kind (default and maximum 50).≥ 1, ≤ 50
Request
curl -X POST https://app.semchat.io/api/v1/search \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"query": "…"}'

Answers 200 with { "data": … }.

Update workspace

PATCH/workspaceFree

Edit the workspace’s settings: its name, description, custom instructions for the assistant, company details.

  • Owner or admin only (the role of the key’s creator): 403 FORBIDDEN otherwise.
  • Only the fields given change; an empty text (or null) clears a field. At least one field is required.

MCP tool update_workspace

ArgumentTypeDescription
nameoptionalstring1–255 characters
descriptionoptionalstring | null
custom_instructionsoptionalstring | nullInstructions the assistant follows in every conversation of the workspace.
company_nameoptionalstring | null
company_websiteoptionalstring | null
company_sirenoptionalstring | nullThe company’s registration number.
company_addressoptionalstring | null
Request
curl -X PATCH https://app.semchat.io/api/v1/workspace \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "…"}'

Answers 200 with { "data": … }.

Set skill

PATCH/skills/{skillId}Free

Turn one of the workspace’s skills on or off for its chat.

  • Owner or admin only (the role of the key’s creator): 403 FORBIDDEN otherwise.

MCP tool set_skill

ArgumentTypeDescription
skillIdin the pathstringIts id.
enabledrequiredboolean
Request
curl -X PATCH https://app.semchat.io/api/v1/skills/{skillId} \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Answers 200 with { "data": … }.

List tool prefs

GET/workspace/toolsFree

The connectors’ tools the assistant may use, each on or off for the workspace.

  • A tool is on unless it was turned off. Each site inherits these, unless it sets its own: see list_site_tool_prefs.

MCP tool list_tool_prefs

Request
curl https://app.semchat.io/api/v1/workspace/tools \
  -H "Authorization: Bearer sk_live_…"

Answers 200 with { "data": … }.

List site tool prefs

GET/sites/{siteId}/toolsFree

The connectors’ tools the assistant may use in this site’s conversations, each on or off.

  • The site’s own choice when it made one, else the workspace’s.

MCP tool list_site_tool_prefs

ArgumentTypeDescription
siteIdin the pathstringIts id.
Request
curl https://app.semchat.io/api/v1/sites/{siteId}/tools \
  -H "Authorization: Bearer sk_live_…"

Answers 200 with { "data": … }.

Set tool pref

PATCH/workspace/toolsFree

Turn a tool on or off for the assistant, for the workspace or for one site.

MCP tool set_tool_pref

ArgumentTypeDescription
tool_namerequiredstringThe tool, as list_tool_prefs names it.1–64 characters
enabledrequiredboolean
site_idoptionalstringOnly for this site (default: the workspace).at least 1 character
Request
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}'

Answers 200 with { "data": … }.

Disconnect connector

DELETE/connectors/{provider}Free

Disconnect a tool connected at workspace level (its stored access is deleted).

  • provider as list_connectors shows it (google_search_console, google_analytics_4, notion, slack, wordpress, webflow, microsoft_clarity, bing_webmaster_tools, yandex_metrica).
  • The sites’ own connections are untouched: see disconnect_site_connector. Connecting a tool is done in the app.

MCP tool disconnect_connector

ArgumentTypeDescription
providerin the pathstringIts id.
Request
curl -X DELETE https://app.semchat.io/api/v1/connectors/{provider} \
  -H "Authorization: Bearer sk_live_…"

Answers 200 with { "data": … }.

Disconnect site connector

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

Disconnect a tool connected to this site (its stored access is deleted).

  • provider as list_site_connectors shows it.

MCP tool disconnect_site_connector

ArgumentTypeDescription
siteIdin the pathstringIts id.
providerin the pathstringIts id.
Request
curl -X DELETE https://app.semchat.io/api/v1/sites/{siteId}/connectors/{provider} \
  -H "Authorization: Bearer sk_live_…"

Answers 200 with { "data": … }.

A question this doesn’t answer? Write to us.

Ready to get your site off the ground?

Ask your first question - semchat replies with a clear action plan in seconds.

Free · no sign-up · takes 5 seconds