# semchat documentation Everything semchat does, explained plainly: add a site, read its analysis, work with the chat, automate with tasks, and use it all from the API or your AI assistant. Online: https://semchat.io/en/docs. API base URL: https://app.semchat.io/api/v1. MCP server: https://app.semchat.io/mcp/sse. ## Get started What semchat does, your first site and its analysis. ### Introduction What semchat does, how it is organised and where to find things. (https://semchat.io/en/docs/introduction) semchat is an AI assistant for your site’s visibility: a chat that analyses websites, keywords, competitors and backlinks, and a page per site with its analysis and its action plan. You ask in plain words, it looks at the real data and answers with what to do. #### How it is organised | Area | What lives there | | --- | --- | | **Workspace** | Everything: sites, conversations, tasks, connectors, the plan and the credits. You can have several and switch between them. | | **Sites** | The websites the workspace follows. Each has its analysis, action plan, keywords, competitors, backlinks, health and its own conversations. | | **Chat** | Conversations outside any site, or inside one, where the assistant already knows that site. | | **Tasks** | Messages the chat sends on its own, at the times you choose. | | **Settings** | The workspace (members, skills, billing, usage, connectors, API) and your account. | #### Finding your way - The left sidebar has **New chat**, **Search**, **Sites** and **Tasks**, then the workspace’s conversations: **Favorites** (the starred ones) and **Recents**. - **Search** (⌘K or Ctrl+K) looks through the whole workspace: conversations, sites, tasks, connectors and skills, with tabs to keep to one kind. - The user menu (your avatar, bottom left) has the workspace switcher, **Create a workspace**, **Settings**, **Plans & billing**, the theme and the language. #### Your first minutes 1. **Fill in your profile**: A short onboarding asks your name, then offers **Add my first site** or **Start without a site**. 2. **Add your site**: Its address, and a few words about who it is for. The analysis starts at once and takes about a minute. See [Add a site](https://semchat.io/en/docs/sites). 3. **Read the action plan**: At the top of the site’s page: what to fix, write and improve, by pillar. See [The action plan](https://semchat.io/en/docs/action-plan). 4. **Ask the chat**: “What should I do first?”, “Write the article for this keyword”, “Why did my traffic drop?” See [Conversations](https://semchat.io/en/docs/conversations). > Every new account gets one free site analysis and one free message. See [Plans, credits and top-ups](https://semchat.io/en/docs/billing). ### Add a site Add a site, find it in the list, change its settings or delete it. (https://semchat.io/en/docs/sites) #### Add a site 1. **Open Sites, then New site**: In the sidebar, **Sites**, then **New site**. 2. **Enter its address**: Add **Instructions** if you like: who the site is for, the tone, what matters. They steer everything semchat writes for this site. 3. **Analyze my site**: The analysis starts right away. See [The site analysis](https://semchat.io/en/docs/analysis). **Enter manually** creates the site without an analysis (name, address, description); you can analyse it later from its page. There is no limit on the number of sites, and adding one is free; the analysis uses credits. When the first message of a chat names a site you follow, semchat offers to link the conversation to it. #### The sites list A search box, sorting, a **Favorites** filter and a star on each card. A site being analysed shows its progress on its card. #### A site’s settings In **Settings**, on the site’s page: | Setting | What it does | | --- | --- | | **Instructions** | The voice, audience and constraints semchat keeps in mind in every conversation of the site, and when it writes the action plan and the content ideas. | | **Writing style** | Used for articles. Saved as you type. | | **Technologies used** | Used for advice specific to your platform. Saved as you type. | | Name, address, description | Saved with **Save**. Changing the address does not run the analysis again. | #### Delete a site **Delete site**, in its settings, removes it from the workspace. Its conversations stay in the workspace. > Every member of the workspace can add, edit, analyse or delete its sites. ### The site analysis What the analysis looks at, how long it takes, what it costs and what a new one changes. (https://semchat.io/en/docs/analysis) semchat explores the site (up to a few hundred pages), checks its technical health and accessibility, finds its competitors, looks at the keywords it ranks for and the gaps against its competitors, then writes the site’s context, its target keywords, content ideas and an action plan. It also fetches the backlinks of the site and of its main competitors, on every plan. #### While it runs 1. **Exploring your site**: its pages, their content and their links. 2. **Competitors and keywords**: who you compete with, and what you rank for. 3. **In-depth analysis**: health, accessibility and the gaps against your competitors. 4. **Enriching keywords**: the volume, difficulty and intent of each keyword. 5. **Building your action plan**: the tasks, by pillar. It takes about a minute. Competitor profiles, backlinks and the full action plan finish a little later in the background, and the site’s page fills in by itself. You can close the window: the analysis keeps running. When many analyses run at once, the first step says yours is in the queue. #### What it costs It uses the workspace’s credits, shown in **Settings → Usage** under site analysis. Without credits it does not start, and semchat offers to top up. **The free analysis**: every new account gets one. It pays for the first analysis of a site, your credits untouched. A new analysis of the same site always uses credits. #### Before your first payment Until the account’s first payment, the site’s page shows the start of each list, with what is left and **See plans**: - 2 tasks per pillar of the action plan - 2 keywords the site ranks for, and 1 opportunity - 2 content ideas - 3 competitors with their summary - the first 3 pages of each health problem (every problem and its count stay) - 2 accessibility problems - 3 pages per group in page visibility - backlinks: the numbers at the top, the comparison with 1 competitor, and the first 3 lines of each list Totals stay visible everywhere, and what you add by hand is always shown. The first payment, a plan or a top-up, shows everything for good: the analysis has already produced it. #### Analyse again On the site’s page, top right, **Re-analyze the site** (or **Retry analysis** after a failure). > Clear your site’s cache first (WordPress or any CMS with a cache), so the analysis sees the latest version. #### What a new analysis changes - The action plan is updated, never wiped: tasks the new data shows as fixed are marked done, new ones arrive with a **New** badge, and the others stay. - Competitors, keywords and content ideas found automatically are refreshed; the ones you added stay. - Health and accessibility get a new snapshot, so their history shows your progress. If the analysis fails, the page shows **Retry analysis**. A step that fails on its own, such as a competitor profile or the backlinks, is skipped without failing the whole analysis. ## Your site The action plan, keywords, health, competitors and backlinks. ### The action plan The tasks semchat writes for your site, by pillar, and how to work through them. (https://semchat.io/en/docs/action-plan) The action plan is the strip of cards at the top of a site’s page: one card per pillar, with its progress. Click one to open its tasks. Only the pillars with tasks show. | Pillar | What it covers | | --- | --- | | **Fix the basics** | The technical problems that hold the site back. | | **Write for your customers** | The pages and articles your customers look for. | | **Make your site accessible** | What makes the site hard to use for some visitors. | | **Get recommended** | Links and mentions from other sites. | | **Get ahead of rivals** | What your competitors do better, and how to catch up. | #### Work through the tasks - **New task** adds your own: a title, a description, a priority. - Filter by status (to do, done) and by priority. - On each task: the round checkbox to mark it done, its priority, **Edit** and delete. - **Work on it** opens a conversation in the site, with a message about that task ready to send. #### After a new analysis New tasks are added and the fixed ones are marked done; your own tasks are never deleted. The site’s **Instructions** set the plan’s tone. > In a conversation inside the site, the assistant already sees the open tasks. ### Keywords and content ideas The keywords to rank for and the pages worth writing, and how to act on them. (https://semchat.io/en/docs/keywords) #### Keywords The **Keywords** tab of a site lists the keywords to rank for, with their volume, difficulty, competition, traffic, position and intent. - **Add keyword**: the keyword, its intent, a priority and why. - **Work on it**, in a keyword’s menu, opens a conversation to rank for it. - A keyword can’t be edited: delete it and add it again. #### Content ideas The **Content ideas** tab lists the articles and pages worth writing. - Add one: a title, a format, a keyword and an angle. - **Write it** opens a conversation that writes the article. - Ideas can’t be edited either: delete and add again. > The keywords and ideas the analysis found are refreshed by the next one; the ones you added stay. ### Health, accessibility and page visibility The technical health score, the accessibility issues and the pages hidden from search. (https://semchat.io/en/docs/health) Three tabs of a site that update with each analysis, each with its history across analyses. They are read-only: to fix something, open a conversation in the site and ask. #### Health A technical health score and what is worth fixing: broken pages, missing titles, descriptions or H1, thin content, pages hard to find and orphan pages, each with its pages. #### Accessibility An accessibility score against WCAG 2.1 and the European directive, with the issues by rule and their pages. #### Page visibility The pages hidden from search engines that should be visible, and the visible ones that should be hidden. ### Competitors Who you compete with, their analysis and how your site compares. (https://semchat.io/en/docs/competitors) The analysis finds your competitors automatically, in the **Competitors** tab of the site. In a conversation inside the site, the assistant knows them. #### Add a competitor - Enter its address and **Analyze competitor**: semchat explores it and compares it with your site. It uses credits. - **Enter manually** (name, address, description) adds it with no analysis, as context for the assistant. #### On each card - **View analysis**: its summary, technical scores, its comparison with your site and the opportunities. - **Analyze** runs or reruns its analysis. It uses credits. - Delete. > Until your first payment you see 3 competitors with their summary; their charts and the comparison with your site come with a plan or a top-up. ### Backlinks Who links to your site, how you compare with your competitors, and the links worth going after. (https://semchat.io/en/docs/backlinks) The **Backlinks** tab of a site: authority, referring domains, backlinks, dofollow links and spam score; the site against its competitors; the links worth going after; the top referring domains, anchors and notable backlinks. Every site analysis fetches them, for the site and its main competitors, on every plan. > **Before your first payment**: The numbers at the top stay, the comparison shows 1 competitor, and each list (links worth going after, referring domains, anchors, notable backlinks) shows its first 3 lines, with how many are left and **See plans**. The first payment, a plan or a top-up, shows everything for good. #### Refresh them **Refresh** fetches them again for the site and its main competitors, and uses credits. It doesn’t run when a refresh is already running for the site, or when the credits can’t cover it. ## The chat Conversations, what they create, skills, scheduled tasks and connectors. ### Conversations Start a conversation, what the assistant knows, the composer, and keeping your conversations in order. (https://semchat.io/en/docs/conversations) #### Start one - **New chat**, in the sidebar: an independent chat outside any site, or a chat on one of your analysed sites. - From a site’s page, the **Chat** tab: a conversation in that site. - **Work on it** on a task or a keyword, and **Write it** on a content idea, start one too, with the message ready. #### What the assistant knows | Where | What it knows | | --- | --- | | In a site | The site’s analysis, context, keywords, competitors, open tasks, instructions, writing style and technologies, a summary of the site’s other conversations, its own connectors (data and CMS) and the workspace’s communication connectors. | | Outside a site | The workspace’s **Custom instructions** and communication connectors. A site named with `/site:` brings its data and its connectors. | | Everywhere | The workspace’s enabled [skills](https://semchat.io/en/docs/skills). | #### The composer **+**, or **/** typed in the message, opens the same menu: - **Upload file**: images, PDF, text, Markdown, CSV, 20 MB per file. Files can also be dropped on the composer. - **Connectors**: the chip of an email address, a Slack or Notion account, a Discord channel. - **Skills**: fills in a skill’s opening message. - **Tools**: **Crawl a site** adds a chip, and the message says what to crawl. - **Sites**: a site’s chip, with a search. A word typed after **/** lists what it matches. **Dictate** is for voice input, and **Stop generation** stops an answer. There is no model to choose: semchat picks it. #### On messages - **Copy**, **Regenerate** and **Export as Markdown** on the assistant’s answers, **Edit** on yours. - Editing or regenerating creates a branch, browsed with the arrows under the message. #### Keep them in order - The star moves a conversation into **Favorites**, shared with the workspace. - Its **…** menu: **Rename**, delete. - **Search** (⌘K) finds any conversation by its title, not only the ones in the sidebar. #### Long conversations Past a certain length, the assistant works from a summary of the first messages, and semchat offers **Continue in a new conversation**, which carries the summary over. > Each message uses credits: the AI’s work, plus the data its tools fetch. ### Documents, charts and images What the assistant creates in a conversation, and where it is kept. (https://semchat.io/en/docs/documents) On request, in a conversation, the assistant creates: | What | How it comes | | --- | --- | | **Documents** | Reports, articles, briefs: a card that opens a side panel to copy it or download it as **PDF**, **PDF with company**, **Markdown (.md)** or **Text (.txt)**. | | **Charts** and **KPI grids** | Shown in the conversation. | | **Site map** | The site’s internal links, as an interactive map. | | **Images** | Generated from a description. They use credits. | | **Code** | JSON-LD, robots.txt, redirects…: a code block with a copy button. | **PDF with company** adds the workspace’s company name, logo, SIREN and address, set in **Settings → Workspace → Your company**. #### Where they are kept - Documents made in a site’s conversations are listed in the site’s **Library → Documents**. Documents made outside a site stay in their conversation. - Charts and KPI grids have a **Save** button in a site’s conversation: saved ones go to the site’s **Data**. Outside a site, the button offers to create a site first. ### Skills Methods the assistant follows step by step, and how to use them. (https://semchat.io/en/docs/skills) Skills are methods the assistant follows step by step when a request matches: a full SEO audit, a semantic cocoon, a content brief, a competitor analysis… - In a conversation, the assistant applies an enabled skill by itself when the request matches. - To start one on purpose: **+ → Skills**, or type **/** and its name. It fills in its opening message. - **Settings → Skills** lists them with an on/off switch. Only the owner and admins see this tab, and a disabled skill isn’t used in the workspace. ### Scheduled tasks A message the chat sends on its own, at the times you choose. (https://semchat.io/en/docs/tasks) A task is a message written once that semchat sends to the chat by itself, at the times you choose, as if you had sent it, with the same credits. Each answer lands in its own conversation. #### Create a task 1. **Open Tasks**: In the sidebar. The first time, a short welcome shows a few ideas; **How does it work?** under the title shows it again. 2. **Write the message**: As in the chat: **/** names a site, a skill or an email address, **+** adds a connector. Pick the site it runs in, or none. 3. **Choose when**: Every day, some days of the week, a day of the month (in a shorter month, its last day), or every 1 to 12 hours, in your time zone. 4. **Create the task**: It runs at the next scheduled time, or right away with **Run now**. #### A few ideas - “Every Monday, review this week’s visits on /site:myshop.com: what’s rising, what’s falling and why. Email me the summary.” - “Find a topic my customers search for that my site hasn’t covered yet, write the article and prepare it as a draft on WordPress.” - “Look at what my competitors published this month and what works for them, then post a summary on /slack:#marketing.” - “Crawl my site and flag the pages that broke, slowed down or disappeared since yesterday.” #### How a run works - Nobody is there to answer: the chat decides on its own and ends with a short summary. - What the message asks for outside semchat (a WordPress draft, a Slack post, an email) is done during the run, as in a chat. See [Connectors](https://semchat.io/en/docs/connectors). - The tasks of a workspace run one at a time. A run stops after 15 minutes, and what was written by then is kept. - Each run is billed like a chat message. #### Manage your tasks - Each task has **Run now**, **Edit**, **Pause** and **Resume**, and its **History**: each run, its status and **Open the conversation**. - **Run now** sends it at once; its next scheduled run doesn’t change. - Deleting a task stops it. The conversations it wrote stay. > **When a task pauses itself**: Out of credits, a task pauses: top up, then turn it back on. After 3 errors in a row it pauses too: check its last conversation, then turn it back on. ### Connectors Your own data and tools: Search Console, Analytics, WordPress, Webflow, Slack, Notion, Discord and email. (https://semchat.io/en/docs/connectors) Connectors let the assistant use your own data and tools. | Kind | Connectors | Where | | --- | --- | --- | | Data | Google Search Console, Google Analytics 4, Bing Webmaster Tools, Yandex Metrica | The site’s **Connectors** tab | | CMS | WordPress (with WooCommerce), Webflow | The site’s **Connectors** tab | | Communication | Email, Slack, Notion, Discord | **Settings → Connectors**, shared by the workspace | #### A site’s data and CMS Each site connects its own, one connection each, used for that site only. A Google account that sees several sites reads the one at the site’s address (its **Property**). The same Google account can be connected in several sites. The assistant uses a site’s connectors on its own in that site’s conversations. Anywhere else (a task, a chat outside any site, another site’s chat), name the site with `/site:` to bring its data and its CMS: “analyse /site:example.com, pull its Search Console data, then post the report on /discord:…”. #### Communication Email, Slack, Notion and Discord belong to the workspace and are shared by every site, task and conversation. Each can have several: Slack workspaces and Notion spaces, Discord channels, email addresses. The composer’s **/** menu lists each one, so a message names exactly which to use; a plain `/slack` uses the first. #### Connect one | Connector | How | | --- | --- | | Search Console, Analytics 4, Bing, Yandex, Notion, Slack, Webflow | Click connect and approve access with that account. | | WordPress | **Approve in WordPress** (the site’s address, then approve in its admin), or **Application password**: the address, the username and an application password created in WordPress under Users → Profile. WooCommerce is detected through WordPress. | | Discord | Paste a channel’s webhook URL (in Discord: the channel’s settings, Integrations, Webhooks) and name it. | | Email | **Add an address**, with a name for its chip. An address other than yours first gets a verification email. | > Every connector works on every plan, the Free plan included. Connect Search Console before the first analysis: it then reads your real searches and builds its tasks on them. #### What a connection may do **Tools**, on a connection’s row, sets what it may do: for example a WordPress that may read but not publish (**Read only**). When a message asks to publish or post (a WordPress or Webflow draft, a WooCommerce product, a Slack message, a Notion page, an email), the assistant does it during its answer, with no confirmation step, in a conversation, a task or the API alike. Its card in the conversation shows what was done. It never does it unasked, nor because a page or a document it read says to. Discord and email are used only when the message names them (`/discord:`, `/email:`), tasks included. #### Reconnect or disconnect An expired connection shows **Access expired**, with **Reconnect**; its **…** menu disconnects it. Any member of the workspace can connect or disconnect tools. ## Account and billing Plans and credits, workspaces and members, your account. ### Plans, credits and top-ups What the Free plan includes, how credits work, top-ups, changing plan and invoices. (https://semchat.io/en/docs/billing) #### The Free plan A new account gets one free analysis and one free message, in any conversation. After that, the chat and the analyses wait for a plan or a top-up: the Free plan has no monthly credits. The account’s first payment, a plan or a top-up, unlocks the whole of every analysis for good, and the chat’s keyword, ranking, domain and backlink data. #### Credits Each paid plan gives the workspace a monthly amount of credits. Everything that uses AI or paid data uses them: messages, site analyses, competitor analyses, backlink refreshes, images and task runs. Credits show as a share of the period, never as a number. **Settings → Usage** (every member): the share used this period, when it resets, and the split by category. When the credits run out, the chat stops with **Top up to continue**: top up or change plan to go on. Every connector, Search Console and Analytics included, works on every plan. #### Top-ups Extra credits, on sale on every plan, the Free plan included: valid 12 months, used after the plan’s credits, with a discount on larger amounts. **Auto top-up** buys an amount when the balance drops under a threshold; it needs a saved card. #### Change plan - In **Settings → Billing** (the owner and admins), **Change plan**: monthly or yearly. - An upgrade, or monthly to yearly, applies now, and the period restarts at 0 %. - A downgrade, or yearly to monthly, applies at the end of the paid period, with nothing charged today; **Keep my current plan** undoes it until then. #### Cancel **Cancel subscription** keeps the plan until the end of the period, then the workspace goes back to Free; **Reactivate subscription** undoes it. After a failed payment it stops at once instead, and the unpaid invoice is voided: nothing is owed. The payment card and the **Invoices**, with their receipts, are in the same tab. Prices are excluding VAT: see the [pricing](https://semchat.io/en/pricing). ### Workspaces and members Workspaces, their settings, members, roles and invitations. (https://semchat.io/en/docs/workspaces) #### Workspaces - **Create a workspace**, in the user menu: a new space with its own sites, conversations, tasks, connectors, plan and credits. Switch from the same menu. - **Settings → Workspace**: the name, **Custom instructions** (the client, industry, language or constraints semchat keeps in mind in every conversation) and **Your company** (name, website, SIREN, address, logo, used on exported PDFs). The owner and admins edit them. - **Delete this workspace** is for the owner only, and not possible for your personal or only workspace. The other members have **Leave this workspace**. #### Members and roles | Role | What they can do | | --- | --- | | **Owner** | Everything, including deleting the workspace. The owner can’t be removed, and ownership can’t be transferred. | | **Admin** | Invite, cancel invitations, change roles and remove members; billing, skills and API keys. | | **Member** | Use the sites, conversations, tasks and connectors. | #### Invite someone **Settings → Members**, **Invite by email**, choose admin or member, then **Send invitation**. The email’s link is valid 7 days: the person signs in or creates an account with that address, then accepts. > There is no limit on the number of members: they share the workspace’s credits. ### Your account Profile, language, password, sessions, emails, your data and deleting the account. (https://semchat.io/en/docs/account) | Settings tab | What is there | | --- | --- | | **General** | First and last name, avatar, appearance (system, light, dark), the chat font, the site icon and the interface language. | | **Account** | Your email (read-only), your password (create one after signing up with Google, or change it), the signed-in devices with **Sign out everywhere**, whether you get semchat’s news and offers, and **Delete my account**. | | **Privacy** | **Download my data**: a file with your profile and the conversations you created. | > Deleting the account deletes every workspace you own (their subscriptions end at the end of the period), and it can’t be undone. ### The affiliate program Recommend semchat and earn 20 % of what your referrals pay for 12 months. (https://semchat.io/en/docs/affiliation) **Settings → Affiliation**: recommend semchat and earn 20 % of what the customers you refer pay, subscriptions and credit packs, for 12 months. 1. **Connect Stripe**: Set up payouts first with **Connect Stripe**. It takes a few minutes. 2. **Share your link**: Your referral link, ready-made messages and your stats then appear. 3. **Get paid**: A commission becomes available about 30 days after the purchase. Payouts go out on the 15th of each month once the available balance reaches 50 €; a smaller balance carries over. #### The rules - A referral is remembered for 30 days after the click. - Referring yourself doesn’t count, and a refund is taken off the next payout. - An active affiliate can create up to 3 promo codes, to say out loud in a video. A customer who types one at checkout gets 10 % off their subscription and becomes your referral for 12 months from that day, unless another affiliate already referred them. More on the [affiliate program’s page](https://semchat.io/en/affiliation). ## API & MCP semchat from your own code or from your AI assistant. ### Getting started Create a key, make your first call and read the answers. (https://semchat.io/en/docs/api) Everything you do in semchat, from your own code (the **API**) or from your AI assistant (**MCP**): your sites, their analysis, action plans, keywords, competitors, backlinks, documents, scheduled tasks and the semchat chat. The same actions as in the app, at the same prices. #### Get a key 1. **Open Settings → API & MCP**: In your workspace, in semchat. Only the owner and admins create and revoke keys. 2. **Create a key**: Give it a name, then copy it: it is shown only once. 3. **Revoke it if it leaks**: **Revoke**, in the same tab: the key stops working at once. > A key acts on the whole workspace. Keep it on a server, never in a public site or app. #### Authentication Every request carries the key in the `Authorization: Bearer` header (or `X-API-Key`). The base URL is `https://app.semchat.io/api/v1`. Bodies and answers are JSON. ```bash curl https://app.semchat.io/api/v1/sites \ -H "Authorization: Bearer sk_live_…" ``` Without a valid key, the answer is a `401`: see [Errors and limits](https://semchat.io/en/docs/api-errors). #### A first site Create a site and start its analysis in the same call. The analysis is billed; `needs_credits` says when the credits could not pay for it. ```bash curl -X POST https://app.semchat.io/api/v1/sites \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"name": "My shop", "site_url": "https://myshop.com", "auto_analyze": true}' ``` Then read its action plan with [List todos](https://semchat.io/en/docs/api-action-plan#list-todos), or ask the chat about it with [Send site message](https://semchat.io/en/docs/api-conversations#send-site-message). #### Answers - An answer is `{ "data": … }`: one object, or a list with every item. - Dates are ISO 8601 in UTC, and ids are UUIDs. - Credits never appear as raw numbers, only as a share of the period: [Get workspace](https://semchat.io/en/docs/api-workspace#get-workspace), [Get usage](https://semchat.io/en/docs/api-workspace#get-usage). #### What a key can see A key belongs to one workspace: it sees that workspace’s sites and conversations and nothing else, and it acts with the rights of the member who created it. #### The OpenAPI document The whole reference as OpenAPI 3.1, to import into Postman, Insomnia or a client generator: [openapi.json](https://semchat.io/openapi.json). - [MCP](https://semchat.io/en/docs/mcp): semchat in Claude, Cursor or any MCP client, with no code. - [What it costs](https://semchat.io/en/docs/api-costs): Reading is free; work uses the workspace’s credits. - [Errors and limits](https://semchat.io/en/docs/api-errors): Error codes, and how many calls a minute. - [Sites](https://semchat.io/en/docs/api-sites): The first operations of the reference. ### MCP Plug semchat into Claude, Cursor or any MCP client, with no code. (https://semchat.io/en/docs/mcp) MCP plugs semchat into an AI assistant with no code. The assistant sees semchat’s tools and uses them on its own: “what’s left in the action plan for myshop.com?”, “add these keywords”, “run a new analysis”. Every operation of the reference is a tool with the same name, shown under each one: its path arguments and body fields are the tool’s arguments. The same key, the same workspace and the same prices as the API. #### The server | Setting | Value | | --- | --- | | Server URL | `https://app.semchat.io/mcp/sse` | | Header | `X-API-Key: ` | > The same setup, ready to copy with your key, is under your keys in **Settings → API & MCP**. #### Claude Code ```bash claude mcp add --transport http semchat https://app.semchat.io/mcp/sse --header "X-API-Key: sk_live_…" ``` #### Cursor In `~/.cursor/mcp.json`: ```json { "mcpServers": { "semchat": { "url": "https://app.semchat.io/mcp/sse", "headers": { "X-API-Key": "sk_live_…" } } } } ``` #### Claude Desktop **Settings → Developer → Edit config**, add the server, then restart Claude. It needs Node.js. ```json { "mcpServers": { "semchat": { "command": "npx", "args": ["-y", "mcp-remote", "https://app.semchat.io/mcp/sse", "--header", "X-API-Key:sk_live_…"] } } } ``` #### Other clients - VS Code (GitHub Copilot), Windsurf, OpenAI’s Codex and Gemini CLI: the server URL and the header, in their own MCP settings. - ChatGPT can’t connect yet: its connectors don’t send a key. #### How the tools answer - A tool that sends a chat message waits for the whole answer and returns it. - An error comes back as a tool error whose message is `CODE: message`, with the API’s [error codes](https://semchat.io/en/docs/api-errors). - Up to 30 tool calls a minute per workspace. ### What it costs Reading is free; work is billed from the workspace’s credits, as in the app. (https://semchat.io/en/docs/api-costs) The same rule as in the app, because the API and MCP run the app’s own code: **reading is free, and work is billed from the workspace’s credits exactly as if you had done it in semchat**. Each operation of the reference says which it is. | | What | | --- | --- | | **Free** | Everything you read: sites, analyses, action plans, keywords, competitors, backlinks already fetched, documents, conversations, usage. And what you create, change or delete that costs nothing: a site, a task, a keyword, a conversation, a member… | | **Billed** | Running an analysis, profiling a competitor, refreshing backlinks, each message to the chat and each run of a scheduled task, in credits, exactly as in the app. | #### When credits run out A billed operation the credits can’t pay for answers `402 INSUFFICIENT_TOKENS`, and nothing runs. Top up or change plan in the app. [Get usage](https://semchat.io/en/docs/api-workspace#get-usage) shows the share of the period used. #### Plans The API and MCP work on every plan, Free included, with the same keys. A Free account that has never paid reads the same partial analysis as in the app: a list with hidden items comes with a `locked` block (how many are hidden, and the link to the plans), and a competitor’s backlinks or a hidden competitor’s analysis answer `403 PLAN_LIMIT_EXCEEDED`. The first payment, a top-up or a subscription, lifts it for good. See [Plans, credits and top-ups](https://semchat.io/en/docs/billing) for the rest. ### Errors and limits The error codes, what they mean, and how many calls a minute. (https://semchat.io/en/docs/api-errors) An error answers `{ "error": { "code": "…", "message": "…" } }` with its HTTP status. Over MCP, the tool error’s message is `CODE: message`. Branch on the code, not on the message. #### Error codes | Status | Code | When | | --- | --- | --- | | `400` | `INVALID_INPUT` | The body or an argument doesn’t match the operation: `details` lists the fields at fault. | | `401` | `MISSING_API_KEY`, `INVALID_API_KEY`, `EXPIRED_API_KEY`, `WORKSPACE_DELETED` | No key, an unknown or revoked key, an expired key, or its workspace was deleted. | | `402` | `INSUFFICIENT_TOKENS` | A billed operation, and the workspace’s credits can’t pay for it. | | `403` | `FORBIDDEN` | The key’s creator isn’t allowed to do this in the workspace: the same rule as in the app. | | `403` | `PLAN_LIMIT_EXCEEDED` | The workspace’s plan doesn’t include it: on an account that has never paid, a competitor’s backlinks or a hidden competitor’s analysis. | | `404` | `NOT_FOUND` | No such site, conversation, task… in this workspace. | | `409` | `CONFLICT` | Already running, or in a state that forbids it. | | `429` | `RATE_LIMITED` | Too many requests for the workspace: `Retry-After` says when to retry. | | `503` | `SERVICE_UNAVAILABLE` | A service the operation needs is briefly unavailable: retry later. | | `500` | `INTERNAL_ERROR` | Our fault: retry later. | ```json { "error": { "code": "INSUFFICIENT_TOKENS", "message": "Workspace is out of tokens for this period." } } ``` #### Rate limits | | Per workspace | | --- | --- | | API | 120 requests a minute | | MCP | 30 tool calls a minute | Over the limit, the answer is `429 RATE_LIMITED`, with a `Retry-After` header that says when to retry. ## API reference Every operation of the API, which is also an MCP tool. ### Workspace The workspace, its usage, search, skills, tool preferences and connectors. (https://semchat.io/en/docs/api-workspace) 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](https://semchat.io/en/docs/api-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 `GET /workspace` · Free · MCP tool `get_workspace` 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. Request: ```bash curl https://app.semchat.io/api/v1/workspace \ -H "Authorization: Bearer sk_live_…" ``` Response 200: ```json { "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 /usage` · Free · MCP tool `get_usage` The current period’s usage, in percent, split by category. Request: ```bash curl https://app.semchat.io/api/v1/usage \ -H "Authorization: Bearer sk_live_…" ``` Response 200: ```json { "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 /skills` · Free · MCP tool `list_skills` The skills available to the workspace’s chat. Request: ```bash curl https://app.semchat.io/api/v1/skills \ -H "Authorization: Bearer sk_live_…" ``` Response 200: ```json { "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 /connectors` · Free · MCP tool `list_connectors` Tools connected at workspace level (Search Console, GA4, Slack, Notion…). - Most connections are per site: see list_site_connectors. Request: ```bash curl https://app.semchat.io/api/v1/connectors \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. #### Search workspace `POST /search` · Free · MCP tool `search_workspace` 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. | Argument | Type | Description | | --- | --- | --- | | `query` (required) | string | What to look for, accents and case aside. Empty: the newest of each kind. (up to 100 characters) | | `limit` (optional) | integer | At most this many of each kind (default and maximum 50). (≥ 1, ≤ 50) | Request: ```bash 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 /workspace` · Free · MCP tool `update_workspace` 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. | Argument | Type | Description | | --- | --- | --- | | `name` (optional) | string | (1–255 characters) | | `description` (optional) | string \| null | | | `custom_instructions` (optional) | string \| null | Instructions the assistant follows in every conversation of the workspace. | | `company_name` (optional) | string \| null | | | `company_website` (optional) | string \| null | | | `company_siren` (optional) | string \| null | The company’s registration number. | | `company_address` (optional) | string \| null | | Request: ```bash 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 · MCP tool `set_skill` 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. | Argument | Type | Description | | --- | --- | --- | | `skillId` (in the path) | string | Its id. | | `enabled` (required) | boolean | | Request: ```bash 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/tools` · Free · MCP tool `list_tool_prefs` 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. Request: ```bash 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}/tools` · Free · MCP tool `list_site_tool_prefs` 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. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/sites/{siteId}/tools \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. #### Set tool pref `PATCH /workspace/tools` · Free · MCP tool `set_tool_pref` Turn a tool on or off for the assistant, for the workspace or for one site. | Argument | Type | Description | | --- | --- | --- | | `tool_name` (required) | string | The tool, as list_tool_prefs names it. (1–64 characters) | | `enabled` (required) | boolean | | | `site_id` (optional) | string | Only for this site (default: the workspace). (at least 1 character) | Request: ```bash 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 · MCP tool `disconnect_connector` 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. | Argument | Type | Description | | --- | --- | --- | | `provider` (in the path) | string | Its id. | Request: ```bash 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 · MCP tool `disconnect_site_connector` Disconnect a tool connected to this site (its stored access is deleted). - provider as list_site_connectors shows it. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `provider` (in the path) | string | Its id. | Request: ```bash curl -X DELETE https://app.semchat.io/api/v1/sites/{siteId}/connectors/{provider} \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. ### Members The workspace’s members, their roles and the invitations. (https://semchat.io/en/docs/api-members) 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](https://semchat.io/en/docs/api-costs)). | Operation | Call | | | --- | --- | --- | | List members | `GET /workspace/members` | Free | | List invitations | `GET /workspace/invitations` | Free | | Invite member | `POST /workspace/invitations` | Free | | Cancel invitation | `DELETE /workspace/invitations/{invitationId}` | Free | | Update member | `PATCH /workspace/members/{userId}` | Free | | Remove member | `DELETE /workspace/members/{userId}` | Free | #### List members `GET /workspace/members` · Free · MCP tool `list_members` The members of the workspace and their role. Request: ```bash curl https://app.semchat.io/api/v1/workspace/members \ -H "Authorization: Bearer sk_live_…" ``` Response 200: ```json { "data": [ { "user_id": "01995d03-8ea0-7e30-9bc8-4a6a79a79b4f", "name": "Olivia Owner", "email": "owner@example.com", "role": "owner", "joined_at": "2025-09-18T13:28:58.000Z" }, { "user_id": "01995d05-6360-74e9-8aa2-63377289227a", "name": "Adam Admin", "email": "admin@example.com", "role": "admin", "joined_at": "2026-07-15T13:26:58.000Z" } ] } ``` #### List invitations `GET /workspace/invitations` · Free · MCP tool `list_invitations` The workspace’s pending invitations. - Owner or admin only (the role of the key’s creator): 403 FORBIDDEN otherwise. Request: ```bash curl https://app.semchat.io/api/v1/workspace/invitations \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. #### Invite member `POST /workspace/invitations` · Free · MCP tool `invite_member` Invite someone to the workspace by email: they receive the invitation email, valid 7 days. - Owner or admin only (the role of the key’s creator): 403 FORBIDDEN otherwise. - 409 CONFLICT when the email is already a member or already invited. | Argument | Type | Description | | --- | --- | --- | | `email` (required) | string | | | `role` (required) | string | admin or member (default). (admin \| member) | Request: ```bash curl -X POST https://app.semchat.io/api/v1/workspace/invitations \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"email": "name@example.com", "role": "admin"}' ``` Answers 201 with `{ "data": … }`. #### Cancel invitation `DELETE /workspace/invitations/{invitationId}` · Free · MCP tool `cancel_invitation` Cancel an invitation: its link stops working. - Owner or admin only (the role of the key’s creator): 403 FORBIDDEN otherwise. | Argument | Type | Description | | --- | --- | --- | | `invitationId` (in the path) | string | Its id. | Request: ```bash curl -X DELETE https://app.semchat.io/api/v1/workspace/invitations/{invitationId} \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. #### Update member `PATCH /workspace/members/{userId}` · Free · MCP tool `update_member` Change a member’s role (admin or member). - Owner or admin only (the role of the key’s creator): 403 FORBIDDEN otherwise. - userId as list_members shows it. The owner’s role can’t be changed. | Argument | Type | Description | | --- | --- | --- | | `userId` (in the path) | string | Its id. | | `role` (required) | string | (admin \| member) | Request: ```bash curl -X PATCH https://app.semchat.io/api/v1/workspace/members/{userId} \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"role": "admin"}' ``` Answers 200 with `{ "data": … }`. #### Remove member `DELETE /workspace/members/{userId}` · Free · MCP tool `remove_member` Remove a member from the workspace. - Owner or admin, except to remove yourself (the key’s creator leaves the workspace). The owner can’t be removed. | Argument | Type | Description | | --- | --- | --- | | `userId` (in the path) | string | Its id. | Request: ```bash curl -X DELETE https://app.semchat.io/api/v1/workspace/members/{userId} \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. ### Sites Sites, their analysis, health and accessibility. (https://semchat.io/en/docs/api-sites) 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](https://semchat.io/en/docs/api-costs)). | Operation | Call | | | --- | --- | --- | | List sites | `GET /sites` | Free | | Create site | `POST /sites` | Free | | Get site | `GET /sites/{siteId}` | Free | | Analyze site | `POST /sites/{siteId}/analyze` | Billed | | List site connectors | `GET /sites/{siteId}/connectors` | Free | | Update site | `PATCH /sites/{siteId}` | Free | | Delete site | `DELETE /sites/{siteId}` | Free | | Set site favorite | `PATCH /sites/{siteId}/favorite` | Free | | Get site health | `GET /sites/{siteId}/health` | Free | | Get site accessibility | `GET /sites/{siteId}/accessibility` | Free | | Get accessibility rule | `GET /sites/{siteId}/accessibility/{ruleId}` | Free | #### List sites `GET /sites` · Free · MCP tool `list_sites` Every site of the workspace. Request: ```bash curl https://app.semchat.io/api/v1/sites \ -H "Authorization: Bearer sk_live_…" ``` Response 200: ```json { "data": [ { "id": "01a08133-4de0-7b5b-87f5-c4c169f01517", "name": "Alpha Conseil", "site_url": "https://alpha.example.com", "analysis_status": "ready", "created_at": "2026-09-08T13:26:58.000Z" }, { "id": "01a0ce72-b1e0-738d-9205-34630681ef77", "name": "Beta Shop", "site_url": "https://beta.example.com", "analysis_status": "idle", "created_at": "2026-09-23T13:26:58.000Z" } ] } ``` #### Create site `POST /sites` · Free · MCP tool `create_site` Create a site, and optionally start its analysis. | Argument | Type | Description | | --- | --- | --- | | `name` (required) | string | The site’s name. (1–255 characters) | | `site_url` (optional) | string | Its address. Needed for an analysis. (up to 500 characters) | | `description` (optional) | string | (up to 2000 characters) | | `auto_analyze` (optional) | boolean | Start the analysis right away (billed). Skipped without credits: needs_credits is then true. | Request: ```bash curl -X POST https://app.semchat.io/api/v1/sites \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"name": "…"}' ``` Response 201: ```json { "data": { "id": "01a168f1-9d83-7253-a7ec-af716d6279e1", "analysis_status": "idle", "needs_credits": false } } ``` #### Get site `GET /sites/{siteId}` · Free · MCP tool `get_site` One site, with everything its last analysis stored (overview, health, accessibility, keywords…). | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/sites/{siteId} \ -H "Authorization: Bearer sk_live_…" ``` Response 200: ```json { "data": { "id": "01a08133-4de0-7b5b-87f5-c4c169f01517", "name": "Alpha Conseil", "site_url": "https://alpha.example.com", "description": null, "analysis_status": "ready", "analysis_stage": null, "last_analyzed_at": "2026-10-21T13:26:58.000Z", "site_context": { "description": "Alpha Conseil, agence de référencement naturel pour les PME lyonnaises.", "platform": "inconnu", "language": "fr", "country": "FR", "positioning": "Le SEO durable et expliqué sans jargon pour les PME.", "primaryTopics": [ "audit SEO", "contenus" ], "targetKeywords": [ "…", "…" ], "kpis": { "organic_traffic_estimate": 1840, "keywords_count": 312, "authority_score": null }, "suggestedInstructions": "Parle simplement à des dirigeants de PME non techniques.", "analyzedAt": "2026-10-21T13:26:58.272Z", "contentLang": "fr", "health": { "score": 72, "label": "good", "pagesChecked": 6, "items": [ "…", "…" ], "checkedAt": "2026-10-21T13:26:58.272Z" }, "accessibility": { "score": 78, "totalIssues": 4, "byLevel": "…", "findings": [ "…", "…" ], "checkedAt": "2026-10-21T13:26:58.272Z" }, "pageVisibility": { "checkedPages": 6, "indexable": 6, "noindex": 0, "visibleButShouldnt": "…", "hiddenButShould": "…", "checkedAt": "2026-10-21T13:26:58.272Z" }, "actionPlan": { "scorecard": "…", "focus": "…", "priorityOrder": [ "content", "backlinks" ], "summary": "Un site sain qui manque de contenus et de liens.", "generatedAt": "2026-10-21T13:26:58.272Z" } }, "instructions": null, "writing_style": null, "technologies": [], "favorite": false, "created_at": "2026-09-08T13:26:58.000Z" } } ``` #### Analyze site `POST /sites/{siteId}/analyze` · Billed · MCP tool `analyze_site` Run (or re-run) the site’s full analysis: crawl, technical health, competitors, keywords, action plan. - Runs in the background (a few minutes): read get_site until analysis_status is ready or error. - Billed exactly like an analysis started in the app. 402 INSUFFICIENT_TOKENS without credits. - A re-analysis keeps the existing action plan and adds what’s new. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | Request: ```bash curl -X POST https://app.semchat.io/api/v1/sites/{siteId}/analyze \ -H "Authorization: Bearer sk_live_…" ``` Answers 202 with `{ "data": … }`. #### List site connectors `GET /sites/{siteId}/connectors` · Free · MCP tool `list_site_connectors` The tools connected to this site. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/sites/{siteId}/connectors \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. #### Update site `PATCH /sites/{siteId}` · Free · MCP tool `update_site` Edit the site’s settings: name, address, description, instructions, writing style, technologies. - Only the fields given are changed. Answers the site with its settings. - Changing the address doesn’t re-run the analysis: call analyze_site for that. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `name` (optional) | string | The site’s name (can’t be blank). (1–255 characters) | | `site_url` (optional) | string \| null | Its address. Blank or null clears it. | | `description` (optional) | string \| null | Blank or null clears it. | | `instructions` (optional) | string \| null | What the assistant keeps in mind for this site. Blank or null clears it. | | `writing_style` (optional) | string \| null | The voice of the articles written for the site; null clears it. | | `technologies` (optional) | array | The technologies the site runs on (their keys); [] clears them. | Request: ```bash curl -X PATCH https://app.semchat.io/api/v1/sites/{siteId} \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"name": "…"}' ``` Answers 200 with `{ "data": … }`. #### Delete site `DELETE /sites/{siteId}` · Free · MCP tool `delete_site` Delete the site. - Soft delete, as in the app: the site leaves the lists and its endpoints answer 404. Nothing else changes: its conversations, documents and saved data are kept. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | Request: ```bash curl -X DELETE https://app.semchat.io/api/v1/sites/{siteId} \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. #### Set site favorite `PATCH /sites/{siteId}/favorite` · Free · MCP tool `set_site_favorite` Star or unstar the site. - Starring doesn’t count as activity: the site keeps its place in the “Activity” sort. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `favorite` (required) | boolean | true stars the site, false unstars it. | Request: ```bash curl -X PATCH https://app.semchat.io/api/v1/sites/{siteId}/favorite \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"favorite": true}' ``` Answers 200 with `{ "data": … }`. #### Get site health `GET /sites/{siteId}/health` · Free · MCP tool `get_site_health` The site’s technical health: the last analysis’s score and issues, the score’s history, and which issue counts changed since the analysis before. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/sites/{siteId}/health \ -H "Authorization: Bearer sk_live_…" ``` Response 200: ```json { "data": { "health": { "score": 72, "label": "good", "pages_checked": 6, "items": [ "…", "…" ], "checked_at": "2026-10-21T13:26:58.272Z" }, "history": [ { "score": 61, "label": "fair", "pages_checked": 6, "analyzed_at": "2026-09-23T13:26:58.000Z" }, { "score": 72, "label": "good", "pages_checked": 6, "analyzed_at": "2026-10-21T13:26:58.000Z" } ], "changes": [ { "key": "noDescription", "before": 3, "after": 1 }, { "key": "thin", "before": 3, "after": 2 } ] } } ``` #### Get site accessibility `GET /sites/{siteId}/accessibility` · Free · MCP tool `get_site_accessibility` The site’s accessibility (WCAG 2.1 A and AA): the last analysis’s score and findings by rule, and the score’s history. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/sites/{siteId}/accessibility \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. #### Get accessibility rule `GET /sites/{siteId}/accessibility/{ruleId}` · Free · MCP tool `get_accessibility_rule` Every page an accessibility rule fails on (a finding’s rule_id), with the failing elements. - pages is capped; page_count is the exact number of pages affected. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `ruleId` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/sites/{siteId}/accessibility/{ruleId} \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. ### Action plan A site’s action plan: list, add, change and delete its tasks. (https://semchat.io/en/docs/api-action-plan) 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](https://semchat.io/en/docs/api-costs)). | Operation | Call | | | --- | --- | --- | | List todos | `GET /sites/{siteId}/todos` | Free | | Create todo | `POST /sites/{siteId}/todos` | Free | | Update todo | `PATCH /sites/{siteId}/todos/{todoId}` | Free | | Delete todo | `DELETE /sites/{siteId}/todos/{todoId}` | Free | #### List todos `GET /sites/{siteId}/todos` · Free · MCP tool `list_todos` The site’s action plan. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/sites/{siteId}/todos \ -H "Authorization: Bearer sk_live_…" ``` Response 200: ```json { "data": [ { "id": "01a15ea4-c1e0-7c64-bc14-c499bd6f1b83", "title": "Corriger le point technical n°1", "description": "Corriger le point technical n°1 - détail.", "category": "technical", "priority": "high", "status": "a_faire", "source": "audit_auto", "created_at": "2026-10-21T13:26:58.000Z" }, { "id": "01a15ea4-c1e0-74b9-8ca0-f4c3410b0f0f", "title": "Corriger le point technical n°2", "description": "Corriger le point technical n°2 - détail.", "category": "technical", "priority": "medium", "status": "fait", "source": "audit_auto", "created_at": "2026-10-21T13:27:58.000Z" } ] } ``` #### Create todo `POST /sites/{siteId}/todos` · Free · MCP tool `create_todo` Add a task to the site’s action plan. - Added as a manual task (source manuel), to do (status a_faire). Answers the task. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `title` (required) | string | What to do. (1–500 characters) | | `description` (optional) | string | (up to 4000 characters) | | `priority` (optional) | string | high, medium (default) or low. (high \| medium \| low) | | `category` (optional) | string | The plan pillar it belongs to. Default technical. (technical \| content \| accessibility \| backlinks \| competitors) | | `source_lang` (optional) | string | The language the text is written in (e.g. "fr", "en"). Omitted: the site’s content language. (2–5 characters) | Request: ```bash curl -X POST https://app.semchat.io/api/v1/sites/{siteId}/todos \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"title": "…"}' ``` Response 201: ```json { "data": { "id": "01a168f1-9dac-7584-b809-fc4ed6d1cffe", "title": "Add alt text to the gallery images", "description": null, "category": "technical", "priority": "high", "status": "a_faire", "source": "manuel", "created_at": "2026-10-23T13:27:07.000Z" } } ``` #### Update todo `PATCH /sites/{siteId}/todos/{todoId}` · Free · MCP tool `update_todo` Change a task of the action plan: its status (to do, in progress, done, ignored), title, description or priority. - Answers the task as it now is. - Text is returned as stored, in the language it was written in (source_lang; null = the site’s content language). The app translates it on display; the API does not. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `todoId` (in the path) | string | Its id. | | `status` (optional) | string | a_faire (to do), en_cours (in progress), fait (done) or ignore (ignored). (a_faire \| en_cours \| fait \| ignore) | | `title` (optional) | string | (1–500 characters) | | `description` (optional) | string \| null | | | `priority` (optional) | string | (high \| medium \| low) | | `source_lang` (optional) | string | The language of the new title / description. Ignored when neither changes. (2–5 characters) | Request: ```bash curl -X PATCH https://app.semchat.io/api/v1/sites/{siteId}/todos/{todoId} \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"status": "a_faire"}' ``` Answers 200 with `{ "data": … }`. #### Delete todo `DELETE /sites/{siteId}/todos/{todoId}` · Free · MCP tool `delete_todo` Remove a task from the action plan. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `todoId` (in the path) | string | Its id. | Request: ```bash curl -X DELETE https://app.semchat.io/api/v1/sites/{siteId}/todos/{todoId} \ -H "Authorization: Bearer sk_live_…" ``` Answers 204 with `{ "data": … }`. ### Keywords A site’s keywords: list, add, change and delete them. (https://semchat.io/en/docs/api-keywords) 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](https://semchat.io/en/docs/api-costs)). | Operation | Call | | | --- | --- | --- | | List keywords | `GET /sites/{siteId}/keywords` | Free | | Add keyword | `POST /sites/{siteId}/keywords` | Free | | Update keyword | `PATCH /sites/{siteId}/keywords/{keywordId}` | Free | | Delete keyword | `DELETE /sites/{siteId}/keywords/{keywordId}` | Free | #### List keywords `GET /sites/{siteId}/keywords` · Free · MCP tool `list_keywords` The site’s target keywords, from its analysis or added by hand, with their volume, difficulty and current position. - Text is returned as stored, in the language it was written in (source_lang; null = the site’s content language). The app translates it on display; the API does not. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/sites/{siteId}/keywords \ -H "Authorization: Bearer sk_live_…" ``` Response 200: ```json { "data": [ { "id": "01a15ea4-c1e0-7957-b667-9b025ed3641e", "keyword": "agence seo lyon", "volume": 1900, "difficulty": 45, "cpc": 1.8, "competition": 40, "current_position": 4, "traffic": 475, "url": "https://alpha.example.com/services", "intent": "commercial", "priority": "high", "rationale": "Opportunité sur « agence seo lyon ».", "source": "auto", "source_lang": "fr", "created_at": "2026-10-21T13:26:58.000Z" }, { "id": "01a15ea4-c1e0-7e93-9a50-38742b693311", "keyword": "audit seo", "volume": 2400, "difficulty": 60, "cpc": 1.8, "competition": 40, "current_position": 12, "traffic": 200, "url": "https://alpha.example.com/services", "intent": "commercial", "priority": "high", "rationale": "Opportunité sur « audit seo ».", "source": "auto", "source_lang": "fr", "created_at": "2026-10-21T13:26:58.000Z" } ] } ``` #### Add keyword `POST /sites/{siteId}/keywords` · Free · MCP tool `add_keyword` Add a target keyword to the site. - Stored as given, as a manual keyword: no keyword data is fetched (nothing billed). Answers the keyword. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `keyword` (required) | string | The keyword. (1–255 characters) | | `volume` (optional) | string \| null | Its monthly search volume, if known. | | `difficulty` (optional) | string \| null | Its difficulty, 0–100, if known. | | `intent` (optional) | string \| null | informational, commercial, transactional or navigational. | | `priority` (optional) | string | high, medium (default) or low. (high \| medium \| low) | | `rationale` (optional) | string \| null | Why to target it. | | `source_lang` (optional) | string | The language the text is written in (e.g. "fr", "en"). Omitted: the site’s content language. (2–5 characters) | Request: ```bash curl -X POST https://app.semchat.io/api/v1/sites/{siteId}/keywords \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"keyword": "…"}' ``` Answers 201 with `{ "data": … }`. #### Update keyword `PATCH /sites/{siteId}/keywords/{keywordId}` · Free · MCP tool `update_keyword` Change a target keyword: the keyword, its figures, intent, priority or rationale. - Answers the keyword as it now is. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `keywordId` (in the path) | string | Its id. | | `keyword` (optional) | string | (1–255 characters) | | `volume` (optional) | string \| null | | | `difficulty` (optional) | string \| null | | | `intent` (optional) | string \| null | | | `priority` (optional) | string | (high \| medium \| low) | | `rationale` (optional) | string \| null | | | `source_lang` (optional) | string | The language of the new keyword / rationale. Ignored when neither changes. (2–5 characters) | Request: ```bash curl -X PATCH https://app.semchat.io/api/v1/sites/{siteId}/keywords/{keywordId} \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"keyword": "…"}' ``` Answers 200 with `{ "data": … }`. #### Delete keyword `DELETE /sites/{siteId}/keywords/{keywordId}` · Free · MCP tool `delete_keyword` Remove a target keyword from the site. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `keywordId` (in the path) | string | Its id. | Request: ```bash curl -X DELETE https://app.semchat.io/api/v1/sites/{siteId}/keywords/{keywordId} \ -H "Authorization: Bearer sk_live_…" ``` Answers 204 with `{ "data": … }`. ### Content ideas A site’s content ideas: list, add and delete them. (https://semchat.io/en/docs/api-content-ideas) 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](https://semchat.io/en/docs/api-costs)). | Operation | Call | | | --- | --- | --- | | List content ideas | `GET /sites/{siteId}/content-ideas` | Free | | Add content idea | `POST /sites/{siteId}/content-ideas` | Free | | Delete content idea | `DELETE /sites/{siteId}/content-ideas/{ideaId}` | Free | #### List content ideas `GET /sites/{siteId}/content-ideas` · Free · MCP tool `list_content_ideas` The site’s content ideas: articles to write, each with its keyword, angle and rationale. - Text is returned as stored, in the language it was written in (source_lang; null = the site’s content language). The app translates it on display; the API does not. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/sites/{siteId}/content-ideas \ -H "Authorization: Bearer sk_live_…" ``` Response 200: ```json { "data": [ { "id": "01a15ea4-c1e0-7736-9a1d-b79cfd3e485e", "title": "Combien coûte un audit SEO ?", "content_type": "faq", "primary_keyword": "référencement naturel pme", "volume": 880, "difficulty": 35, "intent": "informational", "angle": "Angle : combien coûte un audit seo ?", "rationale": "Fort intérêt, peu de concurrence.", "source": "auto", "source_lang": "fr", "created_at": "2026-10-21T13:26:58.000Z" }, { "id": "01a15ea4-c1e0-7aec-b48b-474893e6ef98", "title": "Les 7 erreurs SEO des PME", "content_type": "listicle", "primary_keyword": "stratégie de contenu seo", "volume": 590, "difficulty": 40, "intent": "informational", "angle": "Angle : les 7 erreurs seo des pme", "rationale": "Fort intérêt, peu de concurrence.", "source": "auto", "source_lang": "fr", "created_at": "2026-10-21T13:26:58.000Z" } ] } ``` #### Add content idea `POST /sites/{siteId}/content-ideas` · Free · MCP tool `add_content_idea` Add a content idea to the site. - Added as a manual idea. Answers the idea. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `title` (required) | string | The article’s title. (1–300 characters) | | `content_type` (optional) | string \| null | blog_post, guide, comparison, faq, how_to, listicle or landing. | | `primary_keyword` (optional) | string \| null | The keyword it targets. | | `intent` (optional) | string \| null | informational, commercial, transactional or navigational. | | `angle` (optional) | string \| null | What the article should cover. | | `rationale` (optional) | string \| null | Why write it. | | `volume` (optional) | string \| null | | | `difficulty` (optional) | string \| null | | | `source_lang` (optional) | string | The language the text is written in (e.g. "fr", "en"). Omitted: the site’s content language. (2–5 characters) | Request: ```bash curl -X POST https://app.semchat.io/api/v1/sites/{siteId}/content-ideas \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"title": "…"}' ``` Answers 201 with `{ "data": … }`. #### Delete content idea `DELETE /sites/{siteId}/content-ideas/{ideaId}` · Free · MCP tool `delete_content_idea` Remove a content idea from the site. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `ideaId` (in the path) | string | Its id. | Request: ```bash curl -X DELETE https://app.semchat.io/api/v1/sites/{siteId}/content-ideas/{ideaId} \ -H "Authorization: Bearer sk_live_…" ``` Answers 204 with `{ "data": … }`. ### Competitors A site’s competitors, their analysis and their backlinks. (https://semchat.io/en/docs/api-competitors) 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](https://semchat.io/en/docs/api-costs)). | Operation | Call | | | --- | --- | --- | | List competitors | `GET /sites/{siteId}/competitors` | Free | | Add competitor | `POST /sites/{siteId}/competitors` | Free | | Delete competitor | `DELETE /sites/{siteId}/competitors/{competitorId}` | Free | | Profile competitor | `POST /sites/{siteId}/competitors/{competitorId}/profile` | Billed | | Get competitor backlinks | `GET /sites/{siteId}/competitors/{competitorId}/backlinks` | Billed | #### List competitors `GET /sites/{siteId}/competitors` · Free · MCP tool `list_competitors` The site’s competitors, with their profile once analysed. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/sites/{siteId}/competitors \ -H "Authorization: Bearer sk_live_…" ``` Response 200: ```json { "data": [ { "id": "01a15ea4-c1e0-7285-bdde-d36e70d2d1b9", "url": "https://comp1.example.com", "name": "Concurrent Un", "source": "auto", "profiled_at": "2026-10-21T13:26:58.000Z", "metrics": { "traffic": 5200, "keywords": 400, "overlap": 40, "reason": "Mêmes mots-clés à Lyon." }, "profile": { "summary": "Concurrent Un accompagne les PME.", "positioning": "Agence généraliste.", "topics": [ "SEO", "SEA" ], "strengths": [ "Notoriété" ], "tech": [ "wordpress" ], "pageCount": 24 } }, { "id": "01a15ea4-c1e0-7042-931d-3fa2cb1f4ffc", "url": "https://comp2.example.com", "name": "Concurrent Deux", "source": "auto", "profiled_at": "2026-10-21T13:26:58.000Z", "metrics": { "traffic": 4200, "keywords": 350, "overlap": 30, "reason": "Mêmes mots-clés à Lyon." }, "profile": { "summary": "Concurrent Deux accompagne les PME.", "positioning": "Agence généraliste.", "topics": [ "SEO", "SEA" ], "strengths": [ "Notoriété" ], "tech": [ "wordpress" ], "pageCount": 24 } } ] } ``` #### Add competitor `POST /sites/{siteId}/competitors` · Free · MCP tool `add_competitor` Add a competitor, and optionally profile it (billed). - Answers its id and `analyzing`: false when no analysis was started (none asked for, or no credits; the competitor is saved all the same). | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `url` (required) | string | The competitor’s address. (1–500 characters) | | `name` (optional) | string | (up to 255 characters) | | `auto_analyze` (optional) | boolean | Profile it in the background (billed). Skipped without credits. | Request: ```bash curl -X POST https://app.semchat.io/api/v1/sites/{siteId}/competitors \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"url": "https://example.com"}' ``` Answers 201 with `{ "data": … }`. #### Delete competitor `DELETE /sites/{siteId}/competitors/{competitorId}` · Free · MCP tool `delete_competitor` Remove a competitor from the site’s set. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `competitorId` (in the path) | string | Its id. | Request: ```bash curl -X DELETE https://app.semchat.io/api/v1/sites/{siteId}/competitors/{competitorId} \ -H "Authorization: Bearer sk_live_…" ``` Answers 204 with `{ "data": … }`. #### Profile competitor `POST /sites/{siteId}/competitors/{competitorId}/profile` · Billed · MCP tool `profile_competitor` Analyse a competitor (a shallow crawl of its site and an AI summary: what it does, its positioning, topics, strengths, its gaps against your site) and store it on the competitor. - Billed like the same analysis in the app (an AI call). 402 INSUFFICIENT_TOKENS without credits. - Without background, waits for the profile (up to a few minutes) and answers the competitor with it. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `competitorId` (in the path) | string | Its id. | | `background` (optional) | boolean | Answer at once (202, status analyzing) and store the profile when it lands: read list_competitors for it. | | `locale` (optional) | string | The language to write the profile in (fr, en, es, de, pt, it). Default: the key creator’s. (2–5 characters) | Request: ```bash curl -X POST https://app.semchat.io/api/v1/sites/{siteId}/competitors/{competitorId}/profile \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"background": true}' ``` Answers 200 with `{ "data": … }`. #### Get competitor backlinks `GET /sites/{siteId}/competitors/{competitorId}/backlinks` · Billed · MCP tool `get_competitor_backlinks` A competitor’s backlink numbers: rank (0–100), referring domains, backlinks, spam score. - Free when the site’s stored backlink profile (get_backlinks) already covers this competitor; otherwise one billed data call, as in the app. - 402 INSUFFICIENT_TOKENS without credits when a billed call would be needed. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `competitorId` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/sites/{siteId}/competitors/{competitorId}/backlinks \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. ### Backlinks A site’s backlinks, and refreshing them. (https://semchat.io/en/docs/api-backlinks) 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](https://semchat.io/en/docs/api-costs)). | Operation | Call | | | --- | --- | --- | | Get backlinks | `GET /sites/{siteId}/backlinks` | Free | | Refresh backlinks | `POST /sites/{siteId}/backlinks` | Billed | #### Get backlinks `GET /sites/{siteId}/backlinks` · Free · MCP tool `get_backlinks` The site’s stored backlink profile: its numbers, top referring domains, anchors and backlinks, the comparison with its top competitors and the link-gap opportunities. null until a first refresh. - stale is true once the profile is more than 7 days old: refresh_backlinks updates it. - probable_spam: the referring domains that look like spam (link farms, throwaway domains, casinos, no authority passed), kept out of referring_domains and never in opportunities. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/sites/{siteId}/backlinks \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. #### Refresh backlinks `POST /sites/{siteId}/backlinks` · Billed · MCP tool `refresh_backlinks` Fetch the site’s backlink profile again (the site and its top 3 competitors), store it and answer it. - Billed per data call, exactly as the app’s Refresh: about 10 calls. - 402 INSUFFICIENT_TOKENS when the credits can’t cover the refresh’s most expensive case, 409 CONFLICT while one runs for the site. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | Request: ```bash curl -X POST https://app.semchat.io/api/v1/sites/{siteId}/backlinks \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. ### Data and documents A site’s saved charts, KPI grids and documents. (https://semchat.io/en/docs/api-documents) 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](https://semchat.io/en/docs/api-costs)). | Operation | Call | | | --- | --- | --- | | List site data | `GET /sites/{siteId}/data` | Free | | List site documents | `GET /sites/{siteId}/documents` | Free | | Save data block | `POST /sites/{siteId}/data` | Free | | Delete data block | `DELETE /sites/{siteId}/data/{blockId}` | Free | #### List site data `GET /sites/{siteId}/data` · Free · MCP tool `list_site_data` The data blocks saved on the site: charts, KPI grids and site maps kept from conversations. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/sites/{siteId}/data \ -H "Authorization: Bearer sk_live_…" ``` Response 200: ```json { "data": [ { "id": "01a15ea4-c1e0-7157-becb-0b33c960722e", "type": "kpi_grid", "title": "Vue d'ensemble - alpha", "data": { "title": "Vue d'ensemble - alpha", "cards": [ "…", "…" ] }, "conversation_id": "01a1597c-9120-70b0-87de-f58bf6fe953e", "created_at": "2026-10-18T13:26:58.000Z" }, { "id": "01a15ea4-c1e0-730a-a3c7-1cf43b1cd203", "type": "chart", "title": "Trafic organique - alpha vs concurrents", "data": { "title": "Trafic organique - alpha vs concurrents", "type": "bar", "x_key": "domain", "y_keys": [ "trafic" ], "data": [ "…", "…" ], "format": "number", "unit": "visites/mois" }, "conversation_id": "01a15456-3520-7443-9b04-564ff63c5448", "created_at": "2026-10-17T13:26:58.000Z" } ] } ``` #### List site documents `GET /sites/{siteId}/documents` · Free · MCP tool `list_site_documents` The documents written for the site (articles, briefs…). | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/sites/{siteId}/documents \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. #### Save data block `POST /sites/{siteId}/data` · Free · MCP tool `save_data_block` Save a chart or a KPI grid on the site (as the app’s Save on a conversation’s chart). | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `type` (required) | string | chart or kpi_grid. (chart \| kpi_grid) | | `title` (required) | string | (1–500 characters) | | `data` (required) | object | The chart’s or KPI grid’s props, as a conversation’s block carries them. | | `conversation_id` (optional) | string | The conversation it comes from. (at least 1 character) | | `message_id` (optional) | string | The message it comes from: a message saves one block per title (409 CONFLICT). (at least 1 character) | Request: ```bash curl -X POST https://app.semchat.io/api/v1/sites/{siteId}/data \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"type": "chart", "title": "…", "data": {}}' ``` Answers 201 with `{ "data": … }`. #### Delete data block `DELETE /sites/{siteId}/data/{blockId}` · Free · MCP tool `delete_data_block` Delete a data block saved on the site. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `blockId` (in the path) | string | Its id. | Request: ```bash curl -X DELETE https://app.semchat.io/api/v1/sites/{siteId}/data/{blockId} \ -H "Authorization: Bearer sk_live_…" ``` Answers 204 with `{ "data": … }`. ### Conversations Conversations in the workspace or in a site, their messages, and sending one. (https://semchat.io/en/docs/api-conversations) 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](https://semchat.io/en/docs/api-costs)). | Operation | Call | | | --- | --- | --- | | Update conversation | `PATCH /conversations/{cid}` | Free | | Delete conversation | `DELETE /conversations/{cid}` | Free | | List conversations | `GET /conversations` | Free | | Create conversation | `POST /conversations` | Free | | Get conversation | `GET /conversations/{cid}` | Free | | List messages | `GET /conversations/{cid}/messages` | Free | | Send message | `POST /conversations/{cid}/messages` | Billed | | List conversation documents | `GET /conversations/{cid}/documents` | Free | | List site conversations | `GET /sites/{siteId}/conversations` | Free | | Create site conversation | `POST /sites/{siteId}/conversations` | Free | | Get site conversation | `GET /sites/{siteId}/conversations/{cid}` | Free | | List site messages | `GET /sites/{siteId}/conversations/{cid}/messages` | Free | | Send site message | `POST /sites/{siteId}/conversations/{cid}/messages` | Billed | #### Update conversation `PATCH /conversations/{cid}` · Free · MCP tool `update_conversation` Rename a conversation, or star / unstar it. - Acts on any conversation of the workspace, a site’s ones included (its cid is enough), as the app does. - Only the fields given are changed. Answers the conversation. | Argument | Type | Description | | --- | --- | --- | | `cid` (in the path) | string | Its id. | | `title` (optional) | string | Rename the conversation. (1–500 characters) | | `starred` (optional) | boolean | true stars it (starred_at = now), false unstars it. | Request: ```bash curl -X PATCH https://app.semchat.io/api/v1/conversations/{cid} \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"title": "…"}' ``` Answers 200 with `{ "data": … }`. #### Delete conversation `DELETE /conversations/{cid}` · Free · MCP tool `delete_conversation` Delete a conversation. - Acts on any conversation of the workspace, a site’s ones included (its cid is enough), as the app does. - Soft delete, as in the app: it leaves the lists and answers 404; its messages and the data saved from it are kept. | Argument | Type | Description | | --- | --- | --- | | `cid` (in the path) | string | Its id. | Request: ```bash curl -X DELETE https://app.semchat.io/api/v1/conversations/{cid} \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. #### List conversations `GET /conversations` · Free · MCP tool `list_conversations` The workspace conversations (not tied to a site). Request: ```bash curl https://app.semchat.io/api/v1/conversations \ -H "Authorization: Bearer sk_live_…" ``` Response 200: ```json { "data": [ { "id": "01a163c9-4920-773f-89fb-75ff608e07fe", "title": "Audit complet d'alpha", "site_id": null, "message_count": 2, "starred_at": "2026-10-22T13:31:58.000Z", "last_message_at": "2026-10-22T13:26:58.000Z", "created_at": "2026-10-22T13:24:58.000Z", "updated_at": "2026-10-22T13:26:58.000Z" }, { "id": "01a15ea2-ed20-7a5d-a415-afcd68358a91", "title": "Idées de contenu", "site_id": null, "message_count": 2, "starred_at": "2026-10-21T13:31:58.000Z", "last_message_at": "2026-10-21T13:26:58.000Z", "created_at": "2026-10-21T13:24:58.000Z", "updated_at": "2026-10-21T13:26:58.000Z" } ] } ``` #### Create conversation `POST /conversations` · Free · MCP tool `create_conversation` Start a workspace conversation. | Argument | Type | Description | | --- | --- | --- | | `title` (optional) | string | Its title (optional). (up to 500 characters) | Request: ```bash curl -X POST https://app.semchat.io/api/v1/conversations \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"title": "…"}' ``` Answers 201 with `{ "data": … }`. #### Get conversation `GET /conversations/{cid}` · Free · MCP tool `get_conversation` One conversation of the workspace (a site’s ones included). | Argument | Type | Description | | --- | --- | --- | | `cid` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/conversations/{cid} \ -H "Authorization: Bearer sk_live_…" ``` Response 200: ```json { "data": { "id": "01a163c9-4920-773f-89fb-75ff608e07fe", "title": "Audit complet d'alpha", "site_id": null, "message_count": 2, "starred_at": "2026-10-22T13:31:58.000Z", "last_message_at": "2026-10-22T13:26:58.000Z", "created_at": "2026-10-22T13:24:58.000Z", "updated_at": "2026-10-22T13:26:58.000Z" } } ``` #### List messages `GET /conversations/{cid}/messages` · Free · MCP tool `list_messages` A workspace conversation’s messages, oldest first (text, tool calls and results, charts, documents). | Argument | Type | Description | | --- | --- | --- | | `cid` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/conversations/{cid}/messages \ -H "Authorization: Bearer sk_live_…" ``` Response 200: ```json { "data": [ { "id": "01a15456-3520-7803-9dfd-670569df332f", "role": "user", "content": "C'est quoi le SEO ?", "parts": [ "…" ], "created_at": "2026-10-19T13:24:58.272Z" }, { "id": "01a15456-aa50-78f0-8c72-120a580ca098", "role": "assistant", "content": "Le référencement naturel.", "parts": [ "…", "…" ], "created_at": "2026-10-19T13:25:28.272Z" } ] } ``` #### Send message `POST /conversations/{cid}/messages` · Billed · MCP tool `send_message` Send a message: the assistant answers, using its tools (keyword data, crawl, competitors…) as in the app. - Attachments are stored like the app’s (any member of the workspace; an unsupported type or a file over 20 MB is INVALID_INPUT) and reach the assistant with the message. A request is 25 MB at most: about 18 MB of files once base64-encoded. - The API streams the answer as Server-Sent Events (Vercel AI SDK “UI message stream”); once finished, read it in full with the messages list. Over MCP, the tool waits for the end and returns the answer. - Billed in credits exactly like a chat turn in the app. | Argument | Type | Description | | --- | --- | --- | | `cid` (in the path) | string | Its id. | | `message` (required) | string | The user’s message. (at least 1 character) | | `attachments` (optional) | array | Files attached to the message, as in the app (the same types, 20 MB each at most). | | `stream` (optional) | boolean | Accepted for compatibility; the API answer always streams. | Request: ```bash curl -X POST https://app.semchat.io/api/v1/conversations/{cid}/messages \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"message": "…"}' ``` The answer streams as Server-Sent Events; once finished, read it in full with the messages list. Over MCP the tool waits for the end and returns the answer. #### List conversation documents `GET /conversations/{cid}/documents` · Free · MCP tool `list_conversation_documents` The documents written in a workspace conversation. | Argument | Type | Description | | --- | --- | --- | | `cid` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/conversations/{cid}/documents \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. #### List site conversations `GET /sites/{siteId}/conversations` · Free · MCP tool `list_site_conversations` A site’s conversations. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/sites/{siteId}/conversations \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. #### Create site conversation `POST /sites/{siteId}/conversations` · Free · MCP tool `create_site_conversation` Start a conversation on a site: the assistant knows that site. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `title` (optional) | string | Its title (optional). (up to 500 characters) | Request: ```bash curl -X POST https://app.semchat.io/api/v1/sites/{siteId}/conversations \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"title": "…"}' ``` Answers 201 with `{ "data": … }`. #### Get site conversation `GET /sites/{siteId}/conversations/{cid}` · Free · MCP tool `get_site_conversation` One of a site’s conversations. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `cid` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/sites/{siteId}/conversations/{cid} \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. #### List site messages `GET /sites/{siteId}/conversations/{cid}/messages` · Free · MCP tool `list_site_messages` A site conversation’s messages, oldest first. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `cid` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/sites/{siteId}/conversations/{cid}/messages \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. #### Send site message `POST /sites/{siteId}/conversations/{cid}/messages` · Billed · MCP tool `send_site_message` Send a message in a site conversation: the assistant answers with that site in mind. - Attachments are stored like the app’s (any member of the workspace; an unsupported type or a file over 20 MB is INVALID_INPUT) and reach the assistant with the message. A request is 25 MB at most: about 18 MB of files once base64-encoded. - The API streams the answer as Server-Sent Events (Vercel AI SDK “UI message stream”); once finished, read it in full with the messages list. Over MCP, the tool waits for the end and returns the answer. - Billed in credits exactly like a chat turn in the app. | Argument | Type | Description | | --- | --- | --- | | `siteId` (in the path) | string | Its id. | | `cid` (in the path) | string | Its id. | | `message` (required) | string | The user’s message. (at least 1 character) | | `attachments` (optional) | array | Files attached to the message, as in the app (the same types, 20 MB each at most). | | `stream` (optional) | boolean | Accepted for compatibility; the API answer always streams. | Request: ```bash curl -X POST https://app.semchat.io/api/v1/sites/{siteId}/conversations/{cid}/messages \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"message": "…"}' ``` The answer streams as Server-Sent Events; once finished, read it in full with the messages list. Over MCP the tool waits for the end and returns the answer. ### Scheduled tasks Scheduled tasks: create, change, run now, and read their runs. (https://semchat.io/en/docs/api-tasks) 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](https://semchat.io/en/docs/api-costs)). | Operation | Call | | | --- | --- | --- | | List scheduled tasks | `GET /tasks` | Free | | Get scheduled task | `GET /tasks/{taskId}` | Free | | Create scheduled task | `POST /tasks` | Free | | Update scheduled task | `PATCH /tasks/{taskId}` | Free | | Delete scheduled task | `DELETE /tasks/{taskId}` | Free | | Run scheduled task | `POST /tasks/{taskId}/run` | Billed | | List scheduled task runs | `GET /tasks/{taskId}/runs` | Free | #### List scheduled tasks `GET /tasks` · Free · MCP tool `list_scheduled_tasks` Every scheduled task of the workspace: its message, schedule, state, next and last run. Request: ```bash curl https://app.semchat.io/api/v1/tasks \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. #### Get scheduled task `GET /tasks/{taskId}` · Free · MCP tool `get_scheduled_task` One scheduled task. | Argument | Type | Description | | --- | --- | --- | | `taskId` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/tasks/{taskId} \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`. #### Create scheduled task `POST /tasks` · Free · MCP tool `create_scheduled_task` Create a scheduled task: a message the assistant runs by itself on a schedule, as in the app’s Tasks. - It starts active: its first run is at the schedule’s next time. - Each run is a conversation of the workspace, billed like a chat message. An action that leaves semchat (publishing, posting) that its message asks for is done at once, as in any chat. | Argument | Type | Description | | --- | --- | --- | | `name` (required) | string | The task’s name, as the list shows it. (1–120 characters) | | `prompt` (required) | string | The message the assistant runs each time, written as in the chat. It may name a site (« /site:example.com »: its data and connectors), a skill (« / »), an email address (« /email:paul@example.com »), a Discord channel (« /discord: »), a Slack or Notion account (« /slack: », « /notion: »). (1–8000 characters) | | `schedule` (required) | string \| null | When it runs: { kind: "daily", time: "08:00" }, { kind: "weekly", days: ["mon", "thu"], time: "08:00" }, { kind: "monthly", day: 1, time: "08:00" } (a shorter month: its last day), or { kind: "hourly", every: 6 } (1, 2, 3, 4, 6, 8 or 12). | | `timezone` (required) | string | The time zone its times are in, e.g. "Europe/Paris". | | `site_id` (optional) | string \| null | The site it’s about, for the list (null: none). Defaults to the first site its message names. | Request: ```bash curl -X POST https://app.semchat.io/api/v1/tasks \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"name": "…", "prompt": "…", "schedule": "…", "timezone": "…"}' ``` Answers 201 with `{ "data": … }`. #### Update scheduled task `PATCH /tasks/{taskId}` · Free · MCP tool `update_scheduled_task` Change a scheduled task: its name, message, schedule, time zone or site, or pause and resume it (status). - Only its author, or the workspace’s owner or an admin, can change, run or delete a task: 403 FORBIDDEN otherwise. - Only the fields given change; at least one is required. A new schedule or time zone, or a resume, moves the next run to the schedule’s next time from now. | Argument | Type | Description | | --- | --- | --- | | `taskId` (in the path) | string | Its id. | | `name` (optional) | string | The task’s name, as the list shows it. (1–120 characters) | | `prompt` (optional) | string | The message the assistant runs each time, written as in the chat. It may name a site (« /site:example.com »: its data and connectors), a skill (« / »), an email address (« /email:paul@example.com »), a Discord channel (« /discord: »), a Slack or Notion account (« /slack: », « /notion: »). (1–8000 characters) | | `schedule` (optional) | string \| null | When it runs: { kind: "daily", time: "08:00" }, { kind: "weekly", days: ["mon", "thu"], time: "08:00" }, { kind: "monthly", day: 1, time: "08:00" } (a shorter month: its last day), or { kind: "hourly", every: 6 } (1, 2, 3, 4, 6, 8 or 12). | | `timezone` (optional) | string | The time zone its times are in, e.g. "Europe/Paris". | | `site_id` (optional) | string \| null | The site it’s about, for the list (null: none). Defaults to the first site its message names. | | `status` (optional) | string | "paused": it stops running; "active": it resumes (its error count is cleared). (active \| paused) | Request: ```bash curl -X PATCH https://app.semchat.io/api/v1/tasks/{taskId} \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"name": "…"}' ``` Answers 200 with `{ "data": … }`. #### Delete scheduled task `DELETE /tasks/{taskId}` · Free · MCP tool `delete_scheduled_task` Delete a scheduled task. Its past runs and their conversations stay. - Only its author, or the workspace’s owner or an admin, can change, run or delete a task: 403 FORBIDDEN otherwise. | Argument | Type | Description | | --- | --- | --- | | `taskId` (in the path) | string | Its id. | Request: ```bash curl -X DELETE https://app.semchat.io/api/v1/tasks/{taskId} \ -H "Authorization: Bearer sk_live_…" ``` Answers 204 with `{ "data": … }`. #### Run scheduled task `POST /tasks/{taskId}/run` · Billed · MCP tool `run_scheduled_task` Run a scheduled task now, as the app’s « Run now »: one run, its schedule unchanged. - Only its author, or the workspace’s owner or an admin, can change, run or delete a task: 403 FORBIDDEN otherwise. - Answers at once with the run’s id; the run goes on in the background: read list_scheduled_task_runs for its conversation and recap. - 409 CONFLICT while one of its runs is going; 402 INSUFFICIENT_TOKENS without credits. | Argument | Type | Description | | --- | --- | --- | | `taskId` (in the path) | string | Its id. | Request: ```bash curl -X POST https://app.semchat.io/api/v1/tasks/{taskId}/run \ -H "Authorization: Bearer sk_live_…" ``` Answers 202 with `{ "data": … }`. #### List scheduled task runs `GET /tasks/{taskId}/runs` · Free · MCP tool `list_scheduled_task_runs` A scheduled task’s last runs, newest first: each one’s state, its conversation, its title and recap. | Argument | Type | Description | | --- | --- | --- | | `taskId` (in the path) | string | Its id. | Request: ```bash curl https://app.semchat.io/api/v1/tasks/{taskId}/runs \ -H "Authorization: Bearer sk_live_…" ``` Answers 200 with `{ "data": … }`.