DEVELOPER DOCS
Build on a Cortex
Quick start
- Sign in and mint a key on Activate. It starts with
cx_and is shown once. - Keep it in your shell, never in a chat window:
export CORTEX_API_KEY='cx_...' - Ask your clone something.
curl -X POST https://makecortex.com/<username>/api/query \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CORTEX_API_KEY" \
-d '{ "ask": "What would you push back on in this launch plan?" }'Replace <username> with the Cortex handle, the part after the domain in its public URL.
Authentication
Send the key as a bearer token: Authorization: Bearer cx_.... No other header is read.
- Owner keys work on the owner's own Cortex over REST and MCP.
- Organization teammates can use their own key against a teammate's Cortex in the same organization.
- REST needs the profile to be public. MCP works on a private profile, because it always runs on a key.
- Only a hash of each key is stored, so a lost key cannot be shown again; mint a new one. An account can hold up to 20 keys. Keys do not expire. To revoke one, email aashwin@makecortex.com.
Without a key, the REST endpoints only answer a browser that has passed the anti-bot check on the public clone page. Scripts and agents should always send a key.
Rate limits
| LIMIT | VALUE | APPLIES TO |
|---|---|---|
| Per IP, text | 10 requests per minute | REST query and stream. Skipped when the owner’s own key is used. |
| Per IP, voice | 4 requests per minute | Voice replies. |
| Per Cortex, per day | Individual: 500. Concierge: 10,000. | All text queries to that Cortex, from anyone, including MCP query_person and get_expertise_on. |
Over a limit, REST returns 429 with a Retry-After header in seconds (60 for the per-minute limit, 86400 for the daily one):
HTTP/1.1 429 Too Many Requests
Retry-After: 60
{ "error": "Too many requests from this IP. Please wait and try again.", "limitReached": true, "retryAfter": 60 }MCP reports the same limits as a JSON-RPC error with code -32002 and data.retryAfter. See MCP.
Plans and monthly usage
What a Cortex can be queried through depends on its owner's plan. If the plan does not include a surface, the call returns 402 with "code": "plan_required" and the tier that unlocks it. See pricing for what each plan includes.
{ "error": "REST queries require a Pro or Concierge plan.", "code": "plan_required", "requiredTier": "pro" }Each plan also carries a monthly usage allowance. As an account nears it, answers move to a faster, lighter model chain so the clone keeps answering, and the allowance resets on the 1st of each month (UTC). Treat a 402 from any endpoint as "this Cortex cannot answer right now, tell its owner", not as something to retry in a loop.
Errors
Errors are JSON with an error message, and a machine-readable code where one exists.
| STATUS | CODE | MEANING |
|---|---|---|
| 400 | Malformed JSON, a missing ask, or an invalid image. | |
| 401 | public_access_denied | No key and no browser check. Send Authorization: Bearer cx_... |
| 401 | owner_api_key_required | Only the owner’s own key is accepted on this endpoint right now. |
| 402 | plan_required | The owner’s plan does not include this surface. requiredTier says which does. |
| 404 | The profile does not exist or is not public. Shown only to authenticated callers; anonymous callers get the same 401 for both. | |
| 429 | Rate limited. Wait Retry-After seconds. | |
| 503 | Model capacity is busy. Retry after a few seconds with backoff. | |
| 500 | Server error while answering. Retry once, then contact us. |
CORS
The API does not send CORS headers, so it cannot be called from another site's browser JavaScript. Call it from a server, a script or an agent, where your key stays private.
Help
Email aashwin@makecortex.com. A person reads every message.