Oakstack overview
Oakstack is one API key for the infrastructure every app ends up needing:
| Module | What it does | Status |
|---|---|---|
| clock | Call a URL in your app on a cron schedule, with retries and a run log | Available |
| hook | A permanent inbound URL for webhooks: store every event, forward it, retry, replay | Available |
| HTML in, PDF out, with hosted templates (invoice, proposal, report) | Available | |
| lens | Photos, screenshots, PDFs, and pasted text in, structured data out (Claude) | Available |
| post | Transactional email, plus inbound email delivered to a hook | Test mode now; live sending opening soon |
| ring | Text messages (SMS) from your own verified toll-free number, replies to a hook | Test mode now; live texting opening soon |
| bell | Push notifications to browsers, iPhones (APNs), and Android (FCM), per user | Available |
It's built for coding agents. The SDK, the MCP server, and these docs are designed so an agent can set everything up from a one-line request like "run my cleanup every night at 3am Chicago time" or "make a PDF invoice for every order."
Example app
github.com/shwebz/oakstack-starter is a small Next.js shop back office that uses every module: an order sends a PDF invoice by email, a text, and a push; a nightly job emails a summary; payment webhooks arrive through the relay; a photo becomes a product list. npm run setup creates everything it needs.
Setup
- Create an account and an API key at https://oakstack.dev/dashboard/api-keys.
- Put the key in your app's environment as
OAKSTACK_API_KEY. Keys start withok_live_orok_test_; never commit them. - Pick one or more ways in:
SDK (TypeScript/JavaScript):
npm install oakstack
import { Oakstack } from "oakstack";
const oakstack = new Oakstack(); // reads OAKSTACK_API_KEY
The SDK has zero dependencies and runs in Node 18+, Bun, Deno, Vercel Edge, and Cloudflare Workers.
MCP (lets your coding agent manage Oakstack directly):
# Hosted, nothing to install:
claude mcp add --transport http oakstack https://oakstack.dev/mcp --header "Authorization: Bearer $OAKSTACK_API_KEY"
# Or local over stdio:
claude mcp add oakstack -e OAKSTACK_API_KEY=ok_live_... -- npx -y oakstack-mcp
Claude Code plugin (the skill plus the hosted MCP server in one install): with OAKSTACK_API_KEY exported in your shell:
/plugin marketplace add shwebz/oakstack-plugin
/plugin install oakstack@oakstack
REST: every endpoint is under https://oakstack.dev/api/v1/ and takes Authorization: Bearer <key>.
Quick examples
// Call your app every weekday at 9:00 Chicago time.
const job = await oakstack.clock.jobs.create({
name: "Morning digest",
schedule: "0 9 * * 1-5",
timezone: "America/Chicago",
url: "https://yourapp.com/api/cron/digest",
});
// A permanent webhook URL for Stripe that never loses events.
const endpoint = await oakstack.hook.endpoints.create({
name: "Stripe",
forwardUrl: "https://yourapp.com/api/webhooks/stripe",
});
// Give endpoint.url to Stripe.
Requests Oakstack sends to your app are signed. Verify them with verifySignature (see signatures).
Errors
Every error response is JSON with a machine-readable name and a message that says what to fix:
{
"statusCode": 400,
"name": "invalid_request",
"message": "schedule: must be a 5-field cron expression ..."
}
The SDK throws these as OakstackError (statusCode, errorName, message).
| Status | name |
Meaning | What to do |
|---|---|---|---|
| 400 | invalid_request |
A field is missing or invalid | Fix the field named in message |
| 400 | invalid_idempotency_key |
Bad Idempotency-Key header | Use 1-255 printable characters, such as a UUID |
| 401 | missing_api_key / invalid_api_key |
No key, or the key is wrong, revoked, or expired | Check OAKSTACK_API_KEY |
| 403 | restricted_api_key |
A Restricted key tried to edit or delete | Use a full-access key |
| 403 | workspace_paused / workspace_suspended |
The workspace has been stopped | See the dashboard |
| 404 | not_found |
No such object in your workspace | Check the id |
| 409 | idempotency_in_progress |
The same Idempotency-Key is still being processed | Retry shortly (the SDK does this) |
| 422 | idempotency_key_reused |
The same key was sent with a different request | Use a new key |
| 429 | rate_limited |
Too many requests this minute | Wait for Retry-After (the SDK does this) |
| 429 | usage_limit_reached |
Your plan's limit is used up | Upgrade, free up capacity, or wait for the monthly reset. Don't retry. |
| 500 | internal_error |
Something failed on Oakstack's side | Retry (the SDK does this) |
API keys
Create keys at https://oakstack.dev/dashboard/api-keys. There are two kinds:
- Full access: everything. Use it for setup, scripts, and your coding agent.
- Restricted: for keys that live inside a running app. It can create, run, replay, and read, but can't edit or delete jobs and endpoints, and reads don't include signing secrets or stored job headers (you still get the secret once, when you create something). Editing or deleting with a Restricted key returns
403 restricted_api_key.
ok_test_ keys currently behave exactly like ok_live_ keys for scheduled jobs and webhooks. Test mode will matter for email: test keys won't deliver real messages.
Retries and idempotency
Send an Idempotency-Key header on any POST, PATCH, or DELETE. If you retry with the same key, you get the original response back instead of a second job or endpoint. Keys are remembered for 24 hours per workspace.
The SDK does this for you: every write gets a fresh key that's reused across its automatic retries. To make a write safe across process restarts too (for example, a setup script), pass your own key:
await oakstack.clock.jobs.create(params, { idempotencyKey: "setup-nightly-cleanup-v1" });
Plans and limits
Limits are hard caps. When you reach one, Oakstack stops with usage_limit_reached instead of charging you more.
| Free | Builder ($20/mo) | Studio ($49/mo) | |
|---|---|---|---|
| Scheduled jobs | 3 | 25 | 100 |
| Webhook endpoints | 5 | 50 | 200 |
| Most frequent schedule | every 5 minutes | every minute | every minute |
| Webhook events per month | 1,000 | 50,000 | 250,000 |
| PDFs per month | 25 | 1,000 | 5,000 |
| Pages read per month | 20 | 200 | 500 |
| Text segments per month | test mode only | 100 | 300 |
| Phone numbers (SMS) | none | 1 | 1 |
| Push notifications | 1,000 | 50,000 | 250,000 |
| Emails per month | 100 (live: to your own team only) | 10,000 | 50,000 |
| API requests per minute | 60 | 600 | 1,200 |
| Log retention | 7 days | 7 days | 30 days |
Add-ons (Builder and Studio, monthly, stack as many as you need) cover the two modules that cost per use: Reading pack (+1,000 pages, $25), SMS pack (+500 text segments, $10), Extra phone number ($5). Add or remove them on the dashboard's Billing page; adding is charged right away (prorated), removing ends it at once.
Monthly limits reset on the 1st (UTC). Each account can have one Free workspace; additional workspaces need a paid plan. Check usage any time:
const { plan, usage } = await oakstack.usage();
Every API response also carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. Dashboard actions share the same per-minute limit. A few actions have their own limits: "run now" at most once every 10 seconds per job, and each inbound webhook URL accepts up to 600 events a minute. Replays count as events.
Alert emails
Oakstack emails a workspace's owners and admins when something needs them: a scheduled job paused itself after 10 failed runs, webhook events failed after all retries (at most one email per endpoint per day), email or texting was paused, a phone number passed or failed carrier review, a push app's credentials were rejected, a payment failed, or a monthly limit reached 80% or 100%. Each email links to the right dashboard page. The last few alerts show on the dashboard's Overview, where they can also be turned off (they're still listed there).
What Oakstack will and won't call
Cron jobs and webhook forwarding only call public https:// URLs. Localhost, private networks, and cloud metadata addresses are refused, including hostnames that resolve to them. Redirects are not followed. Your endpoint should answer 2xx within 15 seconds; for longer work, answer 202 and continue in the background.
To test locally, expose your dev server with a tunnel (for example cloudflared tunnel or ngrok) and use its https URL.
More
- Scheduled jobs (clock)
- Webhook relay (hook)
- Verifying signatures
- Everything in one file: https://oakstack.dev/llms-full.txt