SoftSolzSoftSolz
HomeAPI GuideAPI ReferenceWidget Tester

Search Intelligence

Read the Search Visibility score, reports, questions, AI answers, keywords, links and code audits, send in what your own model answered, and let it write the explanations, suggestions and fixes.

Search Intelligence measures how visible a website is in three places: Google and Bing results (SEO), the answers AI models give (GEO) and direct answers to the questions people ask (AEO), and combines them into one Search Visibility score. It keeps a dated history of the site’s Google Search Console data, works out every month what genuinely moved, finds the questions people ask and how well the site answers them, tracks the links pointing at the site, and audits the repository the site is built from. The public API exposes all of it, and it is built so that an external model does the writing: an AI assistant connected through the hosted MCP server, or your own server holding an sk_* key, reads the numbers and writes the explanations, the keyword suggestions, the recommendations and the wording fixes. SoftSolz keeps doing the compute. Base path:

bash
https://app.softsolz.uk/api/v1/services/seo

No endpoint spends SoftSolz AI credits

Every call on this API is free of SoftSolz AI credits, without exception. A monthly report started through the API runs the Search Console sync, the detectors and the ranking, but skips the SoftSolz narration step (the report carries data_quality_json.narration = "skipped_for_api"), so the explanations are yours to write with your own model and your own credits. Anything you write is marked source: "api" with your app or key name, and the dashboard shows a Written by <app> badge beside it.

Connecting Claude, ChatGPT, Gemini or Cursor takes one address and no code; see Connect an AI assistant. Everything below applies equally to a connected assistant (each endpoint is one tool) and to a server calling the REST API with a key.

You do not need the API to keep a website up to date. In the dashboard every job runs on a schedule: the Search Console sync, website reads, technical checks, questions and answer coverage, competitors, the code check, the score and the monthly report all run by themselves, and AI answer checks run weekly or monthly once a member switches them on. The endpoints below that start work are there for when your own system wants something sooner.

Start with the guide

One call hands your model everything it needs to use the rest of this API well, and it is read straight from the running code rather than written by hand, so it cannot drift from what the API actually enforces:

bash
GET https://app.softsolz.uk/api/v1/services/seo/guide

It returns:

  • workflow - the call order for the whole loop, in sentences, each naming the exact next endpoint.
  • hard_rules - what may never be claimed from this data. Read these before writing a single sentence for a customer.
  • scoring - the opportunity score formula with its live weights, the effort multipliers and the published click-through curve.
  • taxonomy - the families, statuses, intents, indexing states and readiness components, so you never have to guess a valid value.
  • evidence_rules - what each kind of number does and does not prove.
  • search_visibility - the pillars, weights and coverage bands behind the Search Visibility score, and how a pillar with no data is left out.
  • ai_app_flows - step-by-step flows for an AI app: keyword_research and ai_visibility (see below).

The loop

The API is arranged around one question asked repeatedly: what should I target, what should I write, what should I fix, what should I earn links for, and did it work.

bash
# 1. what to do next, already ranked
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/opportunities
# 2. the evidence behind it
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/opportunities/{opportunity_id}
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/topics
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/content-gaps
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/technical
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/on-page
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/competitors
# 3. your model thinks, with your tokens
# 4. write the decision back
POST https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/briefs
PUT https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/briefs/{brief_id}
PATCH https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/opportunities/{opportunity_id}
# 5. did it work
POST https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/experiments
POST https://app.softsolz.uk/api/v1/services/seo/experiments/{experiment_id}/pages
POST https://app.softsolz.uk/api/v1/services/seo/experiments/{experiment_id}/measure

Keyword research with your own tools

Research keywords with your own model and data sources, then hand them to SoftSolz. Add up to 100 at once, each with an optional target page on the website, your notes, the source name and your own estimate of monthly searches and difficulty. Your estimates are stored and shown as yours, never mixed with Google’s figures. Then write or improve each target page and record your suggestions. None of this spends SoftSolz AI credits.

bash
POST https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/keywords/bulk
PATCH https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/keywords/{keyword_id}
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/keywords
PUT https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/keywords/{keyword_id}/advice

What this API will not tell you, and why

