DocumentationAPI reference

Sites

Sites, their analysis, health and accessibility.

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

OperationCall
List sitesGET /sitesFree
Create sitePOST /sitesFree
Get siteGET /sites/{siteId}Free
Analyze sitePOST /sites/{siteId}/analyzeBilled
List site connectorsGET /sites/{siteId}/connectorsFree
Update sitePATCH /sites/{siteId}Free
Delete siteDELETE /sites/{siteId}Free
Set site favoritePATCH /sites/{siteId}/favoriteFree
Get site healthGET /sites/{siteId}/healthFree
Get site accessibilityGET /sites/{siteId}/accessibilityFree
Get accessibility ruleGET /sites/{siteId}/accessibility/{ruleId}Free

List sites

GET/sitesFree

Every site of the workspace.

MCP tool list_sites

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

Create a site, and optionally start its analysis.

MCP tool create_site

ArgumentTypeDescription
namerequiredstringThe site’s name.1–255 characters
site_urloptionalstringIts address. Needed for an analysis.up to 500 characters
descriptionoptionalstringup to 2000 characters
auto_analyzeoptionalbooleanStart the analysis right away (billed). Skipped without credits: needs_credits is then true.
Request
curl -X POST https://app.semchat.io/api/v1/sites \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "…"}'
Response · 201
{
  "data": {
    "id": "01a168f1-9d83-7253-a7ec-af716d6279e1",
    "analysis_status": "idle",
    "needs_credits": false
  }
}

Get site

GET/sites/{siteId}Free

One site, with everything its last analysis stored (overview, health, accessibility, keywords…).

MCP tool get_site

ArgumentTypeDescription
siteIdin the pathstringIts id.
Request
curl https://app.semchat.io/api/v1/sites/{siteId} \
  -H "Authorization: Bearer sk_live_…"
Response · 200
{
  "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}/analyzeBilled

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.

MCP tool analyze_site

ArgumentTypeDescription
siteIdin the pathstringIts id.
Request
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}/connectorsFree

The tools connected to this site.

MCP tool list_site_connectors

ArgumentTypeDescription
siteIdin the pathstringIts id.
Request
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

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.

MCP tool update_site

ArgumentTypeDescription
siteIdin the pathstringIts id.
nameoptionalstringThe site’s name (can’t be blank).1–255 characters
site_urloptionalstring | nullIts address. Blank or null clears it.
descriptionoptionalstring | nullBlank or null clears it.
instructionsoptionalstring | nullWhat the assistant keeps in mind for this site. Blank or null clears it.
writing_styleoptionalstring | nullThe voice of the articles written for the site; null clears it.
technologiesoptionalarrayThe technologies the site runs on (their keys); [] clears them.
Request
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

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.

MCP tool delete_site

ArgumentTypeDescription
siteIdin the pathstringIts id.
Request
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}/favoriteFree

Star or unstar the site.

  • Starring doesn’t count as activity: the site keeps its place in the “Activity” sort.

MCP tool set_site_favorite

ArgumentTypeDescription
siteIdin the pathstringIts id.
favoriterequiredbooleantrue stars the site, false unstars it.
Request
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}/healthFree

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.

MCP tool get_site_health

ArgumentTypeDescription
siteIdin the pathstringIts id.
Request
curl https://app.semchat.io/api/v1/sites/{siteId}/health \
  -H "Authorization: Bearer sk_live_…"
Response · 200
{
  "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}/accessibilityFree

The site’s accessibility (WCAG 2.1 A and AA): the last analysis’s score and findings by rule, and the score’s history.

MCP tool get_site_accessibility

ArgumentTypeDescription
siteIdin the pathstringIts id.
Request
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

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.

MCP tool get_accessibility_rule

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

Answers 200 with { "data": … }.

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

Ready to get your site off the ground?

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

Free · no sign-up · takes 5 seconds