API

The Sleepwalker API lets you run AI Visibility and Content Intelligence workflows over HTTPS.

Use it to serialize pages, generate visibility prompts, queue AI Visibility runs, score content, create persisted Content Intelligence runs, and read results from your own systems.

Base URL

Production API URL:

https://api.sleepwalker.ai

Use the API URL shown in the Sleepwalker app.

Generate an API Key

1. Log in to the Sleepwalker app.
2. Open API from the left sidebar.
3. Click Generate.
4. Give the key a clear name.
5. Copy the key immediately.

Sleepwalker only shows the raw key once. Store it in a server-side secret manager.

API keys start with:

sw_api_live_...

API keys are for HTTP API requests. MCP tokens start with sw_mcp_live_... and are for MCP clients.

Authenticate Requests

Send the key as a bearer token:

Authorization: Bearer sw_api_live_...

Example:

curl -s "https://api.sleepwalker.ai/v1/tests?limit=20" \
  -H "Authorization: Bearer sw_api_live_..."

Scopes

Standard API keys generated in the Sleepwalker app include the complete API surface by default: read access, page serialization, prompt suggestions, AI Visibility runs, and Content Intelligence actions. Turn off actions when a key should only read reports. Sleepwalker still enforces exact scopes behind the scenes so older or custom-scoped keys remain limited to the access they were issued with.

Scope	Allows
tests:read	List and inspect saved tests.
runs:read	Read owned run summaries, statuses, usage, and activity.
pages:content:serialize	Serialize page content.
visibility:prompts:suggest	Generate AI Visibility prompt ideas.
visibility:runs:create	Queue and cancel AI Visibility runs.
content_intelligence:trends:discover	Discover content trends.
content_intelligence:content:score	Score content without saving a run.
content_intelligence:runs:create	Queue persisted Content Intelligence runs.

See Scopes Reference for the complete scope list.

Endpoint Reference

Successful API responses currently return 200 OK.

GET

Endpoint	Purpose	Scope
GET /v1/tests	List saved Console tests.	tests:read
GET /v1/tests/{test_id}	Read one saved test.	tests:read
GET /v1/reports/by-url	Find saved reports by URL.	runs:read
GET /v1/usage	Read credit balance and usage telemetry.	runs:read
GET /v1/activity	Read recent request activity.	runs:read
GET /v1/visibility/models	List selectable models and per-probe prices.	runs:read
GET /v1/visibility/runs	List direct AI Visibility runs.	runs:read
GET /v1/visibility/runs/{run_id}	Read one AI Visibility run.	runs:read
GET /v1/content-intelligence/runs	List direct Content Intelligence runs.	runs:read
GET /v1/content-intelligence/runs/{run_id}	Read one Content Intelligence run.	runs:read

POST

Endpoint	Purpose	Scope
POST /v1/pages/content/serialize	Serialize page content.	pages:content:serialize
POST /v1/visibility/prompts/suggest	Generate AI Visibility prompt ideas.	visibility:prompts:suggest
POST /v1/visibility/runs	Queue an AI Visibility run.	visibility:runs:create
POST /v1/visibility/runs/{run_id}/cancel	Cancel a run’s queued probes and release their credits.	visibility:runs:create
POST /v1/content-intelligence/trends/discover	Discover content trends.	content_intelligence:trends:discover
POST /v1/content-intelligence/content/score	Score content without saving a run.	content_intelligence:content:score
POST /v1/content-intelligence/runs	Queue a persisted Content Intelligence run.	content_intelligence:runs:create

Actions and Runs

Sleepwalker separates single actions from persisted runs.

Type	What it does	Saved?
Serialization	Extracts normalized page content.	No
Prompt suggestion	Generates AI Visibility prompt ideas.	No
Trend discovery	Finds relevant content trends for a URL.	No
Content score	Scores a URL and returns recommendations.	No
AI Visibility run	Queues one or more prompt/platform probes.	Yes
Content Intelligence run	Queues a Content Intelligence analysis.	Yes