These are refusals, not gaps. Each one is enforced in code, so writing around them means writing something the data does not support.

  • Google provides no keyword volume or difficulty, so none is invented. Estimates you send with your own keyword research are stored as yours, labelled with their source, and never mixed with Google’s figures. Competition is reported as what the workspace’s own tracked competitors publish, and there is no SEO score for a competitor.
  • Impressions are not indexing. Index state comes only from /sites/{site_id}/index-state, is stamped with when it was checked, and says Not checked otherwise.
  • There is no single average position for a site or a topic, because aggregating it across pages is an average of averages.
  • A competitor’s traffic and rankings are never reported. Everything under /competitors is what a public page of theirs states.
  • An AI answer record is an observation, not a ranking. It says what a named model answered when asked a question on a date, and which sources it listed. Nobody can verify whether an AI product used a page, answers change with every asking, and SoftSolz never judges whether an answer was true. AI search readiness scores page structure only.
  • An experiment without enough comparison pages or days answers inconclusive and carries no p-value, rather than a weak number presented as a result.

What you can read

  • Websites and their Search Console binding, plus performance totals, series, top pages and top keywords for any range.
  • Monthly reports with every finding (detector, severity, the page or query, and the evidence_json numbers behind it) and every recommendation, ranked.
  • Tracked keywords with month-by-month positions and the evidence to write advice from.
  • Links: backlinks with their verified status, an overview, what needs attention, link prospects, brand mentions, crawls and the internal link map.
  • Code: connected repositories, audits with their pass and fail checks, and fix sets.
  • Background tasks, so you can poll anything that runs asynchronously.

What your model can write

WritesEndpointShows up as
An explanation for each findingPUT /runs/{run_id}/narratives (up to 200 at once) or PUT /runs/{run_id}/findings/{finding_id}/narrativeThe plain-English text on the finding card
Suggestions for a tracked keywordPUT /sites/{site_id}/keywords/{keyword_id}/adviceTwo to five suggestions on the keyword
A recommendationPOST /runs/{run_id}/recommendationsA card in the report, linked to the findings it rests on
An explanation for a code findingPUT /code/audits/{audit_id}/findings/{finding_id}/narrativeThe text on the audit finding
Wording and metadata fixesPOST /sites/{site_id}/code/repos/{repo_id}/fixes then POST /code/fixes/{fix_set_id}/pushA pull request on GitHub

Write from the numbers, never from guesses. Every finding carries evidence_json with the current and prior metrics, every keyword advice endpoint returns the evidence next to the advice on file, and the dashboard promises its users that every explanation can be traced back to the data it came from.

What SoftSolz keeps doing

The Search Console sync, the detectors, the ranking of findings and recommendations, backlink verification, web searches for brand mentions, crawls, code audits, the design guard and the pull request itself all run on SoftSolz. None of them involve a model, which is why none of them cost credits from either side. Connecting a Google account or a GitHub account stays in the dashboard, because both need a person to sign in.

AI visibility and questions

Search Intelligence keeps one list of questions per website, checks how well the site answers each one with fixed rules, and records what AI models said when asked them. Every read here is free. Writes need service.seo.ai_search.manage; reads need service.seo.view.

