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).
| Operation | Call | |
|---|---|---|
| Get workspace | GET /workspace | Free |
| Get usage | GET /usage | Free |
| List skills | GET /skills | Free |
| List connectors | GET /connectors | Free |
| Search workspace | POST /search | Free |
| Update workspace | PATCH /workspace | Free |
| Set skill | PATCH /skills/{skillId} | Free |
| List tool prefs | GET /workspace/tools | Free |
| List site tool prefs | GET /sites/{siteId}/tools | Free |
| Set tool pref | PATCH /workspace/tools | Free |
| Disconnect connector | DELETE /connectors/{provider} | Free |
| Disconnect site connector | DELETE /sites/{siteId}/connectors/{provider} | Free |
Get workspace
/workspaceFreeThe 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
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
}
}
}Get usage
/usageFreeThe current period’s usage, in percent, split by category.
MCP tool 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
}
}
}List skills
/skillsFreeThe skills available to the workspace’s chat.
MCP tool 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
}
]
}List connectors
/connectorsFreeTools connected at workspace level (Search Console, GA4, Slack, Notion…).
- Most connections are per site: see list_site_connectors.
MCP tool list_connectors
curl https://app.semchat.io/api/v1/connectors \
-H "Authorization: Bearer sk_live_…"Answers 200 with { "data": … }.
Search workspace
/searchFreeSearches 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
| Argument | Type | Description |
|---|---|---|
queryrequired | string | What to look for, accents and case aside. Empty: the newest of each kind.up to 100 characters |
limitoptional | integer | At most this many of each kind (default and maximum 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": "…"}'Answers 200 with { "data": … }.
Update workspace
/workspaceFreeEdit 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
| Argument | Type | Description |
|---|---|---|
nameoptional | string | 1–255 characters |
descriptionoptional | string | null | |
custom_instructionsoptional | string | null | Instructions the assistant follows in every conversation of the workspace. |
company_nameoptional | string | null | |
company_websiteoptional | string | null | |
company_sirenoptional | string | null | The company’s registration number. |
company_addressoptional | string | null |
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
/skills/{skillId}FreeTurn 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
| Argument | Type | Description |
|---|---|---|
skillIdin the path | string | Its id. |
enabledrequired | 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}'Answers 200 with { "data": … }.
List tool prefs
/workspace/toolsFreeThe 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
curl https://app.semchat.io/api/v1/workspace/tools \
-H "Authorization: Bearer sk_live_…"Answers 200 with { "data": … }.
List site tool prefs
/sites/{siteId}/toolsFreeThe 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
| Argument | Type | Description |
|---|---|---|
siteIdin the path | string | Its id. |
curl https://app.semchat.io/api/v1/sites/{siteId}/tools \
-H "Authorization: Bearer sk_live_…"Answers 200 with { "data": … }.
Set tool pref
/workspace/toolsFreeTurn a tool on or off for the assistant, for the workspace or for one site.
MCP tool set_tool_pref
| Argument | Type | Description |
|---|---|---|
tool_namerequired | string | The tool, as list_tool_prefs names it.1–64 characters |
enabledrequired | boolean | |
site_idoptional | string | Only for this site (default: the workspace).at least 1 character |
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
/connectors/{provider}FreeDisconnect 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
| Argument | Type | Description |
|---|---|---|
providerin the path | string | Its id. |
curl -X DELETE https://app.semchat.io/api/v1/connectors/{provider} \
-H "Authorization: Bearer sk_live_…"Answers 200 with { "data": … }.
Disconnect site connector
/sites/{siteId}/connectors/{provider}FreeDisconnect a tool connected to this site (its stored access is deleted).
- provider as list_site_connectors shows it.
MCP tool disconnect_site_connector
| Argument | Type | Description |
|---|---|---|
siteIdin the path | string | Its id. |
providerin the path | string | Its id. |
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.

