Feature coverage

SearchChamp has three different integration surfaces. They do not expose the same capabilities:

• The public REST API is a stable, API-key-authenticated surface with ten endpoints: eight reads and two status updates.
• The MCP connector gives compatible AI clients a broader, permission-scoped tool catalog.
• The SearchChamp app contains product workflows that are not yet public integration contracts.

Capability map

The MCP tool reference lists the exact tools, inputs, outputs, scopes, plan requirements, and availability. A capability named in the app column is not available to an external integration unless the REST or MCP column also names a supported route or tool.

Content Writer: what external clients can do

External clients can work with content that already exists in SearchChamp:

• Browse the full editorial feed with GET /v1/api/content/articles or list_content_articles, filtered by status=draft / status=published.
• Discover publish-ready drafts with get_content_drafts or list_draft_articles.
• Read a complete draft with GET /v1/api/content/articles/{id} or get_article_content.
• Mark an article published in SearchChamp with PATCH /v1/api/content/articles/{id} or set_content_article_status.
• Read rewrite guidance with get_page_recommendations and the configured voice with get_brand_voice.
• Publish through start_publish and report_publish when the calling agent performs the external write.
• Use publish_article when the connection, scope, role, plan, and server-side enablement allow SearchChamp to run its standard publisher.

Creating a brand-new Content Writer article is not currently a public REST operation or a dedicated MCP tool, and no route or tool on any public surface starts a generation run. Use the SearchChamp app to start article generation.

Original-draft recovery: authenticated app contract

Original Autopilot recovery is not a public REST endpoint or MCP tool. It uses the browser-authenticated app route POST /v1/sites/{siteId}/content/autopilot/queue/{queueId}/retry, with the strict body { "idempotency_key": "your-stable-request-key" }. Owner and Account Admin access, or an Editor's site assignment, plus current paid-account and frozen-site restrictions apply. A repeated key returns the existing request; using that key for another original queue conflicts.

The request records intent for the same article and brief, not a new article, opportunity claim, executable future queue or immediate provider call. The original successful debit, unchanged quality-held draft and absence of an active recovery, refund or successful publication are required. Requests share the three-retry budget. Admission waits for natural cadence and rechecks current entitlement, settings, consent, connection and spending controls.

GET /v1/sites/{siteId}/content/autopilot returns the site's recent recoveries, including the request and original/new queue identities, status, reason, linked publish ID and publish_status when one exists. Requested, admitted and generating states are progress; held, failed and blocked are terminal. A dispatched state does not confirm publication: it identifies publisher handoff, and CMS publication requires actual destination verification.

Recovery requires a new rewrite and judge PASS and the unchanged quality threshold. It preserves the original debit and refund history, adds no second five-credit article debit, and journals actual provider usage for its distinct generation identity. A failed or newly held attempt has no automatic second recovery. See Autopilot recovery for the user-facing conditions.

Opportunities: claiming topics in the app

Use Claim this topic in the SearchChamp app to work on an eligible opportunity. An article topic opens its matching Article Brief. A topic cluster opens Queue with that topic selected, where you can see the existing cluster plan and its linked spokes' progress. A cluster plan is not an Article Brief.

Claiming the same topic again reopens its existing brief or active cluster plan. It does not create another active plan or duplicate the linked spokes. Planning a cluster does not approve or write an article; writing and publishing keep their own permission and credit requirements.

If the destination cannot be opened, the app displays a failure with a retry action. A plan may already have been saved, so retrying should reopen that plan. Access, subscription and frozen-site restrictions remain valid reasons for a claim to be refused.

If generation cannot be queued, the app returns 503 with claim_queue_unavailable and displays “Could not start this topic. Please try claiming it again.” The failed request does not become a successful cached claim. Claim this topic again when the generation service is available.

Claiming topics and planning clusters remain app-only workflows. There is no public REST route for these actions, and the MCP get_opportunities tool reads opportunities rather than claiming them.

Research: what external clients can do

Research Studio sessions that already exist are readable and publishable:

• List a site's sessions with GET /v1/api/research/sessions or list_research_sessions.
• Read one session — its latest brief, pinned sources, and keywords — with GET /v1/api/research/sessions/{id} or get_research_session.
• Mark a session published in SearchChamp with PATCH /v1/api/research/sessions/{id} or set_research_session_status.

Two boundaries apply. No surface starts a research run: ask_atlio provides natural-language, tenant-scoped assistance over SearchChamp data and can propose supported actions, but it is not a session-start API — beginning a deep research session and managing its sources remains a SearchChamp app workflow. And a session with no site assigned is invisible to external clients: session tenancy is proven through the site, so a site-less session is neither readable nor publishable through REST or MCP. Assign it a site in the app first.

AI Visibility: what external clients can do

Use the REST summary endpoint for reporting integrations that need the latest score, prompt counts, appearance rate, and share of voice. Use MCP for an AI client that needs the AI Visibility read plus related bot-access, site-snapshot, opportunity, or recommendation context. Creating prompts, changing engine configuration, and launching scans remain app workflows.

Internal generation identifiers and receipt polling do not add a public REST route or MCP tool. They support SearchChamp's collection and accounting workflow; external reporting clients continue to use the documented summary endpoint or MCP reads.

Why the surfaces differ

Public REST routes are long-lived contracts: they need versioned payloads, API-key authorization, tenant isolation, rate limits, metering, error semantics, and compatibility guarantees. SearchChamp exposes the smaller reporting surface today rather than presenting internal application routes as stable public APIs. MCP has a broader catalog because every tool declares its own schema, permission class, plan rules, and execution safeguards.

If your integration only needs data export or reporting, use the REST endpoint reference. If an AI client needs richer SearchChamp context or approved workflows, use the MCP documentation.

Backlinks outreach: app-only sending safeguards

The authenticated app routes POST /v1/outreach-pitches/{id}/send, POST /v1/sites/{siteId}/outreach-pitches/bulk with op=send, POST /v1/outreach-pitches/{id}/suggested-reply/approve, and POST /v1/sites/{siteId}/outreach-reply-threads/bulk with op=approve are app-only workflows, not new public REST endpoints or MCP tools.

Trial, lapsed-trial, missing-organization and unresolved-plan sending requests return 402 trial_outreach_blocked with upgrade_url: /account/billing, before any pitch or outbound-message write, secret lookup, or queued delivery. Suggested-reply approval counts as sending even though the original message was inbound. Authorization and tenant checks run first. Grandfathered free accounts with a NULL subscription status are not treated as expired trials.

Bulk pitch send mirrors single-send eligibility, creator/designated-sender checks, mailbox connection and daily-cap prechecks. At the site or workspace daily limit, 429 outreach_daily_cap is returned before enqueueing. If usage cannot be determined, 503 outreach_capacity_unavailable prevents enqueueing. A missing mailbox returns 409 no_email_provider_connected; missing queue configuration returns 503 queue_unavailable only after authorization and trial/cap refusals. Bulk sends skip individually ineligible pitches. Non-send operations retain their existing permissions and contracts. Queue acceptance is not proof of delivery.