bash
# the score: overall plus SEO, GEO and AEO, each part marked measured or estimated
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/visibility
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/visibility/history?days=180
# questions people ask, and how well the site answers them
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/questions?coverage=unanswered
POST https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/questions
POST https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/questions/import
PATCH https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/questions/{question_id}
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/answer-coverage
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/local
# what AI models said
POST https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/ai-observations
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/ai-observations
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/ai-observations/{observation_id}
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/ai-visibility
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/ai-citations
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/ai-search/settings
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/entities
# opportunities for one pillar, and turning one into a task
GET https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/opportunities?pillar=geo
POST https://app.softsolz.uk/api/v1/services/seo/sites/{site_id}/opportunities/{opportunity_id}/task
  • GET /sites/{site_id}/visibility returns the Search Visibility score and its SEO, GEO and AEO parts. Each part carries its weight, whether it was measured, its source and when it was updated. A pillar with no data is null and left out of the overall score. GET /sites/{site_id}/visibility/history returns the daily overall and pillar scores, oldest first, for up to 730 days; days with no score are left out rather than filled in.
  • GET /sites/{site_id}/questions lists the questions with their kind, best page, demand and coverage (answered_well, partial, weak, unanswered, not_checked). POST adds up to 50 at once, and POST /sites/{site_id}/questions/import adds the questions people already type into Google, from Search Console.
  • PATCH /sites/{site_id}/questions/{question_id} turns Monitor in AI on or off with ai_monitored, sets ai_priority and ai_models, or ignores a question with status: "ignored". The plan limits how many questions a website can monitor.
  • GET /sites/{site_id}/answer-coverage sums coverage up, with featured-answer chances and pages whose markup could describe their questions and answers.
  • GET /sites/{site_id}/ai-visibility returns mention, citation and recommendation rates, share of voice against tracked competitors, results by model and the sources AI answers list most. GET /sites/{site_id}/ai-citations lists every cited domain, your own cited pages and the questions where a competitor is cited while a page of yours could answer.
  • GET /sites/{site_id}/ai-observations lists single recorded answers, newest first, filtered by question_id, provider, model, source (softsolz_check, external_app or manual), competitor_id, topic_id, mentioned, from and to. The answer text is left out of the list; read one with GET /sites/{site_id}/ai-observations/{observation_id}. Every observation is what one named model said on one date and which URLs it listed. It is never a ranking.
  • GET /sites/{site_id}/ai-search/settings reads whether SoftSolz checks the monitored questions on a schedule, how often, with which models, and how much of the monthly check allowance is used. Changing those settings and starting a check only happen in the dashboard.
  • GET /sites/{site_id}/entities returns the business facts the site’s pages state (name, phone, address, description) and every place they disagree. GET /sites/{site_id}/local lists local searches, location pages and the business details your markup shows, when local search applies to the website.
  • ?pillar=seo|geo|aeo on the opportunities list keeps one pillar; each row carries its pillar and, for question items, its question_id. POST /sites/{site_id}/opportunities/{opportunity_id}/task turns one item into a task in the Tasks service (it needs Tasks active and service.tasks.create on the member behind the key, and a second call returns the task already made).

Send in what your own model answered

SoftSolz can ask AI models itself, but only when a member switches AI answer checks on in the dashboard, and those checks use the workspace’s AI credits. No API call starts them. Instead, ask the monitored questions in your own product, with your own model and your own credits, and post each answer back. It spends no SoftSolz AI credits.

bash
curl -X POST https://app.softsolz.uk/api/v1/services/seo/sites/SITE_ID/ai-observations \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: obs-2026-10-08-q1" \
-d '{
"observations": [
{
"question_id": "QUESTION_ID",
"question": "What is the best bakery in Bradford?",
"provider": "anthropic",
"model_id": "claude-sonnet-4-5",
"observed_at": "2026-10-08T09:30:00Z",
"answer_excerpt": "Popular choices include Acme Bakery, known for its sourdough...",
"citations": [{ "url": "https://acmebakery.co.uk/sourdough", "title": "Sourdough" }]
}
]
}'

Up to 50 observations per call. Each needs the question (or a question_id), the provider, the model_id and observed_at (not in the future, not older than 400 days). answer_excerpt is plain text up to 12,000 characters; citations, mentions, sentiment, confidence and external_id are optional. SoftSolz looks for the business and its tracked competitors in the answer text itself, keeps the mentions you send as you sent them, never opens the cited links, and drops an observation it has already stored. Each one shows in the dashboard as Supplied by your app or key name, and counts towards the GEO score. There is a daily limit per website.

Connected AI apps

Each endpoint here is also a tool on the hosted MCP server. A Claude, ChatGPT or Gemini app that was already connected sees the new tools after it reconnects, and only if the member approved service.seo.ai_search.manage for writes.

The ai_visibility flow for AI apps

