API usage
Build on Billabled.
Use scoped workspace API keys to read and write work records, pull invoice proof, and monitor revenue risk without exposing billing, invites, or workspace administration.
Authentication
Send API keys as bearer tokens. Keys are generated in Settings - Developers and are shown once.
Authorization: Bearer $BILLABLED_API_KEYScoped access
Each endpoint checks a specific read or write scope. Missing scopes return 403.
Protected keys
Billabled stores a hash, prefix, creator, expiry, revoke status, and last-used timestamp, never the full secret value.
Usage tracking
Requests record endpoint, method, status, timestamp, key ID, user agent, and a safe IP hash.
API extends the workflow
Use the Billabled API after the work record is corrected: send proof packs to client systems, pull revenue intelligence into reviews, export work data, and listen for workflow events.
Native integrations
Connect Google Calendar, Slack, and QuickBooks in the app, then use API keys for long-tail systems.
Proof packs
Fetch client-ready invoice evidence for issued invoices and approval workflows.
Revenue intelligence
Read retainer risk, missing billable, and recovery summaries for operating reviews.
Exports
Pull CSV or JSON exports with integrity headers where supported.
Webhooks
Connect project, time, invoice, and approval events to agency systems.
Native app integrations
Use /integrations inside the authenticated app for Google Calendar sync, Slack alerts, and QuickBooks invoice push. OAuth routes stay session-authenticated and store provider credentials encrypted.
Example requests
export BILLABLED_API_KEY="blb_example_replace_me"
curl https://your-domain.com/api/v1/projects --oauth2-bearer "$BILLABLED_API_KEY"export BILLABLED_API_KEY="blb_example_replace_me"
curl "https://your-domain.com/api/v1/export?format=json&projectId=proj_123" --oauth2-bearer "$BILLABLED_API_KEY"Proof and revenue intelligence
Agency integrations can fetch invoice proof packs for client-facing evidence and revenue intelligence for retainer leak, missing billable, and recovery workflows. Proof-pack responses are designed for digest-backed invoice support; exports continue to include the x-billabled-export-sha256 integrity header.
export BILLABLED_API_KEY="blb_example_replace_me"
curl "https://your-domain.com/api/v1/proof-packs?invoiceId=inv_123" --oauth2-bearer "$BILLABLED_API_KEY"export BILLABLED_API_KEY="blb_example_replace_me"
curl "https://your-domain.com/api/v1/revenue-intelligence" --oauth2-bearer "$BILLABLED_API_KEY"Version 1 endpoints
| Method | Path | Use |
|---|---|---|
| GET | /api/v1/clients | Read clients |
| POST | /api/v1/clients | Create a client with write:clients |
| GET | /api/v1/projects | Read projects |
| POST | /api/v1/projects | Create a project with write:projects |
| GET | /api/v1/tags | Read workspace tags |
| GET | /api/v1/tasks | Read project tasks |
| GET | /api/v1/schedule | Read scheduled work |
| POST | /api/v1/schedule | Create scheduled work with write:schedule |
| GET | /api/v1/time-entries | Read time entries |
| POST | /api/v1/time-entries | Create completed work with write:time |
| GET | /api/v1/analytics | Read analytics summaries |
| GET | /api/v1/invoices | Read invoices |
| GET | /api/v1/proof-packs?invoiceId=... | Read invoice proof packs with read:proof-packs |
| GET | /api/v1/revenue-intelligence | Read retainer risk and recovery summaries with read:revenue-intelligence |
| GET | /api/v1/export | Download CSV or JSON exports with export:data |
Available scopes
What the API leaves in the app
Billing changes, user invites, subscription management, and workspace administration stay inside authenticated Billabled workflows.