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?"},
    wait="safe",
)

print(run.status)      # done|failed|cancelled|blocked
print(run.outputs())   # concrete output_flat primary values by step id

# Debug only: full execution trace (steps + outputs)
trace = client.runs.steps(run.run_id)

Published recipes expose their declared integration surface on completed recipe_output steps. Those steps have output_flat.type == "json", with the advertised output-field mapping in output_flat.primary. RunOutcome.outputs() returns those mappings by step id alongside any other concrete trace outputs. Older deployments that return an empty recipe-output surface remain supported; the SDK skips only that empty compatibility placeholder.

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.

Recipe contracts (own published recipes)

contract = client.recipes.get_execution_contract("01K....")

print(contract["contract_version"])
print(contract["step_order"])
print(sorted(contract["steps"].keys()))

• client.recipes.get_execution_contract(...) returns the full pre-execution contract for all step outputs in a published recipe.
• client.recipes.get_output_contract(...) is narrower: it returns only the final recipe_output surface and may return recipe_output_missing when the recipe has no final output step.

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.recipes.get_execution_contract(...) and client.recipes.get_output_contract(...) use the same recipe self-service surface and require a published same-org recipe with recipes:read.
• client.marketplace.* requires Marketplace to be enabled on the deployment.
• client.marketplace.search(...) also requires the Marketplace search index.
• client.marketplace.input_fields(...) needs marketplace:read; it is never called implicitly by marketplace.run(...).
• client.marketplace.run(...) needs marketplace:run and still posts directly by default.
• 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"])

from stewai import validate_inputs

fields = client.marketplace.input_fields(first["recipe_ulid"])
inputs = {"query": "latest gemini model updates"}
validate_inputs(inputs, fields)

outcome = client.marketplace.run(
    first["recipe_ulid"],
    inputs=inputs,
    wait="safe",
)
print(outcome.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.