GET /guide returns ai_app_flows.ai_visibility, the same steps in sentences, so an assistant connected over MCP can follow them without this page:

  1. Read GET /sites/{site_id}/questions to see the questions, how well each is answered and which are monitored in AI.
  2. Monitor or ignore a question with PATCH, add new ones with POST, or import them from Search Console.
  3. Ask each monitored question in your own product, with your own model and your own credits.
  4. Post what you saw to POST /sites/{site_id}/ai-observations, up to 50 per call.
  5. Read the result with ai-visibility, ai-citations and ai-observations, then the score with visibility and visibility/history.
  6. Act on it: opportunities?pillar=geo or ?pillar=aeo, answer-coverage for questions without a good answer, and opportunities/{opportunity_id}/task to hand one item to a person.

None of these calls spends SoftSolz AI credits and none of them starts a SoftSolz AI check. When you report the result to a person, say which model answered, on which date and which pages it listed. Never describe it as a ranking in ChatGPT or any other assistant.

Worked flow: a monthly report your model explains

1. Start the report

The site needs a Search Console property bound to it (gsc_property_url on the site is not null). Leave out period_start to analyse the latest complete month.

bash
curl -X POST https://app.softsolz.uk/api/v1/services/seo/sites/SITE_ID/runs \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: report-2026-08-acme" \
-d '{"period_start":"2026-08-01"}'
202 Accepted
{
"data": {
"run": {
"id": "3f2b9c44-8f4e-4d0a-9c1b-2a7d6e5f1a23",
"site_id": "1ccbcc0f-8720-4d84-8053-18b198d0da36",
"period_start": "2026-08-01",
"period_end": "2026-08-31",
"status": "queued",
"credits_used": 0,
"task_id": "9b1e6d2a-5c3f-4a8e-b7d1-0f2e4c6a8b9d"
},
"task_id": "9b1e6d2a-5c3f-4a8e-b7d1-0f2e4c6a8b9d"
}
}

409 run_exists means that month is already analysed, so read it instead. 409 gsc_not_connected means Search Console is not bound yet, and 400 no_period_available means there is no complete month of data.

2. Poll the task

bash
curl https://app.softsolz.uk/api/v1/services/seo/tasks/9b1e6d2a-5c3f-4a8e-b7d1-0f2e4c6a8b9d \
-H "Authorization: Bearer sk_live_your_key"

Poll every few seconds until status is completed, failed or cancelled. If you registered a webhook, seo.analysis.completed fires at the same moment.

3. Read the report

bash
curl https://app.softsolz.uk/api/v1/services/seo/runs/3f2b9c44-8f4e-4d0a-9c1b-2a7d6e5f1a23 \
-H "Authorization: Bearer sk_live_your_key"

The response holds the run, the site, the findings ordered by impact and the recommendations ordered by priority. Findings whose narrative is null still need an explanation; GET /runs/{run_id}/findings?only_missing=true lists just those.

One finding
{
"data": [
{
"id": "a7c1e9d3-2b4f-4e6a-8c0d-1f3e5a7b9c2d",
"detector": "striking_distance",
"severity": "medium",
"entity_type": "query",
"query_text": "sourdough starter",
"page_path": "/blog/sourdough-guide",
"impact_score": 42.5,
"evidence_json": {
"current": { "clicks": 80, "impressions": 1900, "position": 11.2 },
"prior": { "clicks": 120, "impressions": 1850, "position": 8.9 }
},
"narrative": null,
"narrative_source": null
}
]
}

4. Write the explanations

Two to four sentences per finding, at most 2000 characters, grounded in evidence_json. Ids that are not in this report, duplicates and blank text are skipped and listed in skipped.

bash
curl -X PUT https://app.softsolz.uk/api/v1/services/seo/runs/3f2b9c44-8f4e-4d0a-9c1b-2a7d6e5f1a23/narratives \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"only_missing": true,
"narratives": [
{
"finding_id": "a7c1e9d3-2b4f-4e6a-8c0d-1f3e5a7b9c2d",
"narrative": "Clicks fell from 120 to 80 because the page slipped from position 8.9 to 11.2, just off page one. Impressions held steady, so the demand is still there.",
"confidence": 0.8
}
]
}'
200 OK
{
"data": { "applied": 1, "skipped": [] }
}

5. Add a recommendation

