poke 0.1.1

Poke.com Developer SDK

poke

The official Poke Python SDK for sending messages to your Poke agent, creating webhook triggers, and firing webhooks.

Built by Interaction Company in California.

Installation

pip install poke

Zero dependencies. Works with Python 3.8+.

Quick start

from poke import Poke

client = Poke(api_key="pk_...")

# Send a message to your agent
client.send_message("Summarize my unread emails")

# Create a webhook trigger
webhook = client.create_webhook(
    condition="When a deploy fails",
    action="Send me a summary of the error",
)

# Fire the webhook with data
client.send_webhook(
    webhook_url=webhook["webhookUrl"],
    webhook_token=webhook["webhookToken"],
    data={"event": "deploy_failed", "repo": "my-app", "error": "OOM killed"},
)

Authentication

The SDK resolves credentials in this order:

1. api_key passed to the constructor
2. POKE_API_KEY environment variable
3. Credentials from poke login (~/.config/poke/credentials.json)

# Option 1: Pass directly
client = Poke(api_key="pk_...")

# Option 2: Set POKE_API_KEY in your environment
client = Poke()

# Option 3: Run `poke login` first, then
client = Poke()

Get your API key at poke.com/kitchen/api-keys.

Methods

client.send_message(message)

Send a text message to your Poke agent.

result = client.send_message("What meetings do I have today?")
# {"success": True, "message": "..."}

client.create_webhook(condition, action)

Create a webhook trigger. Returns a webhookUrl and webhookToken that you use with send_webhook.

webhook = client.create_webhook(
    condition="When a new user signs up",
    action="Send me a welcome summary in Slack",
)
# {
#     "triggerId": "...",
#     "webhookUrl": "https://poke.com/api/v1/inbound/webhook",
#     "webhookToken": "eyJhbG..."
# }

client.send_webhook(webhook_url, webhook_token, data)

Fire a webhook trigger with data. Use the webhook_url and webhook_token returned by create_webhook.

client.send_webhook(
    webhook_url=webhook["webhookUrl"],
    webhook_token=webhook["webhookToken"],
    data={"event": "new_signup", "email": "[e-mail]", "plan": "pro"},
)
# {"success": True}

Configuration

Option	Environment Variable	Default
api_key	POKE_API_KEY	—
base_url	POKE_API	https://poke.com/api/v1

Error handling

from poke import Poke, AuthenticationError, ForbiddenError, RateLimitError, PokeError

client = Poke()

try:
    client.send_message("hello")
except AuthenticationError:
    print("Bad API key")
except ForbiddenError:
    print("Key lacks required scopes")
except RateLimitError:
    print("Slow down")
except PokeError as e:
    print(f"API error ({e.status}): {e}")

Configuration

Credentials are stored in ~/.config/poke/credentials.json (respects $XDG_CONFIG_HOME).

Environment Variable	Description	Default
POKE_API_KEY	API key for SDK usage	—
POKE_API	API base URL	https://poke.com/api/v1