The API
Everything the browser can do, over HTTP: start a company, run a shift, read the report, pull the receipts, stop everything.
It is included. There is no API plan.
The API costs the same as the browser, because it does the same thing — a shift is a shift whether you asked for it by clicking or over HTTP. Your plan includes the work either way, and every action is itemised on a receipt. Charging a second time for the same night's work, because you used a different door, would be a fee with nothing behind it.
Authentication
A bearer token, from your account page. Never send it in a query string — query strings end up in access logs, browser history and referrer headers.
curl https://firstemployee.ai/api/v1/me/ \ -H "Authorization: Bearer $FIRSTEMPLOYEE_TOKEN"
Start a company
curl -X POST https://firstemployee.ai/api/v1/companies/ \
-H "Authorization: Bearer $FIRSTEMPLOYEE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"brief": "A directory of dog-friendly cafes in Bristol"}'Run a shift
Returns 202 and queues the work. A shift takes minutes, so poll the shift endpoint rather than holding the connection open — or pass "wait": true if you would rather block.
curl -X POST https://firstemployee.ai/api/v1/companies/bristol-cafes/shifts/ \ -H "Authorization: Bearer $FIRSTEMPLOYEE_TOKEN"
Endpoints
| method | path | what it does |
|---|---|---|
| GET | /api/v1/me/ | Who the token belongs to |
| GET | /api/v1/spend/ | Ceiling, spent, remaining |
| POST | /api/v1/stop/ | Kill switch — pause every company at once |
| GET POST | /api/v1/companies/ | List, or start one |
| GET PATCH DELETE | /api/v1/companies/{slug}/ | Read, edit, or delete with its data |
| GET POST | /api/v1/companies/{slug}/shifts/ | History, or run one now |
| GET | /api/v1/companies/{slug}/shifts/{n}/ | One shift and its report |
| POST | /api/v1/companies/{slug}/shifts/{n}/answer/ | Answer the one question |
| GET | /api/v1/companies/{slug}/receipts/ | Every action, model and cost |
| GET | /api/v1/companies/{slug}/artifacts/ | The pages and documents it produced |
| GET DELETE | /api/v1/companies/{slug}/artifacts/{path} | One page, with its body and lint result |
| GET | /api/v1/companies/{slug}/payments/ | Whether this company can take money, and through whose account |
| GET | /api/v1/approvals/ | Everything waiting on a human, across every company |
| GET POST | /api/v1/approvals/{id}/ | Read one, or approve/reject it |
| GET PATCH | /api/v1/spend/ | Read the internal work budget (advanced) |
| POST | /api/v1/token/rotate/ | Rotate this token — the old one stops immediately |
The receipts endpoint is the point
An autonomous agent you cannot audit is not something to wire into your systems. Every action a shift takes is returned in order, with the tool, the result, the model, the token counts and the cost in cents — including the actions it held for approval and did not take. Filter with ?held=1, ?tool=publish_page or ?shift=3.
Approvals are the endpoint that matters most
Your employee stops before anything irreversible — sending mail, posting in public, starting an ad, charging a customer. Poll /approvals/ and you will find the draft, in full, with everything you need to decide. Approving carries it out and writes a new receipt; rejecting is recorded too, because deciding not to is also evidence. Nothing can be decided twice, and anything left waiting for fourteen days expires rather than firing later against facts that have moved.
curl -X POST https://firstemployee.ai/api/v1/approvals/42/ \
-H "Authorization: Bearer $FIRSTEMPLOYEE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"decision": "approve"}'Errors
JSON, always, with a stable code you can branch on. 402 means this period's included work is used up and no shift will start — that is a deliberate stop, not a failure.
{"error": {"code": "spend_ceiling_reached", "message": "…", "spend": {…}}}