Only a completed report accepts recommendations (409 run_not_completed), and every id in finding_ids must belong to it (400 finding_not_in_run). Members who manage recommendations are notified, and seo.recommendation.created fires.

bash
curl -X POST https://app.softsolz.uk/api/v1/services/seo/runs/3f2b9c44-8f4e-4d0a-9c1b-2a7d6e5f1a23/recommendations \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"title": "Refresh the sourdough guide and add a starter recipe",
"detail_markdown": "**Why:** the page lost 40 clicks a month as it slipped to position 11.2.\n\n**How:** add a step-by-step starter section near the top and update the date.",
"estimated_effort": "medium",
"opportunity_clicks": 180,
"finding_ids": ["a7c1e9d3-2b4f-4e6a-8c0d-1f3e5a7b9c2d"]
}'

The recommendation appears in the report with play: "external_suggestion" and your name as author_label. Accepting, dismissing or reopening it is PATCH /recommendations/{recommendation_id}; turning it into a task stays in the dashboard, where a person approves it.

Keyword suggestions

Read the evidence first, then put the suggestions back. Send two to five, most valuable first; titles are cut at 90 characters and details at 420, and anything beyond five is dropped.

bash
curl https://app.softsolz.uk/api/v1/services/seo/sites/SITE_ID/keywords/KEYWORD_ID/advice \
-H "Authorization: Bearer sk_live_your_key"
200 OK
{
"data": {
"advice": null,
"evidence": {
"query_text": "sourdough starter",
"period_start": "2026-08-01",
"position": 11.2,
"previous_position": 8.9,
"best_position": 5.1,
"months_seen": 9,
"impressions": 1900,
"clicks": 80,
"ctr": 0.0421,
"pages": [
{ "url": "https://acmebakery.co.uk/blog/sourdough-guide", "clicks": 80, "impressions": 1900, "position": 11.2 }
]
}
}
}
bash
curl -X PUT https://app.softsolz.uk/api/v1/services/seo/sites/SITE_ID/keywords/KEYWORD_ID/advice \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-5",
"suggestions": [
{
"title": "Add a step-by-step starter recipe",
"detail": "The page ranks 11th for a query with 1,900 monthly impressions; a recipe section answers the intent directly and is the shortest route back to page one.",
"effort": "medium"
},
{
"title": "Answer the three common starter questions in the intro",
"detail": "Impressions are flat while clicks fell, so the result is still shown but the snippet no longer matches what searchers want to know first.",
"effort": "low"
}
]
}'

The optional model is recorded as external:<model> so the workspace can see which model wrote the advice.

Code fixes that become a pull request

Connect a repository in the dashboard (it needs a GitHub sign-in), then audit it, read the failed checks, fetch the files from the repository yourself, rewrite only the wording and the head or metadata tags, and send the complete new content back. SoftSolz reads the original from the branch head, diffs it, runs the guard, and opens the pull request when you push.

1. Audit

bash
curl -X POST https://app.softsolz.uk/api/v1/services/seo/sites/SITE_ID/code/repos/REPO_ID/audits \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"branch":"main"}'

Returns 202 with the audit. Poll GET /code/audits/{audit_id} until status is completed; the response lists failed checks first and ranks the audited pages by search traffic so fixes go where they count.

2. Create the fix set

One to fifty files per call, each with its full new content. Bodies are capped at 1 MB, so send big sets in batches: create with the first batch, then add more with POST /code/fixes/{fix_set_id}/files until the set is pushed.

bash
curl -X POST https://app.softsolz.uk/api/v1/services/seo/sites/SITE_ID/code/repos/REPO_ID/fixes \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"base_branch": "main",
"files": [
{
"file_path": "src/pages/index.astro",
"title": "Add a meta description",
"reason": "The audit found no meta description on the home page.",
"page_path": "/",
"check_ids": ["description_present"],
"after_content": "<html lang=\"en\"><head><title>Acme Bakery</title><meta name=\"description\" content=\"Sourdough, pastries and cakes baked every morning in Bradford.\">...</head>...</html>"
},
{
"file_path": "src/styles/global.css",
"title": "Tidy the heading font",
"after_content": "h1 { font-family: serif; }"
}
]
}'
201 Created
{
"data": {
"set": {
"id": "5d8f2a1c-7e3b-4c9a-a1f0-6b2d4e8c0a13",
"status": "ready",
"base_branch": "main",
"source": "api",
"author_label": "Claude",
"credits_used": 0
},
"files": [
{
"id": "c2e4a6b8-0d1f-4a3c-9e5b-7f9a1c3e5b7d",
"file_path": "src/pages/index.astro",
"change_kind": "update",
"title": "Add a meta description",
"included": true
}
],
"refused": [
{
"file_path": "src/styles/global.css",
"code": "fix_touches_design",
"message": "\"src/styles/global.css\" controls how the site looks, so it is left alone."
}
]
}
}

