Bullpen API and CLI

Bullpen exposes one endpoint. Every call is a POST with a JSON body naming an action. Auth is a workspace API key.

POST https://qsxircxaggtazoqrykyz.supabase.co/functions/v1/api
Authorization: Bearer bp_live_...
Content-Type: application/json

{"action": "whoami"}

Quickstart

1. Sign in at https://bullpen.sale/login and open a workspace (you need the manager or admin role).
2. Go to Settings → API keys (https://bullpen.sale/app/settings/api), name the key, copy it. It is shown once.
3. Check it:

export BULLPEN_KEY=bp_live_...
curl -s https://qsxircxaggtazoqrykyz.supabase.co/functions/v1/api \
  -H "Authorization: Bearer $BULLPEN_KEY" -H "Content-Type: application/json" \
  -d '{"action":"whoami"}'
# {"user_id":"…","org_id":"…","workspace":"…","role":"admin","via":"api_key"}

1. Ask Herman to do something:

curl -s https://qsxircxaggtazoqrykyz.supabase.co/functions/v1/api \
  -H "Authorization: Bearer $BULLPEN_KEY" -H "Content-Type: application/json" \
  -d '{"action":"herman_chat","message":"Who is on the floor right now?"}'

CLI

curl -fsSL https://bullpen.sale/install.sh | sh     # installs ~/.local/bin/bullpen (bash, curl, python3)
bullpen login bp_live_...                           # saves the key to ~/.config/bullpen/key
bullpen whoami
bullpen herman "find 10 HVAC companies in Salt Lake City"
bullpen brain "what does Bullpen cost for a team of five?"
bullpen knock +18015551234 "Acme Electric" "Jane Doe, GM"
bullpen call campaign_create name="Q4 HVAC"            # any action: key=value, key:=<json>

Pricing

Usage-based, prepaid credits: $5 per human reached (bridge or knock), $0.30 per crew minute, $3/month per number, $0.03 per text, $0.25 per fax page. New workspaces get $10. At a zero balance, spending actions return 402. Check with credits_status. Full table: https://bullpen.sale/pricing

Paying from an agent

An agent can top up its workspace's credits itself, with no checkout page, using the Machine Payments Protocol (MPP, through Stripe). It can also attach an AP2 mandate proving its principal allowed the spend.

POST https://bullpen.sale/pay/credits?amount=25
X-Bullpen-Key: bp_live_...

1. The first request returns 402 with a WWW-Authenticate: Payment … challenge ($5–$500).
2. The agent pays with a card Shared Payment Token (for example npx @stripe/link-cli mpp pay <url>) and retries with Authorization: Payment ….
3. Bullpen credits the workspace and answers with a payment receipt.

No account yet? An agent can create the workspace itself by paying:

POST https://bullpen.sale/pay/signup?amount=25
Content-Type: application/json

{"owner_email": "ops@yourco.com", "company": "Your Co", "agent_name": "your agent"}

Same 402 → pay → retry flow ($25–$500, all of it becomes credits, plus the $10 welcome credit). The paid response returns api_key, org_id and balance_cents. Research, Herman, the brain, company search and campaigns work right away. Outbound calls and texts unlock after the owner opens the invite email, signs in, accepts the Outbound Compliance Agreement and adds a phone number, because a person has to stand behind outbound.

AP2 (optional). Get a challenge first:

GET https://bullpen.sale/pay/ap2/challenge?amount=25
X-Bullpen-Key: bp_live_...
# {"aud":"bullpen.sale","nonce":"n_…","transaction_id":"tx_…","payee":{"id":"bullpen.sale","name":"Bullpen"},"payment_amount":{"amount":2500,"currency":"USD"}}

Close your open mandate to exactly that (aud, nonce, transaction_id, payee, amount in cents) and send the dSD-JWT chain on both requests as X-AP2-Mandate. Bullpen checks the root issuer against the workspace's trusted issuers (Settings → API keys), every hop's signature and hash binding, every hop's amount and payee limits (not just the root's), expiry, and replay. A paid request returns ap2_receipt, an ES256 JWT whose reference is sha256 of the closing mandate. Verify it with https://bullpen.sale/pay/ap2/jwks.

Auth

• API key (bp_live_…): acts as the member who created it, in that workspace. Revoke it any time in Settings → API keys.
• Keys can call the actions listed below. Billing, buying numbers, connecting Salesforce/Google and inviting people need a signed-in person.
• Errors come back as {"error":"…"} with an HTTP status: 400 bad input, 401 bad or revoked key, 403 not allowed for this key or role, 402 out of credits, 409 a precondition (e.g. phones not set up).

Actions

Account

• whoami → user, workspace, role.

Herman (the chat agent that runs the bullpen)

• herman_chat {message} → Herman's reply. Outside actions (calls, texts, email) come back as pending with an id; nothing goes out until confirmed. Herman must be switched on for the key's user.
• herman_decide {id, decision: "confirm"|"cancel"} → runs or drops a pending action.

Company brain

• brain_ask {question} → answer with sources, gated by the member's role.

Calls

• bridge_call {to, target?, why?} → a crew member dials, works the menu / hold / AI receptionist, asks "real person or AI?", and connects the key's user the moment a person is on.
• knock_call {to, company, target?, note?} → reach a human at a company line and leave "we got to your humans — find us at bullpen.sale". Company lines only, business hours, once a week per company.
• knock_many {targets:[{company, phone, target?}]} → two at a time.
• floor_state → live and recent crew calls.

Messages

• send_sms {to, body} → from the workspace's line (E.164 to). Opt-outs are honored.
• mail_send {to, subject, text, cc?} → from the workspace's agent inbox.

Finding companies

• company_search {query, max?} → companies with their main line and website.
• company_research {id} → who to ask for at a found company.
• twilio_search {area_code} → numbers available to buy (buying needs a person).

Campaigns

• campaign_create {name, goal?} · campaign_import {id, csv} · campaign_update · campaign_cycle_now {id} · campaign_work {id} · campaign_chat {id, message}

Social Intel (watch companies for buying and risk signals)

• intel_add {names} (comma or newline separated) · intel_update · intel_remove · intel_scan_now

Meetings

• book_meeting · meeting_status

Rules the crew follows

• Cell phones need written consent before an AI calls them; company lines don't.
• Calling hours follow the callee's time zone.
• STOP / opt-outs end texts and calls to that number.
• The crew says it is an AI when asked.

Contact

office@roseglass.dev · https://bullpen.sale