stewai 0.1.8

Official StewAI Python SDK

stewai (Python SDK)

Base URL (only): https://api.stewai.com/v1

Public docs:

• SDK overview: https://docs.stewai.com/sdk-api/overview
• Availability, scopes, and feature gates: https://docs.stewai.com/sdk-api/availability-and-access

Install

pip install -U stewai

Get an API key

1. Log in to stewai.com
2. Go to Settings → API keys
3. Create a key and copy it once (sk-live-...)

Usage

from stewai import Client

client = Client(api_key="sk-live-...")

# Use the Input step “API input id” shown in the editor as the inputs key
run = client.runs.create(
    recipe_id="01K....",
    inputs={"USERQUESTION": "What should I focus on this week?"},
)

print(run["status"])  # done|failed|cancelled|blocked

# Debug only: full execution trace (steps + outputs)
trace = client.runs.steps(run["id"])

List runs

runs = client.runs.list(page=1, page_size=20, status="done")
print(runs["count"])

List own recipes (/v1/recipes/)

recipes = client.recipes.list(page=1, page_size=20)
print(recipes["count"])

client.recipes.get/create/update/delete map to server endpoints that are currently disabled by default and may return 404.

Access and availability notes

• client.runs is baseline public v1.
• client.recipes.list() is baseline public v1.
• client.recipes.get/create/update/delete exist in the SDK, but may return 404 when recipe self-service is disabled on the deployment.
• client.marketplace.* requires Marketplace to be enabled on the deployment.
• client.marketplace.search(...) also requires the Marketplace search index.
• client.storage.* requires Storage to be enabled on the deployment.
• Scoped keys need the matching permissions such as runs:create, runs:read, recipes:read, recipes:write, marketplace:read, and marketplace:run.

Marketplace discovery (query -> detail -> run)

from stewai import Client

client = Client(api_key="sk-live-...")

recipes = client.marketplace.search(
    "gemini web search",
    visibility="public_open",
    page=1,
    page_size=20,
)

first = recipes["results"][0]
detail = client.marketplace.detail(first["recipe_ulid"])

run = client.marketplace.run(
    first["recipe_ulid"],
    inputs={"query": "latest gemini model updates"},
    wait=True,
)
print(run["status"])

Ingest sources (URLs + Pantry docs)

from stewai import Client, IngestSource

client = Client(api_key="sk-live-...")

run = client.runs.create(
    recipe_id="01K....",
    ingest={
        "ingest_1": [
            IngestSource(uri="https://example.com/docs", kind="url"),
        ]
    },
)

Upload + resolve Pantry paths

from stewai import Client, IngestSource

client = Client(api_key="sk-live-...")

upload = client.storage.upload("./report.pdf")
run = client.runs.create(
    recipe_id="01K....",
    ingest={"ingest_1": [upload.to_ingest_source(label="Q4 Report")]},
)

resolved = client.storage.resolve_path("Reports/Q4.pdf")
if resolved:
    client.runs.create(
        recipe_id="01K....",
        ingest={"ingest_1": [resolved.to_ingest_source()]},
    )

Environment variable

export STEWAI_API_KEY="sk-live-..."

from stewai import Client

client = Client()  # reads STEWAI_API_KEY
run = client.runs.create(recipe_id="01K....", wait=False)
run = client.runs.wait(run["id"], timeout=300)

Output usage contract (credits-first)

• client.runs.steps(run_id) returns output_flat.usage with credits-focused billing fields.
• Raw token counters are hidden by default in user-facing v1 responses.
• Compatibility mode for token counters is server-gated and requires privileged access.