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
Section titled “Base URL”Production API URL:
https://api.sleepwalker.aiUse the API URL shown in the Sleepwalker app.
Generate an API Key
Section titled “Generate an API Key”- Log in to the Sleepwalker app.
- Open API from the left sidebar.
- Click Generate.
- Give the key a clear name.
- Choose the access level or scopes.
- 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
Section titled “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
Section titled “Scopes”Scopes limit what an API key can do.
| 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 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. |
Use the smallest scope set that can perform the job.
See Scopes Reference for the complete scope list.
Endpoint Reference
Section titled “Endpoint Reference”Successful API responses currently return 200 OK.
| 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/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 |
| 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/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
Section titled “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
Section titled “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 probe counts, including queued, running, succeeded, errored, and cancelled probes.
Polling, Not Webhooks
Section titled “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
Section titled “Credits”Sleepwalker uses pay-as-you-go credits.
| Action | Credits |
|---|---|
| 1 AI Visibility probe | 1 |
| 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.02minimum top-up = €5.00Read 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
Section titled “Limits”| Area | Limit |
|---|---|
| List endpoints | limit is clamped to the endpoint maximum. Saved tests use 50. Run/activity endpoints use 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
Section titled “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
Section titled “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
Section titled “Common Errors”Error responses use a detail field. See Errors for response shapes and machine-readable values.
| Status | Meaning |
|---|---|
400 | Invalid request body, unsupported filter, or missing required field. |
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. |
503 | The requested action is temporarily unavailable. |
Versioning and Stability
Section titled “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.