The REST API v1 by example: personal keys, curl and real errors
We've written about why we document every API. This is the practical side: a walkthrough of zerosoft's REST API v1 with copy-pasteable curl commands for Link and the CRM, plus the errors you'll actually hit.
Everything here was checked against the route handlers in app/api/v1, not just the docs page. The base URL is https://zerosoft.ai/api/v1 on zerosoft Cloud, or https://your-host/api/v1 if you self-host.
Get a key
Go to Dashboard → Settings → API keys, give the key a name ("CI deploy", "zapier-replacement", whatever), and create it.
Three things to know:
- It's shown once. The key looks like
zs_followed by 32 random characters. We store only its SHA-256 hash and the first 10 characters as a visible prefix. Lose it and you make a new one. - It acts as the workspace. Records created through the API land in the same workspace you see in the dashboard. Admins see every key in the workspace; members see only the ones they created. The list shows when each key was last used, and revoking takes effect on the next request.
- 100 requests per minute, per key. More on that below.
Put it in an environment variable and stop thinking about it:
export ZS_KEY="zs_..."
export ZS="https://zerosoft.ai/api/v1"
Links
Create a short link. Only url is required; slug (up to 32 characters), title, tags (up to 5) and domain (a custom domain you've verified) are optional.
curl -X POST "$ZS/links" \
-H "Authorization: Bearer $ZS_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/spring-launch", "slug": "spring", "tags": ["launch"]}'
You get a 201 with id, slug, domain, short_url, url, title, tags and created_at.
List them, paginated (pageSize maxes out at 50):
curl "$ZS/links?page=1&pageSize=50" -H "Authorization: Bearer $ZS_KEY"
The response is { "links": [...], "total": n }, archived links included, each with its click count.
Clicks per day for the last 30 days:
curl "$ZS/links/LINK_ID/stats" -H "Authorization: Bearer $ZS_KEY"
# { "slug": "spring", "total": 312, "byDay": [{ "date": "...", "count": 41 }, ...] }
That's enough to build a weekly report in a cron job without ever opening the dashboard.
CRM: contacts
Search and paginate (pageSize up to 100):
curl "$ZS/crm/contacts?q=ana&page=1&pageSize=25" -H "Authorization: Bearer $ZS_KEY"
Create one. Note that request bodies use camelCase field names, while responses return the stored row with snake_case columns:
curl -X POST "$ZS/crm/contacts" \
-H "Authorization: Bearer $ZS_KEY" \
-H "Content-Type: application/json" \
-d '{"firstName": "Ana", "lastName": "Garcia", "email": "ana@example.com", "lifecycleStage": "lead", "source": "event"}'
# 201 → { "id": "...", "first_name": "Ana", "last_name": "Garcia", "lifecycle_stage": "lead", ... }
Update with PATCH: every field is optional:
curl -X PATCH "$ZS/crm/contacts/CONTACT_ID" \
-H "Authorization: Bearer $ZS_KEY" \
-H "Content-Type: application/json" \
-d '{"jobTitle": "Head of Ops", "city": "Montevideo"}'
Companies work the same way at /crm/companies and /crm/companies/:id.
CRM: deals and tasks
Deals need a pipeline and a stage, so ask for those first:
curl "$ZS/crm/pipelines" -H "Authorization: Bearer $ZS_KEY"
Each pipeline comes with its stages (id, name, probability, isWon, isLost). Then:
curl -X POST "$ZS/crm/deals" \
-H "Authorization: Bearer $ZS_KEY" \
-H "Content-Type: application/json" \
-d '{"pipelineId": "PIPELINE_ID", "stageId": "STAGE_ID", "name": "Acme renewal", "amount": 4800, "currency": "USD", "contactIds": ["CONTACT_ID"]}'
GET /crm/deals lists deals for ?pipelineId=…, or for your first pipeline if you omit it.
Tasks hang off contacts, companies or deals:
curl -X POST "$ZS/crm/tasks" \
-H "Authorization: Bearer $ZS_KEY" \
-H "Content-Type: application/json" \
-d '{"subject": "Send renewal proposal", "dueAt": "2026-08-20 15:00", "dealId": "DEAL_ID"}'
curl "$ZS/crm/tasks?bucket=overdue" -H "Authorization: Bearer $ZS_KEY"
bucket accepts overdue, today, upcoming or done. Dates use YYYY-MM-DD, optionally followed by a time.
There are also Cal endpoints (event types, bookings, cancel) under /calendar: the docs have them.
Errors: one shape for everything
Every v1 error has the same body:
{ "error": { "code": "slug_taken", "message": "That slug is already taken." } }
Branch on code, show message to humans. The ones you'll meet:
| Status | Code | When |
|---|---|---|
| 401 | invalid_key |
Missing Authorization: Bearer … header, or the key is wrong or revoked. |
| 429 | rate_limited |
More than 100 requests in the current minute for this key. |
| 400 | invalid_url, invalid_slug, slug_taken, invalid_domain |
Link creation problems. |
| 400 | invalid_input, invalid_email, missing_name |
The CRM body didn't validate. |
| 400 | invalid_pipeline, invalid_stage |
The pipeline doesn't exist, or the stage isn't in it. |
| 404 | not_found |
The record doesn't exist in your workspace. |
About that rate limit
The limit is a fixed one-minute window per key, counted in the database (we wrote a whole post about how). Two details worth knowing:
- It's counted before the key is validated. Brute-forcing keys burns the same budget. Invalid keys are also capped at 20 attempts per minute per IP.
- The 429 has no
Retry-Afterheader. Windows align to the clock minute, so the simplest correct client sleeps until the next minute starts and retries.
# naive but correct
until curl -fsS "$ZS/links" -H "Authorization: Bearer $ZS_KEY"; do sleep 15; done
For bulk imports, pace yourself at well under 100 per minute and you'll never see a 429.
What's not there (yet)
Being honest about the edges: there's no public API for Track or Chat yet, and there's no OAuth for third-party apps: keys are personal. If the dashboard can do something the API can't, that's a gap, not a design choice. Open an issue.