API Reference

Base URL: https://getpost.dev/api

Full machine-readable spec: /api/openapi.json


Authentication

POST/auth/signup

Create a new agent account. Returns API key (shown once).

Request body
{ "name": "my-agent", "bio": "optional bio" }
Response
{ "agent_id": "...", "api_key": "gp_live_...", "email": "my-agent@quik.email", "balance_cents": 100 }
GET/auth/me

Get your profile, balance, emails, and phone numbers.

PUT/auth/me

Update your name and/or bio.

Request body
{ "name": "new-name", "bio": "updated bio" }
DELETE/auth/me

Permanently delete your account and all data.

GET/auth/rate-limits

Check your current rate limit usage and remaining quota.

Response
{ "limits": { "per_minute": 60, "per_hour": 1000 }, "usage": { "current_minute": 5, "current_hour": 42 }, "remaining": { "this_minute": 55, "this_hour": 958 } }

Email

POST/email/send

Send an email from your assigned address.

Request body
{ "to": "user@example.com", "subject": "Hello", "body": "...", "html": false, "from_address": "optional" }
GET/email/inbox

Get received emails. Query: ?limit=50&offset=0

POST/email/addresses

Register a dedicated email address ($5/mo).

Request body
{ "local_part": "myname", "domain": "quik.email" }
GET/email/addresses

List your email addresses.


SMS

POST/sms/send

Send an SMS message.

Request body
{ "to": "+14155551234", "body": "Hello from my bot" }
GET/sms/inbox

Get received SMS messages.

POST/sms/numbers

Provision a dedicated phone number ($10/mo).

Request body
{ "area_code": "415", "country": "US" }
GET/sms/numbers

List your phone numbers.


POST/search

Search the web. Returns structured results.

Request body
{ "query": "latest AI news", "num_results": 10 }
Response
{ "query": "...", "results": [{ "position": 1, "title": "...", "url": "...", "snippet": "..." }] }

Web Scrape

POST/scrape

Scrape a web page with a real browser.

Request body
{ "url": "https://example.com", "extract_text": true, "screenshot": false }
Response
{ "url": "...", "text": "..." }

LLM Gateway

GET/llm/models

List available models with per-token pricing.

POST/llm/chat

Chat completion. Model prefix determines provider: gpt-*, claude-*, gemini-*, grok-*.

Request body
{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}], "stream": false }
Response
{ "model": "gpt-4o-mini", "content": "...", "usage": { "input_tokens": 5, "output_tokens": 42, "cost_cents": 1 } }

Shipping

POST/shipping/rates

Get shipping rates for a parcel.

Request body
{ "from": { "name": "...", "street1": "...", "city": "...", "state": "...", "zip": "...", "country": "US" }, "to": { ... }, "parcel": { "length": 10, "width": 8, "height": 4, "weight": 16 } }
POST/shipping/labels

Buy a shipping label.

Request body
{ "rate_id": "...", "shipment_id": "..." }
GET/shipping/track/:id

Track a shipment.


Balance & Billing

GET/balance

Get current balance and last 50 transactions.

POST/balance/topup

Create Stripe checkout for balance topup.

Request body
{ "amount_cents": 1000 }
Response
{ "checkout_url": "https://checkout.stripe.com/...", "session_id": "..." }

Webhooks

Events: email.received, sms.received, balance.low, balance.credited

POST/webhooks

Register a webhook endpoint.

Request body
{ "url": "https://my-agent.com/webhook", "events": ["email.received", "sms.received"] }
Response
{ "id": "...", "url": "...", "events": [...], "secret": "whsec_...", "active": true }
GET/webhooks

List your registered webhooks.

DELETE/webhooks/:id

Delete a webhook.