The design guard

Every file passes the same guard the dashboard uses. Only wording and head or metadata tags may change; the layout fingerprint of an updated page must be identical to the original. Stylesheets, images, scripts, config files and framework settings are refused, and so is any change that removes content. Only robots.txt, sitemap.xml, llms.txt and security.txt may be created. A refused file never blocks the rest of the set: it comes back in refused with a code and a message you can act on, so fix it and send it again.

CodeWhy the file was refused
fix_touches_designA stylesheet, image or config file, or a change that alters the layout of the page.
fix_adds_scriptThe new content adds a script.
fix_adds_handlerThe new content adds an event handler attribute.
fix_removes_contentWording that was on the page is gone from the new content.
fix_create_not_allowedA new file that is not one of the four permitted site files.
fix_too_largeThe file is bigger than the guard will read.

You may also see fix_path_unsupported, fix_path_unsafe, fix_would_overwrite, fix_missing_original, fix_no_change and fix_duplicate_path, each with the same shape. A set where every file was refused has status: "empty".

3. Choose what goes in, then push

PATCH /code/fixes/{fix_set_id}/files/{file_id} with {"included": false} leaves a file out. Then push:

bash
curl -X POST https://app.softsolz.uk/api/v1/services/seo/code/fixes/5d8f2a1c-7e3b-4c9a-a1f0-6b2d4e8c0a13/push \
-H "Authorization: Bearer sk_live_your_key"
200 OK
{
"data": {
"fix_set": {
"id": "5d8f2a1c-7e3b-4c9a-a1f0-6b2d4e8c0a13",
"status": "pushed",
"branch_name": "softsolz/seo-content-5d8f2a1c7e3b",
"pull_request_url": "https://github.com/acme/bakery-site/pull/42",
"pull_request_number": 42
},
"already_pushed": false
}
}

A push never commits to the base branch. The included files land on a new softsolz/seo-content-* branch and a pull request is opened against the base branch, with your app credited in its first line. The team is notified and seo.fixes.pushed fires. Pushing a set that was already pushed returns the existing pull request with already_pushed: true; 400 nothing_selected means every file is excluded, and 409 fix_set_locked means you tried to add files to a set that is being pushed or already pushed. Merging is a human decision on GitHub.

The full report

GET /sites/{site_id}/full-report (scope service.seo.export) returns everything Search Intelligence knows about a website as one Markdown document, written for a model to read in one go: what to do this month, the ranked growth board, alerts, search performance, keywords, content, links, technical checks, the code check and prepared fixes, experiments and every finding of the monthly analysis. It uses the latest completed report unless you pass run_id, and it spends no SoftSolz AI credits.

bash
curl https://app.softsolz.uk/api/v1/services/seo/sites/0f6c1d2e-8a4b-4c3d-9e5f-1a2b3c4d5e6f/full-report \
-H "Authorization: Bearer sk_live_your_key"
200 OK
{
"data": {
"markdown": "# Acme Bakery - full SEO report\n...",
"file_name": "acme-bakery-co-uk-full-seo-report-2026-09",
"period_start": "2026-09-01"
}
}

Compute you can trigger

These endpoints do real work on SoftSolz and answer 202 Accepted with something to poll. None of them call a model.