Use persisted runs when you need status polling, Activity visibility, Console visibility, or later result retrieval.

Use single actions when you only need an immediate result, such as a serialized page, prompt suggestions, trends, or a score.

Statuses

Run endpoints can return the statuses listed in Enums.

Common run statuses:

Status	Meaning
queued	The run has been accepted and is waiting to start.
running	Work has started.
completed	Work finished and results are available.
failed / cancelled	Work could not complete. Check the response for details.

Create responses can also return partially_queued when some requested probes were queued and the rest were skipped.

AI Visibility runs also report mention rate, an overall_score equal to that mention rate, an AI Visibility band, and probe counts including queued, running, succeeded, errored, and cancelled probes.

Polling, Not Webhooks

Persisted runs are asynchronous. Create a run, then poll its status endpoint until it reaches a terminal state such as completed, failed, or cancelled.

Sleepwalker does not send webhooks or callbacks. Polling is the supported way to detect completion.

Recommended polling interval: 10 to 30 seconds.

Credits

Sleepwalker uses pay-as-you-go credits.

Action	Credits
1 AI Visibility probe	per model, see List visibility models
Page content serialization	1
Prompt suggestion batch	1
Trend discovery	1
Content score with supplied trends	2
Content score without supplied trends	3
Persisted CI run, score depth	3
Persisted CI run, full depth	6

Public pricing:

1 credit = €0.02
minimum top-up = €5.00

Read endpoints, status polling, and invalid requests that are rejected before work begins do not consume credits. Visibility probes that fail without a usable response or citations release their reserved credit.

See Credit Lifecycle for estimated, reserved, settled, released, and failed states.

Limits

Area	Limit
Saved tests	limit defaults to 50 and is clamped to 1-50.
Reports by URL	limit defaults to 5 and is clamped to 1-20 recent runs per matched test.
Direct run lists and Activity	limit defaults to 20 and is clamped to 1-100.
Usage telemetry	recent_limit defaults to 20 and is clamped to 1-100.
Page serialization	max_chars must be between 1 and 25,000. Use offset to page through long content.
Prompt text	Visibility probe prompts support up to 500 characters.
Result payloads	Result endpoints return compact structured data by default. Use include flags for heavier result payloads.

See Limits for the complete limit table.

Pagination

Run list endpoints return newest items first and support cursor pagination:

GET /v1/visibility/runs?limit=20&starting_after=<run_id>

Responses include has_more and next_starting_after.

See Pagination for details.

Idempotency

Create-run endpoints accept idempotency_key.

Use an idempotency key when your integration may retry a request after a timeout.

If the same account, source, and key are replayed while the original run record exists, Sleepwalker returns 200 OK with the existing run handle instead of creating duplicate billable work.

The key is scoped to the authenticated account and access source.

{
  "idempotency_key": "daily-sleepwalker-homepage-2026-06-10"
}

Common Errors

Error responses use a detail field. See Errors for response shapes and machine-readable values.

Endpoint pages list their expected domain-specific errors. API-key requests can also return the shared authentication, rate-limit, validation, and temporary availability errors below.

Status	Meaning
400	The request passed schema validation but contains an invalid URL, cursor, filter, or field combination.
401	Missing or invalid authentication.
402	Insufficient credits for a billable action.
403	Key does not have the required scope, the account is suspended, or the action is unavailable.
404	Resource was not found or does not belong to the authenticated user.
422	A required body/query field is missing, has the wrong type, or violates a declared field bound.
429	API key rate limit exceeded.
500	Extraction, provider, or another unexpected server operation failed.
503	The requested action is temporarily unavailable.

Versioning and Stability

The current API surface is versioned under /v1 and is the supported surface for integrations.

• Backward-incompatible changes are introduced under a new version path.
• Additive changes, such as new endpoints or new response fields, can appear within /v1.

Build clients to tolerate new fields: ignore unknown response fields rather than failing on them.