BACK TO CORTEX

DEVELOPER DOCS

REST API

Plain HTTPS and JSON. Every request needs Authorization: Bearer cx_... (see authentication) and the profile must be public. Base URL: https://makecortex.com.

Ask a question

POST /{username}/api/query

FIELDTYPENOTES
askstringThe question. Required unless you send images. question is accepted as an alias.
contextstringOptional. Background the clone should take into account.
conversationHistoryarrayOptional. [{ "role": "user" | "assistant", "content": "..." }]. The last 10 turns are used.
querierContextobjectOptional. { "type": "ai" | "human", "identity": "..." }. Tells the clone who is asking; identity is cut to 200 characters.
imagesarrayOptional. Up to 3 images, each under 4 MB, JPEG, PNG, WebP or GIF, as { "mimeType", "data" (base64) } or { "url": "data:..." }.
REQUEST
curl -X POST https://makecortex.com/<username>/api/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CORTEX_API_KEY" \
  -d '{
    "ask": "I am choosing between two engineer candidates. What would you push back on in my thinking?",
    "context": "seed-stage startup, first 10 hires, speed matters but cultural drift is expensive",
    "querierContext": { "type": "ai", "identity": "Claude helping with a hiring decision" }
  }'
RESPONSE
{
  "profile": "cortex://<username>",
  "voice": "direct, editorial, slightly contrarian",
  "response": "Don't optimize for scale first. Hire someone who...",
  "confidence": 0.87,
  "sources": [{ "concept": "Hiring philosophy", "excerpt": "..." }],
  "queried_at": "2026-10-15T10:00:00.000Z",
  "mode": "full_text_path",
  "models": ["..."],
  "limitReached": false,
  "retrieval_degraded": false
}
  • response is the answer, in the person's voice.
  • sources are the parts of their brain it drew on; each excerpt is cut to about 120 characters.
  • mode is lightweight_fast_path for short conversational turns, otherwise full_text_path.
  • retrieval_degraded is true when part of the memory search failed and the answer was built from less than usual.

Stream the answer

POST /{username}/api/query/stream takes the same body and returns server-sent events (text/event-stream). Each frame is event: <name> plus a JSON data: line. A : ping comment arrives every 12 seconds to keep the connection open.

EVENTDATAWHEN
status{ "state": "thinking" | "checking_memory" | "answering", "label" }Progress, before and while answering.
delta{ "text" }The next piece of the answer. Append in order.
sources{ "sources": [{ "concept", "excerpt" }] }What the answer drew on.
done{ "response", "limitReached", "mode", "models", "metrics": { "firstTokenMs", "responseMs" } }Last event. response is the full answer.
error{ "message" }The stream failed part way. Keep what you have, or retry.
REQUEST
curl -N -X POST https://makecortex.com/<username>/api/query/stream \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CORTEX_API_KEY" \
  -d '{ "ask": "How do you decide when to ship something unfinished?" }'
STREAM
event: status
data: {"state":"thinking","label":"Thinking..."}

event: delta
data: {"text":"Ship it when "}

event: delta
data: {"text":"the thing you are unsure about can only be learned from users."}

event: done
data: {"response":"Ship it when the thing you are unsure about can only be learned from users.","limitReached":false,"mode":"full_text_stream_path","models":["..."],"metrics":{"firstTokenMs":900,"responseMs":4200}}

Errors that happen before the stream starts (auth, plan, rate limit, bad body) come back as ordinary JSON with the status codes on the overview.

Other endpoints

Voice reply

POST /{username}/api/voice with ask (plus optional context and conversationHistory) returns audio/mpeg in the person's voice. The answer text is in the X-Clone-Text header, URI-encoded and cut to 1000 characters. Needs a plan with voice; limited to 4 requests per minute per IP.

curl -X POST https://makecortex.com/<username>/api/voice \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CORTEX_API_KEY" \
  -d '{ "ask": "Introduce yourself in two sentences." }' \
  --output reply.mp3

Feedback on an answer

POST /{username}/api/review with rating (1 to 5, required) and optionally originalQuestion, originalResponse, whatWouldBeBetter and correctAnswer. The owner sees it and can fold corrections into their brain. Limited to 8 per minute per IP.

Practical notes

  • Send conversationHistory yourself for multi-turn conversations; each request is otherwise independent.
  • Set querierContext.type to ai when an agent is asking. The clone answers an agent differently from a person.
  • Back off on 429 and 503. Never retry 401 or 402 without changing something.
  • Building an agent? MCP gives it the same clone as tools, with no HTTP code to write.

Pricing · Trust · Contact · Terms · Privacy

v-27c86ea