cracked-ai (Python)

Zero-dependency Python client for Cracked, the tool router for agents: one API key, one balance, 50,000+ tools (scrapers, search, data, AI models). Discover a tool in natural language, inspect its schema, run it, poll if it is asynchronous.

Publishing to PyPI soon. Until then install from the repo path:

pip install ./sdk/python            # from the repo root
# or, once published:
pip install cracked-ai

Python 3.9+. Uses only the standard library (urllib).

Quick start

import os
from cracked_ai import Cracked, CrackedError

c = Cracked()  # reads CRACKED_API_KEY; base URL from CRACKED_BASE_URL (default https://cracked.ai/v1)

hits = c.discover("weather forecast for a lat/long", limit=5)["results"]
best = hits[0]
schema = c.inspect(best["provider"], best["endpoint"])["input"]["body"]   # JSON Schema, never guess fields

rec = c.run("open-meteo", "/forecast", {"latitude": 30.27, "longitude": -97.74})
print(rec["status"], rec["billing"]["totalUsd"])
print(rec["output"])

No key yet? Register an agent workspace with no human in the loop (trial credit included):

reg = Cracked.register_agent(name="my-agent")
reg.client.run(...)            # ready to use
print(reg.api_key)             # shown once: store it as CRACKED_API_KEY
print(reg.claim_url)           # give this to your human: adds credit, unlocks top-ups

Methods

All responses are plain dicts typed as TypedDicts (RunRecord, SmartRunRecord, DiscoverResult, InspectResult, Balance, ...). Import them from cracked_ai.

Async runs

Scrapers marked async: true in discover results can take minutes. Either let the client poll:

rec = c.run("apify", "/apify/instagram-profile-scraper", {"usernames": ["nike"]}, wait=False, poll=True, timeout=600)

or drive it yourself:

rec = c.run("apify", "/apify/instagram-profile-scraper", {"usernames": ["nike"]}, wait=False)   # HTTP 202, status RUNNING
rec = c.wait_for(rec["runId"], timeout=600)                                                     # or c.get_run(id, wait=30) in a loop
c.stop(rec["runId"])                                                                            # abort if needed

Terminal statuses: COMPLETED, FAILED, BLOCKED, STOPPED, TIMED_OUT. COMPLETED with providerResponse.httpStatus == 404 means the provider found nothing; that is not an error. BLOCKED (HTTP 503, not billed) means the provider needs your own key: add it at /app/connections or pick another result.

Errors

Every non-2xx response raises CrackedError with .status, .code, .message (and .run_id when relevant):

try:
    c.run("some-provider", "/endpoint", {...})
except CrackedError as e:
    if e.insufficient_funds:   # 402: top up at https://cracked.ai/app/billing or earn credit via bounties
        ...
    elif e.unauthorized:       # 401: bad or missing key
        ...
    elif e.rate_limited:       # 429
        ...

Transport failures raise CrackedError with status == 0 and code NETWORK_ERROR / NETWORK_TIMEOUT.

CLI

python -m cracked_ai discover "instagram profile followers" -l 5
python -m cracked_ai inspect open-meteo /forecast
python -m cracked_ai run open-meteo /forecast '{"latitude":30.27,"longitude":-97.74}'
python -m cracked_ai capability instagram-profile '{"username":"nike"}'
python -m cracked_ai get <runId> -w 30
python -m cracked_ai balance
python -m cracked_ai register my-agent

(cracked-ai ... works too once installed via pip.)

Tests

tests/test_smoke.py hits the live API and is skipped unless CRACKED_API_KEY is set. It spends well under $0.05 (two keyless weather calls).

CRACKED_API_KEY=ck_live_... CRACKED_BASE_URL=https://cracked.ai/v1 python -m pytest sdk/python/tests -q

Publishing

cd sdk/python && python -m pip install build twine && python -m build && twine upload dist/*