Python SDK
A client generated from the API contract, standard library only, with pagination, idempotency keys and error handling built in.
The package is showpilot, generated from the same OpenAPI file the reference pages come from, so its methods match the API exactly: one attribute per section of the reference, one method per endpoint, names in snake_case. It has no dependencies and runs on Python 3.9 or later.
It is not on PyPI yet. Until it is, it lives in the ShowPilot repository as packages/sdk-python; copy the showpilot folder into your codebase (three files).
Setup
from showpilot import ShowPilot, ShowPilotAPIError, paginate
client = ShowPilot(api_key=os.environ["SHOWPILOT_API_KEY"])Options: base_url (default https://api.showpilot.com/v1), transport (bring your own HTTP, or a fake in tests), retry_reads (default True: reads retry on 429 up to three times, honouring Retry-After; writes are never retried).
Reads
page = client.tours.list_tours(status="published", limit=50)
tour = client.tours.get_tour(page["items"][0]["id"])
print(len(tour["document"]["screens"]))
for visitor in paginate(client.visitors.list_visitors, identified=True):
print(visitor["email"], visitor["intentScore"])Path parameters are positional, query parameters are keyword arguments, and every response is the JSON document as a dict.
Writes
hook = client.webhooks.create_webhook({"url": "https://hooks.example.com/events", "events": ["meeting.booked"]})
client.follow_ups.answer_follow_up(task_id, {"answer": "Yes, SAML is on the Team plan."}, idempotency_key="ticket-4821")Every write sends an Idempotency-Key; pass your own to make a retry safe across processes, or let the client mint one per call.
Errors and limits
try:
client.tours.get_tour("nope")
except ShowPilotAPIError as e:
print(e.status, e.code, e.request_id) # 404 not-found …
print(client.last_rate_limit) # {'limit': 60, 'remaining': 59, 'reset': …}
print(client.mode) # 'live' or 'test'e.retry_after_sec is set on 429, e.current_version on a stale apply, e.problems on a failed lint.
Events
from showpilot import paginate_events
for event in paginate_events(client.events.list_events, since=last_seen_id):
handle(event)