The Brainis API gives external tools programmatic access to your organization: read your records, and perform actions through the same governed pipeline the in-app AI uses.
Base URL: https://brainis.ai/api/v1
Get a key
Admin, API Keys. Create a key with the scopes it needs (read, write, or both) and copy it immediately: the full key is shown exactly once and stored only as a hash. Keys begin with br_live_.
Only owners and admins can create keys, and a key grants access to your whole organization within its scopes, so treat it like a password.
Your first request
curl "https://brainis.ai/api/v1/ping" \
-H "Authorization: Bearer br_live_YOUR_KEY"
This returns your organization id, the key name, and its scopes. If it works, everything else will.
Reading data
curl "https://brainis.ai/api/v1/tasks?limit=25&status=in_progress" \
-H "Authorization: Bearer br_live_YOUR_KEY"
Available resources include tasks, projects, deals, contacts, accounts, candidates, jobs, employees, invoices, agents, agent-runs, and deliverables. Responses are { data, next_cursor, has_more }; pass next_cursor back as cursor for the next page. Use updated_since for incremental syncs.
Reads are scoped to your organization and return an explicit column set. Employee reads deliberately exclude compensation and personal identifiers.
Making changes
Writes are not modeled as one endpoint per record type. Everything goes through a single actions endpoint with a verb:
curl -X POST "https://brainis.ai/api/v1/actions" \
-H "Authorization: Bearer br_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"verb": "create_task", "payload": {"title": "Follow up with Acme"}}'
GET /v1/verbs lists every available verb with its module, risk class, credit cost, required fields, and whether it always needs approval.
Governed like everything else
An API write runs the full pipeline: verb validation, risk scoring, your authority contract, credits, and the audit chain. Depending on your settings a call returns executed, or pending_approval when it needs a human, or denied with a reason. The API cannot do what your configured autonomy would not allow the AI to do.
Two flags make integration safe: dry_run: true returns the decision without doing anything, and an idempotency_key (or x-idempotency-key header) makes retries safe.
Limits
60 requests per minute per key by default, returning 429 with Retry-After when exceeded. Actions consume credits at the verb's listed cost.
Important: v1 does not include outbound webhooks, file upload, or per-user permissions for key callers. Poll with updated_since where you would otherwise want webhooks.