EndpointDoesPoll
POST /sites/{site_id}/backfillImports up to 16 months of Search Console historyGET /tasks/{task_id}
POST /sites/{site_id}/runsSyncs, detects and ranks one monthGET /tasks/{task_id}
POST /sites/{site_id}/links/verifyRe-opens every stale backlinkGET /tasks/{task_id}
POST /sites/{site_id}/crawlsCrawls the site to map internal links, within the plan budgetGET /sites/{site_id}/crawls
POST /sites/{site_id}/code/repos/{repo_id}/auditsReads the branch and runs the checksGET /code/audits/{audit_id}

Single-page checks are synchronous instead: verifying one backlink or one prospect opens the page and answers in the same call, and POST /sites/{site_id}/mentions/find runs the web search and returns the counts straight away. POST /tasks/{task_id}/cancel stops a running task (409 cannot_cancel once it has finished).

What a key or an app can see

  • A plain sk_* key sees only websites and repositories shared with the whole workspace (visibility: "tenant"). Everything a website owns follows the website: its reports, findings, keywords and links. Everything a repository owns follows the repository.
  • A connected app sees exactly what the member who connected it sees, including records shared with that member by name or by role, and is limited to the scopes that member approved.
  • POST /sites and POST /sites/{site_id}/code/repos default to private, which a plain key cannot read back. Send "visibility": "tenant" when the API should keep seeing what it created.
  • A record outside your view answers 404, never 403, so an id from another workspace reveals nothing.

Scopes

ScopeAllows
service.seo.viewRead websites, reports, findings, keywords, links and code audits. Every GET: sites, monthly reports with their findings and recommendations, tracked keywords and their evidence, backlinks, prospects, mentions, crawls, code audits and fix sets, plus the Search Visibility score, questions, answer coverage and AI answer records.
service.seo.sites.manageAdd and edit websites and tracked keywords. Create and update websites, track and untrack keywords.
service.seo.deleteArchive websites and delete reports. Archive a website or delete a monthly report.
service.seo.analysis.runStart reports and write explanations. Start a monthly report or a history import, write finding narratives and keyword suggestions with your own model, cancel background tasks. Never spends SoftSolz AI credits.
service.seo.opportunities.manageDecide what to do about an opportunity. Plan, start, finish or dismiss an item on the growth board, and acknowledge or resolve its alerts. Never spends SoftSolz AI credits.
service.seo.briefs.managePlan content. Create content briefs from the evidence, write their outlines with your own model, and order the content roadmap. Never spends SoftSolz AI credits.
service.seo.technical.manageCheck indexing and speed. Re-read the sitemaps, reconcile which pages search engines can see, refresh real-user speed figures, and notify search engines when pages change. Never spends SoftSolz AI credits.
service.seo.competitors.manageTrack competitors. Add the websites to compare against and read their public pages to find the topics they cover and you do not. Never spends SoftSolz AI credits.
service.seo.experiments.manageMeasure a change. Set up a change, choose the pages it applies to, and measure it against comparable pages you left alone. Never spends SoftSolz AI credits.
service.seo.recommendations.manageWrite and decide recommendations. Add recommendations to a completed report and accept or dismiss them.
service.seo.exportExport reports and link files. Render a report as Markdown, download the backlinks CSV and the disavow file.
service.seo.links.manageManage backlinks, prospects and mentions. Record, import, verify and disavow backlinks, run prospects and mentions, change the link-checking settings.
service.seo.crawl.runCrawl the website. Start and cancel crawls that map internal links.
service.seo.code.manageConnect repositories and run code audits. Connect GitHub repositories, start audits and write explanations for code findings.
service.seo.code.applyPropose and push code fixes. Create fix sets from rewritten files, add files, choose what to include and open the pull request.
service.seo.ai_search.manageManage questions and AI answers. Add questions, choose which ones are checked in AI answers, ignore questions, and record the answers your own AI model saw, with the model, the date and the sources it listed. Never spends SoftSolz AI credits.

A connected assistant only ever holds the scopes the member ticked on the consent screen, and a member can only grant scopes their own role already holds.

Events

