{"openapi":"3.1.0","info":{"title":"semchat API & MCP","version":"1","description":""},"servers":[{"url":"https://app.semchat.io/api/v1"}],"security":[{"bearer":[]},{"apiKey":[]}],"tags":[{"name":"Workspace"},{"name":"Members"},{"name":"Sites"},{"name":"Action plan"},{"name":"Keywords"},{"name":"Content ideas"},{"name":"Competitors"},{"name":"Backlinks"},{"name":"Data and documents"},{"name":"Conversations"},{"name":"Scheduled tasks"}],"paths":{"/workspace":{"get":{"operationId":"get_workspace","summary":"Get workspace","description":"The workspace, its plan and how much of the period’s credits is used.\n\n- Credits are never shown as raw numbers: only percentages of the period.\n\nFree.\n\nMCP tool: `get_workspace`","tags":["Workspace"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"responses":{"200":{"description":"The answer, in `data`.","content":{"application/json":{"example":{"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}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"update_workspace","summary":"Update workspace","description":"Edit the workspace’s settings: its name, description, custom instructions for the assistant, company details.\n\n- Owner or admin only (the role of the key’s creator): 403 FORBIDDEN otherwise.\n- Only the fields given change; an empty text (or null) clears a field. At least one field is required.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `update_workspace`","tags":["Workspace"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"custom_instructions":{"description":"Instructions the assistant follows in every conversation of the workspace.","anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"company_name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]},"company_website":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]},"company_siren":{"description":"The company’s registration number.","anyOf":[{"type":"string","maxLength":20},{"type":"null"}]},"company_address":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/usage":{"get":{"operationId":"get_usage","summary":"Get usage","description":"The current period’s usage, in percent, split by category.\n\nFree.\n\nMCP tool: `get_usage`","tags":["Workspace"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"responses":{"200":{"description":"The answer, in `data`.","content":{"application/json":{"example":{"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}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/skills":{"get":{"operationId":"list_skills","summary":"List skills","description":"The skills available to the workspace’s chat.\n\nFree.\n\nMCP tool: `list_skills`","tags":["Workspace"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"responses":{"200":{"description":"The answer, in `data`.","content":{"application/json":{"example":{"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}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/connectors":{"get":{"operationId":"list_connectors","summary":"List connectors","description":"Tools connected at workspace level (Search Console, GA4, Slack, Notion…).\n\n- Most connections are per site: see list_site_connectors.\n\nFree.\n\nMCP tool: `list_connectors`","tags":["Workspace"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/search":{"post":{"operationId":"search_workspace","summary":"Search workspace","description":"Searches the workspace’s conversations, sites, scheduled tasks, connectors and skills by name, address, message or account, as the app’s search (⌘K) does.\n\n- Each kind comes with `more`: true when there are others than those returned.\n- Conversations are searched by their title.\n\nFree.\n\nMCP tool: `search_workspace`","tags":["Workspace"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","maxLength":100,"description":"What to look for, accents and case aside. Empty: the newest of each kind."},"limit":{"description":"At most this many of each kind (default and maximum 50).","type":"integer","minimum":1,"maximum":50}},"required":["query"],"additionalProperties":false}}}},"responses":{"200":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/workspace/members":{"get":{"operationId":"list_members","summary":"List members","description":"The members of the workspace and their role.\n\nFree.\n\nMCP tool: `list_members`","tags":["Members"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"responses":{"200":{"description":"The answer, in `data`.","content":{"application/json":{"example":{"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"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/skills/{skillId}":{"patch":{"operationId":"set_skill","summary":"Set skill","description":"Turn one of the workspace’s skills on or off for its chat.\n\n- Owner or admin only (the role of the key’s creator): 403 FORBIDDEN otherwise.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `set_skill`","tags":["Workspace"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"skillId","in":"path","required":true,"description":"The skill's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false}}}},"responses":{"200":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/workspace/tools":{"get":{"operationId":"list_tool_prefs","summary":"List tool prefs","description":"The connectors’ tools the assistant may use, each on or off for the workspace.\n\n- A tool is on unless it was turned off. Each site inherits these, unless it sets its own: see list_site_tool_prefs.\n\nFree.\n\nMCP tool: `list_tool_prefs`","tags":["Workspace"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"set_tool_pref","summary":"Set tool pref","description":"Turn a tool on or off for the assistant, for the workspace or for one site.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `set_tool_pref`","tags":["Workspace"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tool_name":{"type":"string","minLength":1,"maxLength":64,"description":"The tool, as list_tool_prefs names it."},"enabled":{"type":"boolean"},"site_id":{"description":"Only for this site (default: the workspace).","type":"string","minLength":1}},"required":["tool_name","enabled"],"additionalProperties":false}}}},"responses":{"200":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/tools":{"get":{"operationId":"list_site_tool_prefs","summary":"List site tool prefs","description":"The connectors’ tools the assistant may use in this site’s conversations, each on or off.\n\n- The site’s own choice when it made one, else the workspace’s.\n\nFree.\n\nMCP tool: `list_site_tool_prefs`","tags":["Workspace"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/connectors/{provider}":{"delete":{"operationId":"disconnect_connector","summary":"Disconnect connector","description":"Disconnect a tool connected at workspace level (its stored access is deleted).\n\n- provider as list_connectors shows it (google_search_console, google_analytics_4, notion, slack, wordpress, webflow, microsoft_clarity, bing_webmaster_tools, yandex_metrica).\n- The sites’ own connections are untouched: see disconnect_site_connector. Connecting a tool is done in the app.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `disconnect_connector`","tags":["Workspace"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"provider","in":"path","required":true,"description":"The provider's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/connectors/{provider}":{"delete":{"operationId":"disconnect_site_connector","summary":"Disconnect site connector","description":"Disconnect a tool connected to this site (its stored access is deleted).\n\n- provider as list_site_connectors shows it.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `disconnect_site_connector`","tags":["Workspace"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}},{"name":"provider","in":"path","required":true,"description":"The provider's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/workspace/invitations":{"get":{"operationId":"list_invitations","summary":"List invitations","description":"The workspace’s pending invitations.\n\n- Owner or admin only (the role of the key’s creator): 403 FORBIDDEN otherwise.\n\nFree.\n\nMCP tool: `list_invitations`","tags":["Members"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"invite_member","summary":"Invite member","description":"Invite someone to the workspace by email: they receive the invitation email, valid 7 days.\n\n- Owner or admin only (the role of the key’s creator): 403 FORBIDDEN otherwise.\n- 409 CONFLICT when the email is already a member or already invited.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `invite_member`","tags":["Members"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"role":{"default":"member","description":"admin or member (default).","type":"string","enum":["admin","member"]}},"required":["email","role"],"additionalProperties":false}}}},"responses":{"201":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/workspace/invitations/{invitationId}":{"delete":{"operationId":"cancel_invitation","summary":"Cancel invitation","description":"Cancel an invitation: its link stops working.\n\n- Owner or admin only (the role of the key’s creator): 403 FORBIDDEN otherwise.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `cancel_invitation`","tags":["Members"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"invitationId","in":"path","required":true,"description":"The invitation's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/workspace/members/{userId}":{"patch":{"operationId":"update_member","summary":"Update member","description":"Change a member’s role (admin or member).\n\n- Owner or admin only (the role of the key’s creator): 403 FORBIDDEN otherwise.\n- userId as list_members shows it. The owner’s role can’t be changed.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `update_member`","tags":["Members"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"userId","in":"path","required":true,"description":"The user's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["admin","member"]}},"required":["role"],"additionalProperties":false}}}},"responses":{"200":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"remove_member","summary":"Remove member","description":"Remove a member from the workspace.\n\n- Owner or admin, except to remove yourself (the key’s creator leaves the workspace). The owner can’t be removed.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `remove_member`","tags":["Members"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"userId","in":"path","required":true,"description":"The user's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites":{"get":{"operationId":"list_sites","summary":"List sites","description":"Every site of the workspace.\n\nFree.\n\nMCP tool: `list_sites`","tags":["Sites"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"responses":{"200":{"description":"The answer, in `data`.","content":{"application/json":{"example":{"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"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"create_site","summary":"Create site","description":"Create a site, and optionally start its analysis.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `create_site`","tags":["Sites"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"The site’s name."},"site_url":{"description":"Its address. Needed for an analysis.","type":"string","maxLength":500},"description":{"type":"string","maxLength":2000},"auto_analyze":{"description":"Start the analysis right away (billed). Skipped without credits: needs_credits is then true.","type":"boolean"}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"The answer, in `data`.","content":{"application/json":{"example":{"data":{"id":"01a168f1-9d83-7253-a7ec-af716d6279e1","analysis_status":"idle","needs_credits":false}}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}":{"get":{"operationId":"get_site","summary":"Get site","description":"One site, with everything its last analysis stored (overview, health, accessibility, keywords…).\n\nFree.\n\nMCP tool: `get_site`","tags":["Sites"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`.","content":{"application/json":{"example":{"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"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"update_site","summary":"Update site","description":"Edit the site’s settings: name, address, description, instructions, writing style, technologies.\n\n- Only the fields given are changed. Answers the site with its settings.\n- Changing the address doesn’t re-run the analysis: call analyze_site for that.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `update_site`","tags":["Sites"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The site’s name (can’t be blank).","type":"string","minLength":1,"maxLength":255},"site_url":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"Its address. Blank or null clears it."},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"Blank or null clears it."},"instructions":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"description":"What the assistant keeps in mind for this site. Blank or null clears it."},"writing_style":{"description":"The voice of the articles written for the site; null clears it.","anyOf":[{"type":"string","enum":["professional","conversational","educational","journalistic","persuasive","storytelling","technical","friendly","luxury","seo_optimized"]},{"type":"null"}]},"technologies":{"description":"The technologies the site runs on (their keys); [] clears them.","maxItems":40,"type":"array","items":{"type":"string","enum":["wordpress","woocommerce","shopify","wix","squarespace","webflow","framer","nextjs","react","vue","nuxt","angular","svelte","astro","gatsby","drupal","joomla","magento","prestashop","ghost","contentful","sanity","strapi","bigcommerce","hubspot","laravel","django","rails","nodejs","php","shopware","typo3"]}}},"additionalProperties":false}}}},"responses":{"200":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"delete_site","summary":"Delete site","description":"Delete the site.\n\n- 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.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `delete_site`","tags":["Sites"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/analyze":{"post":{"operationId":"analyze_site","summary":"Analyze site","description":"Run (or re-run) the site’s full analysis: crawl, technical health, competitors, keywords, action plan.\n\n- Runs in the background (a few minutes): read get_site until analysis_status is ready or error.\n- Billed exactly like an analysis started in the app. 402 INSUFFICIENT_TOKENS without credits.\n- A re-analysis keeps the existing action plan and adds what’s new.\n\nBilled from the workspace’s credits, exactly as in the app.\n\nMCP tool: `analyze_site`","tags":["Sites"],"x-badges":[{"name":"Billed","color":"#f59e0b","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/connectors":{"get":{"operationId":"list_site_connectors","summary":"List site connectors","description":"The tools connected to this site.\n\nFree.\n\nMCP tool: `list_site_connectors`","tags":["Sites"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/todos":{"get":{"operationId":"list_todos","summary":"List todos","description":"The site’s action plan.\n\nFree.\n\nMCP tool: `list_todos`","tags":["Action plan"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`.","content":{"application/json":{"example":{"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"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"create_todo","summary":"Create todo","description":"Add a task to the site’s action plan.\n\n- Added as a manual task (source manuel), to do (status a_faire). Answers the task.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `create_todo`","tags":["Action plan"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":500,"description":"What to do."},"description":{"type":"string","maxLength":4000},"priority":{"description":"high, medium (default) or low.","type":"string","enum":["high","medium","low"]},"category":{"description":"The plan pillar it belongs to. Default technical.","type":"string","enum":["technical","content","accessibility","backlinks","competitors"]},"source_lang":{"description":"The language the text is written in (e.g. \"fr\", \"en\"). Omitted: the site’s content language.","type":"string","minLength":2,"maxLength":5}},"required":["title"],"additionalProperties":false}}}},"responses":{"201":{"description":"The answer, in `data`.","content":{"application/json":{"example":{"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"}}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/competitors":{"get":{"operationId":"list_competitors","summary":"List competitors","description":"The site’s competitors, with their profile once analysed.\n\nFree.\n\nMCP tool: `list_competitors`","tags":["Competitors"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`.","content":{"application/json":{"example":{"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}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"add_competitor","summary":"Add competitor","description":"Add a competitor, and optionally profile it (billed).\n\n- Answers its id and `analyzing`: false when no analysis was started (none asked for, or no credits; the competitor is saved all the same).\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `add_competitor`","tags":["Competitors"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":500,"description":"The competitor’s address."},"name":{"type":"string","maxLength":255},"auto_analyze":{"description":"Profile it in the background (billed). Skipped without credits.","type":"boolean"}},"required":["url"],"additionalProperties":false}}}},"responses":{"201":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/data":{"get":{"operationId":"list_site_data","summary":"List site data","description":"The data blocks saved on the site: charts, KPI grids and site maps kept from conversations.\n\nFree.\n\nMCP tool: `list_site_data`","tags":["Data and documents"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`.","content":{"application/json":{"example":{"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"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"save_data_block","summary":"Save data block","description":"Save a chart or a KPI grid on the site (as the app’s Save on a conversation’s chart).\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `save_data_block`","tags":["Data and documents"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["chart","kpi_grid"],"description":"chart or kpi_grid."},"title":{"type":"string","minLength":1,"maxLength":500},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"The chart’s or KPI grid’s props, as a conversation’s block carries them."},"conversation_id":{"description":"The conversation it comes from.","type":"string","minLength":1},"message_id":{"description":"The message it comes from: a message saves one block per title (409 CONFLICT).","type":"string","minLength":1}},"required":["type","title","data"],"additionalProperties":false}}}},"responses":{"201":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/documents":{"get":{"operationId":"list_site_documents","summary":"List site documents","description":"The documents written for the site (articles, briefs…).\n\nFree.\n\nMCP tool: `list_site_documents`","tags":["Data and documents"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/favorite":{"patch":{"operationId":"set_site_favorite","summary":"Set site favorite","description":"Star or unstar the site.\n\n- Starring doesn’t count as activity: the site keeps its place in the “Activity” sort.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `set_site_favorite`","tags":["Sites"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"favorite":{"type":"boolean","description":"true stars the site, false unstars it."}},"required":["favorite"],"additionalProperties":false}}}},"responses":{"200":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/conversations/{cid}":{"patch":{"operationId":"update_conversation","summary":"Update conversation","description":"Rename a conversation, or star / unstar it.\n\n- Acts on any conversation of the workspace, a site’s ones included (its cid is enough), as the app does.\n- Only the fields given are changed. Answers the conversation.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `update_conversation`","tags":["Conversations"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"cid","in":"path","required":true,"description":"The cid's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"Rename the conversation.","type":"string","minLength":1,"maxLength":500},"starred":{"description":"true stars it (starred_at = now), false unstars it.","type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"delete_conversation","summary":"Delete conversation","description":"Delete a conversation.\n\n- Acts on any conversation of the workspace, a site’s ones included (its cid is enough), as the app does.\n- Soft delete, as in the app: it leaves the lists and answers 404; its messages and the data saved from it are kept.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `delete_conversation`","tags":["Conversations"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"cid","in":"path","required":true,"description":"The cid's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"get":{"operationId":"get_conversation","summary":"Get conversation","description":"One conversation of the workspace (a site’s ones included).\n\nFree.\n\nMCP tool: `get_conversation`","tags":["Conversations"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"cid","in":"path","required":true,"description":"The cid's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`.","content":{"application/json":{"example":{"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"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/todos/{todoId}":{"patch":{"operationId":"update_todo","summary":"Update todo","description":"Change a task of the action plan: its status (to do, in progress, done, ignored), title, description or priority.\n\n- Answers the task as it now is.\n- 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.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `update_todo`","tags":["Action plan"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}},{"name":"todoId","in":"path","required":true,"description":"The todo's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"a_faire (to do), en_cours (in progress), fait (done) or ignore (ignored).","type":"string","enum":["a_faire","en_cours","fait","ignore"]},"title":{"type":"string","minLength":1,"maxLength":500},"description":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}]},"priority":{"type":"string","enum":["high","medium","low"]},"source_lang":{"description":"The language of the new title / description. Ignored when neither changes.","type":"string","minLength":2,"maxLength":5}},"additionalProperties":false}}}},"responses":{"200":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"delete_todo","summary":"Delete todo","description":"Remove a task from the action plan.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `delete_todo`","tags":["Action plan"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}},{"name":"todoId","in":"path","required":true,"description":"The todo's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Done, no body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/keywords":{"get":{"operationId":"list_keywords","summary":"List keywords","description":"The site’s target keywords, from its analysis or added by hand, with their volume, difficulty and current position.\n\n- 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.\n\nFree.\n\nMCP tool: `list_keywords`","tags":["Keywords"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`.","content":{"application/json":{"example":{"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"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"add_keyword","summary":"Add keyword","description":"Add a target keyword to the site.\n\n- Stored as given, as a manual keyword: no keyword data is fetched (nothing billed). Answers the keyword.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `add_keyword`","tags":["Keywords"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keyword":{"type":"string","minLength":1,"maxLength":255,"description":"The keyword."},"volume":{"description":"Its monthly search volume, if known.","anyOf":[{"type":"integer","minimum":0,"maximum":100000000},{"type":"null"}]},"difficulty":{"description":"Its difficulty, 0–100, if known.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"intent":{"description":"informational, commercial, transactional or navigational.","anyOf":[{"type":"string","enum":["informational","commercial","transactional","navigational"]},{"type":"null"}]},"priority":{"description":"high, medium (default) or low.","type":"string","enum":["high","medium","low"]},"rationale":{"description":"Why to target it.","anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"source_lang":{"description":"The language the text is written in (e.g. \"fr\", \"en\"). Omitted: the site’s content language.","type":"string","minLength":2,"maxLength":5}},"required":["keyword"],"additionalProperties":false}}}},"responses":{"201":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/keywords/{keywordId}":{"patch":{"operationId":"update_keyword","summary":"Update keyword","description":"Change a target keyword: the keyword, its figures, intent, priority or rationale.\n\n- Answers the keyword as it now is.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `update_keyword`","tags":["Keywords"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}},{"name":"keywordId","in":"path","required":true,"description":"The keyword's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keyword":{"type":"string","minLength":1,"maxLength":255},"volume":{"anyOf":[{"type":"integer","minimum":0,"maximum":100000000},{"type":"null"}]},"difficulty":{"anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"intent":{"anyOf":[{"type":"string","enum":["informational","commercial","transactional","navigational"]},{"type":"null"}]},"priority":{"type":"string","enum":["high","medium","low"]},"rationale":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"source_lang":{"description":"The language of the new keyword / rationale. Ignored when neither changes.","type":"string","minLength":2,"maxLength":5}},"additionalProperties":false}}}},"responses":{"200":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"delete_keyword","summary":"Delete keyword","description":"Remove a target keyword from the site.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `delete_keyword`","tags":["Keywords"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}},{"name":"keywordId","in":"path","required":true,"description":"The keyword's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Done, no body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/content-ideas":{"get":{"operationId":"list_content_ideas","summary":"List content ideas","description":"The site’s content ideas: articles to write, each with its keyword, angle and rationale.\n\n- 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.\n\nFree.\n\nMCP tool: `list_content_ideas`","tags":["Content ideas"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`.","content":{"application/json":{"example":{"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"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"add_content_idea","summary":"Add content idea","description":"Add a content idea to the site.\n\n- Added as a manual idea. Answers the idea.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `add_content_idea`","tags":["Content ideas"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300,"description":"The article’s title."},"content_type":{"description":"blog_post, guide, comparison, faq, how_to, listicle or landing.","anyOf":[{"type":"string","enum":["blog_post","guide","comparison","faq","how_to","listicle","landing"]},{"type":"null"}]},"primary_keyword":{"description":"The keyword it targets.","anyOf":[{"type":"string","maxLength":255},{"type":"null"}]},"intent":{"description":"informational, commercial, transactional or navigational.","anyOf":[{"type":"string","enum":["informational","commercial","transactional","navigational"]},{"type":"null"}]},"angle":{"description":"What the article should cover.","anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"rationale":{"description":"Why write it.","anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"volume":{"anyOf":[{"type":"integer","minimum":0,"maximum":100000000},{"type":"null"}]},"difficulty":{"anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"source_lang":{"description":"The language the text is written in (e.g. \"fr\", \"en\"). Omitted: the site’s content language.","type":"string","minLength":2,"maxLength":5}},"required":["title"],"additionalProperties":false}}}},"responses":{"201":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/content-ideas/{ideaId}":{"delete":{"operationId":"delete_content_idea","summary":"Delete content idea","description":"Remove a content idea from the site.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `delete_content_idea`","tags":["Content ideas"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}},{"name":"ideaId","in":"path","required":true,"description":"The idea's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Done, no body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/competitors/{competitorId}":{"delete":{"operationId":"delete_competitor","summary":"Delete competitor","description":"Remove a competitor from the site’s set.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `delete_competitor`","tags":["Competitors"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}},{"name":"competitorId","in":"path","required":true,"description":"The competitor's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Done, no body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/competitors/{competitorId}/profile":{"post":{"operationId":"profile_competitor","summary":"Profile competitor","description":"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.\n\n- Billed like the same analysis in the app (an AI call). 402 INSUFFICIENT_TOKENS without credits.\n- Without background, waits for the profile (up to a few minutes) and answers the competitor with it.\n\nBilled from the workspace’s credits, exactly as in the app.\n\nMCP tool: `profile_competitor`","tags":["Competitors"],"x-badges":[{"name":"Billed","color":"#f59e0b","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}},{"name":"competitorId","in":"path","required":true,"description":"The competitor's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"background":{"description":"Answer at once (202, status analyzing) and store the profile when it lands: read list_competitors for it.","type":"boolean"},"locale":{"description":"The language to write the profile in (fr, en, es, de, pt, it). Default: the key creator’s.","type":"string","minLength":2,"maxLength":5}},"additionalProperties":false}}}},"responses":{"200":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/competitors/{competitorId}/backlinks":{"get":{"operationId":"get_competitor_backlinks","summary":"Get competitor backlinks","description":"A competitor’s backlink numbers: rank (0–100), referring domains, backlinks, spam score.\n\n- Free when the site’s stored backlink profile (get_backlinks) already covers this competitor; otherwise one billed data call, as in the app.\n- 402 INSUFFICIENT_TOKENS without credits when a billed call would be needed.\n\nBilled from the workspace’s credits, exactly as in the app.\n\nMCP tool: `get_competitor_backlinks`","tags":["Competitors"],"x-badges":[{"name":"Billed","color":"#f59e0b","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}},{"name":"competitorId","in":"path","required":true,"description":"The competitor's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/backlinks":{"get":{"operationId":"get_backlinks","summary":"Get backlinks","description":"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.\n\n- stale is true once the profile is more than 7 days old: refresh_backlinks updates it.\n- 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.\n\nFree.\n\nMCP tool: `get_backlinks`","tags":["Backlinks"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"refresh_backlinks","summary":"Refresh backlinks","description":"Fetch the site’s backlink profile again (the site and its top 3 competitors), store it and answer it.\n\n- Billed per data call, exactly as the app’s Refresh: about 10 calls.\n- 402 INSUFFICIENT_TOKENS when the credits can’t cover the refresh’s most expensive case, 409 CONFLICT while one runs for the site.\n\nBilled from the workspace’s credits, exactly as in the app.\n\nMCP tool: `refresh_backlinks`","tags":["Backlinks"],"x-badges":[{"name":"Billed","color":"#f59e0b","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/data/{blockId}":{"delete":{"operationId":"delete_data_block","summary":"Delete data block","description":"Delete a data block saved on the site.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `delete_data_block`","tags":["Data and documents"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}},{"name":"blockId","in":"path","required":true,"description":"The block's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Done, no body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/health":{"get":{"operationId":"get_site_health","summary":"Get site health","description":"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.\n\nFree.\n\nMCP tool: `get_site_health`","tags":["Sites"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`.","content":{"application/json":{"example":{"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}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/accessibility":{"get":{"operationId":"get_site_accessibility","summary":"Get site accessibility","description":"The site’s accessibility (WCAG 2.1 A and AA): the last analysis’s score and findings by rule, and the score’s history.\n\nFree.\n\nMCP tool: `get_site_accessibility`","tags":["Sites"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/accessibility/{ruleId}":{"get":{"operationId":"get_accessibility_rule","summary":"Get accessibility rule","description":"Every page an accessibility rule fails on (a finding’s rule_id), with the failing elements.\n\n- pages is capped; page_count is the exact number of pages affected.\n\nFree.\n\nMCP tool: `get_accessibility_rule`","tags":["Sites"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}},{"name":"ruleId","in":"path","required":true,"description":"The rule's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/conversations":{"get":{"operationId":"list_conversations","summary":"List conversations","description":"The workspace conversations (not tied to a site).\n\nFree.\n\nMCP tool: `list_conversations`","tags":["Conversations"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"responses":{"200":{"description":"The answer, in `data`.","content":{"application/json":{"example":{"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"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"create_conversation","summary":"Create conversation","description":"Start a workspace conversation.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `create_conversation`","tags":["Conversations"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"Its title (optional).","type":"string","maxLength":500}},"additionalProperties":false}}}},"responses":{"201":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/conversations/{cid}/messages":{"get":{"operationId":"list_messages","summary":"List messages","description":"A workspace conversation’s messages, oldest first (text, tool calls and results, charts, documents).\n\nFree.\n\nMCP tool: `list_messages`","tags":["Conversations"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"cid","in":"path","required":true,"description":"The cid's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`.","content":{"application/json":{"example":{"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"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"send_message","summary":"Send message","description":"Send a message: the assistant answers, using its tools (keyword data, crawl, competitors…) as in the app.\n\n- 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.\n- 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.\n- Billed in credits exactly like a chat turn in the app.\n\nBilled from the workspace’s credits, exactly as in the app.\n\nAnswers a Server-Sent Events stream; over MCP, the tool waits and returns the final answer.\n\nMCP tool: `send_message`","tags":["Conversations"],"x-badges":[{"name":"Billed","color":"#f59e0b","position":"after"}],"parameters":[{"name":"cid","in":"path","required":true,"description":"The cid's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","minLength":1,"description":"The user’s message."},"attachments":{"description":"Files attached to the message, as in the app (the same types, 20 MB each at most).","maxItems":10,"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255},"mime_type":{"type":"string","minLength":1,"description":"image/png, image/jpeg, image/webp, image/gif, application/pdf, text/plain, text/markdown, text/csv"},"data_base64":{"type":"string","minLength":1,"description":"The file’s content, base64."}},"required":["filename","mime_type","data_base64"],"additionalProperties":false}},"stream":{"description":"Accepted for compatibility; the API answer always streams.","type":"boolean"}},"required":["message"],"additionalProperties":false}}}},"responses":{"200":{"description":"The answer, as it is written (Server-Sent Events).","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/conversations/{cid}/documents":{"get":{"operationId":"list_conversation_documents","summary":"List conversation documents","description":"The documents written in a workspace conversation.\n\nFree.\n\nMCP tool: `list_conversation_documents`","tags":["Conversations"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"cid","in":"path","required":true,"description":"The cid's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/conversations":{"get":{"operationId":"list_site_conversations","summary":"List site conversations","description":"A site’s conversations.\n\nFree.\n\nMCP tool: `list_site_conversations`","tags":["Conversations"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"create_site_conversation","summary":"Create site conversation","description":"Start a conversation on a site: the assistant knows that site.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `create_site_conversation`","tags":["Conversations"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"Its title (optional).","type":"string","maxLength":500}},"additionalProperties":false}}}},"responses":{"201":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/conversations/{cid}":{"get":{"operationId":"get_site_conversation","summary":"Get site conversation","description":"One of a site’s conversations.\n\nFree.\n\nMCP tool: `get_site_conversation`","tags":["Conversations"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}},{"name":"cid","in":"path","required":true,"description":"The cid's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}/conversations/{cid}/messages":{"get":{"operationId":"list_site_messages","summary":"List site messages","description":"A site conversation’s messages, oldest first.\n\nFree.\n\nMCP tool: `list_site_messages`","tags":["Conversations"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}},{"name":"cid","in":"path","required":true,"description":"The cid's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"send_site_message","summary":"Send site message","description":"Send a message in a site conversation: the assistant answers with that site in mind.\n\n- 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.\n- 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.\n- Billed in credits exactly like a chat turn in the app.\n\nBilled from the workspace’s credits, exactly as in the app.\n\nAnswers a Server-Sent Events stream; over MCP, the tool waits and returns the final answer.\n\nMCP tool: `send_site_message`","tags":["Conversations"],"x-badges":[{"name":"Billed","color":"#f59e0b","position":"after"}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id.","schema":{"type":"string","format":"uuid"}},{"name":"cid","in":"path","required":true,"description":"The cid's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","minLength":1,"description":"The user’s message."},"attachments":{"description":"Files attached to the message, as in the app (the same types, 20 MB each at most).","maxItems":10,"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255},"mime_type":{"type":"string","minLength":1,"description":"image/png, image/jpeg, image/webp, image/gif, application/pdf, text/plain, text/markdown, text/csv"},"data_base64":{"type":"string","minLength":1,"description":"The file’s content, base64."}},"required":["filename","mime_type","data_base64"],"additionalProperties":false}},"stream":{"description":"Accepted for compatibility; the API answer always streams.","type":"boolean"}},"required":["message"],"additionalProperties":false}}}},"responses":{"200":{"description":"The answer, as it is written (Server-Sent Events).","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/tasks":{"get":{"operationId":"list_scheduled_tasks","summary":"List scheduled tasks","description":"Every scheduled task of the workspace: its message, schedule, state, next and last run.\n\nFree.\n\nMCP tool: `list_scheduled_tasks`","tags":["Scheduled tasks"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"create_scheduled_task","summary":"Create scheduled task","description":"Create a scheduled task: a message the assistant runs by itself on a schedule, as in the app’s Tasks.\n\n- It starts active: its first run is at the schedule’s next time.\n- 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.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `create_scheduled_task`","tags":["Scheduled tasks"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"The task’s name, as the list shows it."},"prompt":{"type":"string","minLength":1,"maxLength":8000,"description":"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 (« /&lt;skill-id&gt; »), an email address (« /email:paul@example.com »), a Discord channel (« /discord:&lt;id&gt; »), a Slack or Notion account (« /slack:&lt;id&gt; », « /notion:&lt;id&gt; »)."},"schedule":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"daily"},"time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}},"required":["kind","time"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"weekly"},"days":{"minItems":1,"maxItems":7,"type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}},"required":["kind","days","time"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"monthly"},"day":{"type":"integer","minimum":1,"maximum":31},"time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}},"required":["kind","day","time"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"hourly"},"every":{"type":"integer","minimum":1,"maximum":12}},"required":["kind","every"],"additionalProperties":false}],"description":"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":{"type":"string","description":"The time zone its times are in, e.g. \"Europe/Paris\"."},"site_id":{"anyOf":[{"type":"string","minLength":1,"maxLength":36},{"type":"null"}],"description":"The site it’s about, for the list (null: none). Defaults to the first site its message names."}},"required":["name","prompt","schedule","timezone"],"additionalProperties":false}}}},"responses":{"201":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/tasks/{taskId}":{"get":{"operationId":"get_scheduled_task","summary":"Get scheduled task","description":"One scheduled task.\n\nFree.\n\nMCP tool: `get_scheduled_task`","tags":["Scheduled tasks"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"taskId","in":"path","required":true,"description":"The task's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"update_scheduled_task","summary":"Update scheduled task","description":"Change a scheduled task: its name, message, schedule, time zone or site, or pause and resume it (status).\n\n- Only its author, or the workspace’s owner or an admin, can change, run or delete a task: 403 FORBIDDEN otherwise.\n- 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.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `update_scheduled_task`","tags":["Scheduled tasks"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"taskId","in":"path","required":true,"description":"The task's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"The task’s name, as the list shows it."},"prompt":{"type":"string","minLength":1,"maxLength":8000,"description":"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 (« /&lt;skill-id&gt; »), an email address (« /email:paul@example.com »), a Discord channel (« /discord:&lt;id&gt; »), a Slack or Notion account (« /slack:&lt;id&gt; », « /notion:&lt;id&gt; »)."},"schedule":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"daily"},"time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}},"required":["kind","time"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"weekly"},"days":{"minItems":1,"maxItems":7,"type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}},"required":["kind","days","time"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"monthly"},"day":{"type":"integer","minimum":1,"maximum":31},"time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}},"required":["kind","day","time"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"hourly"},"every":{"type":"integer","minimum":1,"maximum":12}},"required":["kind","every"],"additionalProperties":false}],"description":"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":{"type":"string","description":"The time zone its times are in, e.g. \"Europe/Paris\"."},"site_id":{"anyOf":[{"type":"string","minLength":1,"maxLength":36},{"type":"null"}],"description":"The site it’s about, for the list (null: none). Defaults to the first site its message names."},"status":{"description":"\"paused\": it stops running; \"active\": it resumes (its error count is cleared).","type":"string","enum":["active","paused"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"The answer, in `data`."},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"delete_scheduled_task","summary":"Delete scheduled task","description":"Delete a scheduled task. Its past runs and their conversations stay.\n\n- Only its author, or the workspace’s owner or an admin, can change, run or delete a task: 403 FORBIDDEN otherwise.\n\nFree: it changes the workspace, it costs nothing.\n\nMCP tool: `delete_scheduled_task`","tags":["Scheduled tasks"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"taskId","in":"path","required":true,"description":"The task's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Done, no body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/tasks/{taskId}/run":{"post":{"operationId":"run_scheduled_task","summary":"Run scheduled task","description":"Run a scheduled task now, as the app’s « Run now »: one run, its schedule unchanged.\n\n- Only its author, or the workspace’s owner or an admin, can change, run or delete a task: 403 FORBIDDEN otherwise.\n- 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.\n- 409 CONFLICT while one of its runs is going; 402 INSUFFICIENT_TOKENS without credits.\n\nBilled from the workspace’s credits, exactly as in the app.\n\nMCP tool: `run_scheduled_task`","tags":["Scheduled tasks"],"x-badges":[{"name":"Billed","color":"#f59e0b","position":"after"}],"parameters":[{"name":"taskId","in":"path","required":true,"description":"The task's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/tasks/{taskId}/runs":{"get":{"operationId":"list_scheduled_task_runs","summary":"List scheduled task runs","description":"A scheduled task’s last runs, newest first: each one’s state, its conversation, its title and recap.\n\nFree.\n\nMCP tool: `list_scheduled_task_runs`","tags":["Scheduled tasks"],"x-badges":[{"name":"Free","color":"#10b981","position":"after"}],"parameters":[{"name":"taskId","in":"path","required":true,"description":"The task's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The answer, in `data`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Your key (`sk_live_…`), created in semchat: Settings → API & MCP."},"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"The same key in the X-API-Key header."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Branch on it, not on the message."},"message":{"type":"string"},"details":{"description":"The fields at fault (INVALID_INPUT)."}}}}}},"responses":{"InvalidInput":{"description":"The body doesn’t match the operation: `details` lists the fields at fault.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_INPUT","message":"The body doesn’t match the operation: `details` lists the fields at fault."}}}}},"Unauthorized":{"description":"No key, or an unknown, revoked or expired one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_API_KEY","message":"No key, or an unknown, revoked or expired one."}}}}},"InsufficientCredits":{"description":"The workspace’s credits can’t pay for it: nothing ran.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INSUFFICIENT_TOKENS","message":"The workspace’s credits can’t pay for it: nothing ran."}}}}},"Forbidden":{"description":"The key’s creator may not do this in the workspace, or the plan doesn’t include it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"FORBIDDEN","message":"The key’s creator may not do this in the workspace, or the plan doesn’t include it."}}}}},"NotFound":{"description":"No such item in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"No such item in this workspace."}}}}},"RateLimited":{"description":"Too many requests for the workspace: Retry-After says when to retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests for the workspace: Retry-After says when to retry."}}}}}}}}