Skip to main content

​
Install

pip install stablebrowse
Python 3.9+ required. Depends only on httpx.

​
Configuration

from stablebrowse import Stablebrowse

# Explicit
client = Stablebrowse(api_key="sb_live_...")

# Or read from env:
#   STABLEBROWSE_API_KEY   — the bearer token
#   STABLEBROWSE_BASE_URL  — override API base (useful for beta / local)
client = Stablebrowse()

​
Running tasks

The sync-feeling happy path: submit + poll in one call. 
result = client.tasks.run(
    end_user_id="alice",
    task="Give me the top 3 Show HN posts from today",
)
print(result.result)
run() blocks until the task terminates. If you’d rather drive the poll loop yourself (for progress UI, concurrent submission, etc.): 
submission = client.tasks.submit(end_user_id="alice", task="...")
import time
while True:
    task = client.tasks.get(submission.task_id)
    if task.is_terminal:
        break
    time.sleep(2)
print(task.result)

​
All task options

result = client.tasks.run(
    end_user_id="alice",
    task="Summarize this article",
    session_id="s_abc...",               # optional, continue existing session
    start_url="https://example.com/x",   # optional, skip agent URL-discovery
    schema={"type": "object", ...},      # optional, structured output
    max_steps=10,                        # optional, agent step cap (≤ 25)
    include_html_dump=True,              # optional, return raw HTML
    poll_interval=2,                     # optional, how often to poll (seconds)
    poll_timeout=300,                    # optional, give-up threshold (seconds)
)

​
Sessions / follow-ups

first = client.tasks.run(end_user_id="alice", task="Who's trending on HN?")
follow = client.tasks.run(
    end_user_id="alice",
    task="What's the score on the top one?",
    session_id=first.session_id,
)
Fetch every turn in a session: 
session = client.sessions.get(first.session_id)
for t in session.tasks:
    print(t.status, t.task)

​
Design extraction

Pull a site’s images, fonts, colors, icons, design tokens, and logo as structured data. See Design extraction for what each extractor returns. 
task = client.design.run(
    url="https://www.figma.com/",
    end_user_id="alice",
    extractors=["colors", "fonts", "logo"],  # omit to run all six
)
print(task.design["results"]["colors"]["colors"][:3])
run() submits + polls until the extraction terminates (typically 5–15 seconds). For manual control: 
submission = client.design.submit(
    url="https://www.figma.com/",
    end_user_id="alice",
)
# ... later — design tasks ride the same task record as agent tasks
task = client.tasks.get(submission.task_id)
if task.is_terminal and task.status == "completed":
    print(task.design)

​
Options

task = client.design.run(
    url="https://www.figma.com/",
    end_user_id="alice",
    extractors=["images", "fonts", "colors", "icons", "tokens", "logo"],
    poll_interval=2,
    poll_timeout=300,
)
task.design is the raw JSON the server returns — see the response schema. Asset URLs are signed S3 links valid for 7 days; re-submit the task to refresh.

​
End-user credentials

# Upload (idempotent upsert — only touches platforms you pass)
client.end_users("alice").credentials.set(
    twitter_auth_token="...",
    twitter_ct0="...",
)

# Status (never returns secrets)
status = client.end_users("alice").credentials.get()
assert status.platforms["twitter"] is True

# Clear some fields or everything
client.end_users("alice").credentials.delete(
    fields=["twitter_auth_token", "twitter_ct0"],
)
client.end_users("alice").credentials.delete()  # wipe all
Python uses snake_case keyword arguments; the SDK maps them to the API’s camelCase field names on the wire.

​
API key management

Create and revoke API keys in the dashboard under Settings → API Keys. Key lifecycle is dashboard-only by design — so a leaked key can’t mint more.

​
Exceptions

from stablebrowse import StablebrowseError, TaskFailed, TaskTimeout

try:
    result = client.tasks.run(end_user_id="alice", task="...")
except TaskFailed as e:
    print("Agent reported failure:", e.task.error)
except TaskTimeout as e:
    print("Poll deadline reached, task still", e.task.status)
except StablebrowseError as e:
    print("HTTP/transport error:", e.status_code, e.body)
  • TaskFailed and TaskTimeout both extend StablebrowseError and carry the (failed / in-progress) Task record on .task.
  • StablebrowseError for everything else — catch this for a blanket handler.

​
Typed results

Every response model is a lightweight @dataclass with typed fields. Unknown fields from the server are preserved on .raw so a server-side addition doesn’t break your client: 
task = client.tasks.get(tid)
print(task.status)            # typed
print(task.result)             # typed (str | dict)
print(task.raw["some_new_field"])  # any future field the server adds

​
Version pinning

The SDK follows semver:
  • 0.x.y — API may change on minor bumps. Pin conservatively while we stabilize.
  • 1.x.y — breaking changes only on major bumps (post-1.0).
# requirements.txt — pin to latest patch in 0.1.x
stablebrowse ~= 0.1.0

# Or pin exactly for reproducibility
stablebrowse == 0.1.2

​
Source

Package source lives on PyPI. The full client is a thin wrapper over the HTTP API — if you hit a bug or want a feature, reach out at team@stablebrowse.ai.