EventWhen it fires
seo.analysis.completedA monthly report finished and its findings are ready to review.
seo.analysis.failedA monthly report could not be completed.
seo.connection.reconnect_requiredA Google connection stopped working and needs to be reconnected.
seo.backlink.liveA link pointing at your website was found on the page that should carry it.
seo.backlink.lostA link that used to point at your website is no longer on the page.
seo.crawl.completedA crawl of your website finished and the internal link map is ready.
seo.crawl.failedA crawl of your website could not be completed.
seo.prospect.link_liveA link you were chasing went live on the page you were promised.
seo.opportunity.updatedSomebody moved an item on the growth board, or an app did through the API.
seo.recommendation.createdA connected app or API key added a recommendation to a completed report.
seo.fixes.pushedA set of content fixes was committed to a branch and opened as a pull request.
seo.task.startedA background SEO task started.
seo.task.completedA background SEO task finished.
seo.task.failedA background SEO task could not be completed.
seo.task.cancelledA background SEO task was cancelled.
seo.visibility.changedThe Search Visibility score, or one of its SEO, GEO or AEO parts, moved by at least 5 points.
seo.ai_check.completedA round of AI answer checks finished, with counts of mentions and citations.
seo.ai_mention.changedFor one question and model, AI answers started or stopped naming your business.
seo.ai_citation.changedFor one question and model, AI answers started or stopped listing your website as a source.
seo.competitor.ai_visibility_changedA tracked competitor became noticeably more or less visible in AI answers.
seo.question.discoveredNew questions people ask were found for a website.
seo.answer_coverage.changedThe share of questions your pages answer well went up or down.
seo.opportunity.createdA new item was added to the growth board, with its SEO, GEO or AEO pillar.
seo.entity.issue_foundYour pages disagree about a business fact such as your name, phone or address.
seo.analysis.completed
{
"run_id": "3f2b9c44-8f4e-4d0a-9c1b-2a7d6e5f1a23",
"site_id": "1ccbcc0f-8720-4d84-8053-18b198d0da36",
"period_start": "2026-08-01",
"finding_count": 14,
"recommendation_count": 5
}

The search visibility events carry ids, codes and numbers only: never a question, an answer, a URL or a business detail. Read the record they point at with the endpoints above when you need the text.

EventPayload fields
seo.visibility.changedsite_id, day, previous_day, before, after and change (the overall and pillar scores that moved)
seo.ai_check.completedsite_id, task_id, checked_count, failed_count, skipped_count, reused_count, mentioned_count, cited_count
seo.ai_mention.changedsite_id, question_id, observation_id, provider, model_id, mentioned, previously_mentioned
seo.ai_citation.changedsite_id, question_id, observation_id, provider, model_id, cited, previously_cited
seo.competitor.ai_visibility_changedsite_id, competitor_id, share, previous_share, change_points
seo.question.discoveredsite_id, discovered_count, question_ids (the first 10)
seo.answer_coverage.changedsite_id, previous_coverage, coverage, change
seo.opportunity.createdsite_id, opportunity_id, kind, family, pillar, score
seo.entity.issue_foundsite_id, entity_id, entity_kind, issue_code
seo.ai_mention.changed
{
"site_id": "1ccbcc0f-8720-4d84-8053-18b198d0da36",
"question_id": "7a1d0c52-3b9e-4f6a-8d2c-5e4b3a2f1c0d",
"observation_id": "b4e2f9a1-6c3d-4e8b-9a7f-1d2c3b4a5e6f",
"provider": "openai",
"model_id": "gpt-4.1-mini",
"mentioned": true,
"previously_mentioned": false
}

Failure events carry a stable error code, never a raw message, so you can branch on it safely. Every delivery is signed; follow Webhooks for the signature check before you trust a payload.

Sandbox

An sk_test_* key, or a connected app that chose the Sandbox workspace, acts on the sandbox twin: its own websites, reports, keywords and links, never the live ones. Everything above works there, which makes it the right place to develop a prompt or an integration. One thing to know: a repository connected in the sandbox is a real GitHub repository, so a push from the sandbox opens a real pull request on it. Point sandbox repositories at a fork or a test repository.

Next

Every endpoint, parameter, response shape and error code is generated into the API Reference, with samples in cURL, Node, Python and the SDKs. Connect an assistant in a minute with Connect an AI assistant, or read the product walkthrough on docs.softsolz.uk.