Cortexa — The agent for research teams

Quickstart

If your app already uses an OpenAI SDK, point the base URL at Cortexa and use your Cortexa API key. The model name iscortexa.

curl https://api.cortexa.sh/v1/chat/completions \
  -H "Authorization: Bearer $CORTEXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cortexa",
    "messages": [
      {
        "role": "user",
        "content": "Summarize the evidence for GLP-1 agonists in neuroinflammation. Cite sources."
      }
    ]
  }'

from openai import OpenAI

client = OpenAI(
    api_key="sk-cortexa-live-...",
    base_url="https://api.cortexa.sh/v1",
)

response = client.chat.completions.create(
    model="cortexa",
    messages=[
        {
            "role": "user",
            "content": "Find recent clinical evidence for tau PET as an Alzheimer's endpoint.",
        }
    ],
)

print(response.choices[0].message.content)

Endpoint reference

Every endpoint on the v1 surface authenticates with the same bearer token and returns OpenAI-compatible error envelopes.

POST

/v1/chat/completionschat:completions

OpenAI-compatible chat completion endpoint. Best for existing SDKs and server-side integrations. Text messages only, streaming or not.

POST

/v1/agents/cortexa/runsagents:runs

Native streaming endpoint for text deltas, tool events, citations, and rich data cards. The only endpoint that can read an attached Library file.

GET

/v1/runs/{id}agents:runs

Fetch the completed messages, tool invocations, and stream of an earlier run by ID.

GET

/v1/modelsmodels:list

List available Cortexa models. Returns a single entry today; included for OpenAI client compatibility.

GET

/v1/toolstools:list

Inspect the verified tools the agent can route to per request.

GET

/v1/sourcestools:list

Browse the curated data source catalog the agent can reach.

POST

/mcp

MCP endpoint for clients that support streamable HTTP. Any valid key reaches it; see the MCP guide for host setup.

The tag next to each path is the key scope that endpoint requires. See Key scopes.

Streaming

Setstream: trueon a chat completion to receive server-sent events instead of one JSON body. OpenAI SDKs handle this for you; the raw shape is below if you are reading the stream yourself.

curl https://api.cortexa.sh/v1/chat/completions \
  -H "Authorization: Bearer $CORTEXA_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "cortexa",
    "messages": [
      {
        "role": "user",
        "content": "Which biomarkers predict response to checkpoint inhibitors?"
      }
    ],
    "stream": true
  }'

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Tumor mutational"},"finish_reason":null}]}

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":42,"completion_tokens":188,"total_tokens":230}}

data: [DONE]

Reading the stream

Text arrives in choices[0].delta.content. The last content frame carries finish_reason: "stop", followed by one frame with an empty choices array and the token usage for the whole request, then data: [DONE].

Failures after the stream opens

The response status is sent before the agent starts work, so a later failure cannot change it. When that happens Cortexa emits a frame carrying an error object with code stream_error, then closes with data: [DONE]. Check each frame for an error key rather than relying on the HTTP status alone.

Cortexa selects the tools

You send a question. Cortexa decides which research tools to call, calls them, and writes the answer with its citations. There is nothing to wire up on your side.

Do not send a tools array

Chat completions has no tools or tool_choice input. Sending one has no effect: unknown fields are accepted and ignored rather than rejected, so the request succeeds and your definitions are never reached. The same goes for sampling fields such as temperature, max_tokens, top_p, and stop. They keep existing SDK calls working and do not change the run.

Where you do get an error

Native runs are stricter about message content. A message part the endpoint cannot act on returns HTTP 400 with unsupported_part_type rather than being dropped, because a silently discarded attachment produces a confident answer about material the agent never saw.

Native streaming

Native runs stream the agent surface directly: text deltas, tool invocations, source-backed citations, structures, formulas, charts, and usage summaries.

curl https://api.cortexa.sh/v1/agents/cortexa/runs \
  -H "Authorization: Bearer $CORTEXA_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Compare evidence for two candidate targets and cite primary sources."
      }
    ]
  }'

1.8K+ verified tools behind one model

Cortexa handles tool selection internally. Client applications can stay simple while still benefiting from live literature, biomedical, clinical, genomics, chemistry, structure, patent, and code-execution tools.

Attaching files

A run can work from a file you already keep in your Library. Upload the file once in the Cortexa app, then point a native run at it by id.

curl https://api.cortexa.sh/v1/agents/cortexa/runs \
  -H "Authorization: Bearer $CORTEXA_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "messages": [
      {
        "role": "user",
        "parts": [
          { "type": "text", "text": "Summarize the methods section." },
          {
            "type": "data-library-file-ref",
            "data": { "id": "file_9c2f...", "name": "trial-protocol.pdf" }
          }
        ]
      }
    ]
  }'

What works

Native runs accept a data-library-file-refpart alongside your text. Cortexa resolves the id against the key owner's Library and the active workspace, then reads the file the way the app does. A file id the key cannot reach returns HTTP 404 with file_not_found, so you never get an answer written as though the file were included.

What does not exist yet

There is no upload endpoint for API keys. Files enter the Library through the Cortexa app, and your integration references them by id afterwards. Chat completions has no file input at all: it takes text messages only, so use native runs when a file is involved.

File ids are visible in your Library. See the Library guide for uploading and organizing them.

Authentication

Send API keys as bearer tokens:Authorization: Bearer sk-cortexa-live-.... Create and revoke keys from the API Keys dashboard.

Key scopes

Each key carries a set of scopes that decide which endpoints it can reach. Narrow a key to the capability one integration needs, and a leaked or misused key cannot do more than that.

chat:completions

Run the agent through the OpenAI-compatible chat endpoint, streaming or not.

/v1/chat/completions

agents:runs

Start a native agent run and fetch an earlier run back by id.

/v1/agents/cortexa/runs · /v1/runs/{id}

models:list

Read the model listing.

/v1/models

tools:list

Read the tool and data source catalogs.

/v1/tools · /v1/sources

connections:use

Let a run read the private connections the key owner has already been granted.

Calling an endpoint your key is not scoped for

Cortexa answers HTTP 403 and names the scope you are missing, so you can mint the right key without guessing. The envelope matches every other error on this surface.

HTTP/1.1 403 Forbidden

{
  "error": {
    "message": "This API key is missing the 'agents:runs' scope, which this endpoint requires. Create a key that includes it in Settings → API keys.",
    "type": "invalid_request_error",
    "code": "insufficient_scope",
    "param": null
  }
}

Choosing scopes

Keys created from the dashboard include everything except connections:use, which you opt into per key. Keys created before scopes existed keep working on the endpoints above and cannot reach private connections. Scopes are fixed when the key is created: to change them, create a new key and revoke the old one.

Credit charging & HTTP 402

API calls use the same account credit pool and overage cap as work started in the Cortexa app.

Model work is charged by actual usage

Successful model-producing requests debit credits from the account that owns the API key. Token volume, agent steps, and cache reads determine the charge; endpoint request counts are analytics, not the billing unit. Tool-only requests with no model usage do not consume model credits.

402 Payment Required

Cortexa returns HTTP 402 before starting model work when included credits are exhausted with no overage, the monthly overage cap is reached, the account's email is unverified, or the account's budget cannot be safely verified. Upgrade, raise the cap, verify your email, or update payment in Billing, then retry the request with the same application-level idempotency behavior.

curl https://api.cortexa.sh/v1/chat/completions \ -H "Authorization: Bearer $CORTEXA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "cortexa", "messages": [ { "role": "user", "content": "Summarize the evidence for GLP-1 agonists in neuroinflammation. Cite sources." } ] }'

from openai import OpenAI client = OpenAI( api_key="sk-cortexa-live-...", base_url="https://api.cortexa.sh/v1", ) response = client.chat.completions.create( model="cortexa", messages=[ { "role": "user", "content": "Find recent clinical evidence for tau PET as an Alzheimer's endpoint.", } ], ) print(response.choices[0].message.content)

curl https://api.cortexa.sh/v1/chat/completions \ -H "Authorization: Bearer $CORTEXA_API_KEY" \ -H "Content-Type: application/json" \ -N \ -d '{ "model": "cortexa", "messages": [ { "role": "user", "content": "Which biomarkers predict response to checkpoint inhibitors?" } ], "stream": true }'

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]} data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Tumor mutational"},"finish_reason":null}]} data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]} data: {"object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":42,"completion_tokens":188,"total_tokens":230}} data: [DONE]

curl https://api.cortexa.sh/v1/agents/cortexa/runs \ -H "Authorization: Bearer $CORTEXA_API_KEY" \ -H "Content-Type: application/json" \ -N \ -d '{ "messages": [ { "role": "user", "content": "Compare evidence for two candidate targets and cite primary sources." } ] }'

curl https://api.cortexa.sh/v1/agents/cortexa/runs \ -H "Authorization: Bearer $CORTEXA_API_KEY" \ -H "Content-Type: application/json" \ -N \ -d '{ "messages": [ { "role": "user", "parts": [ { "type": "text", "text": "Summarize the methods section." }, { "type": "data-library-file-ref", "data": { "id": "file_9c2f...", "name": "trial-protocol.pdf" } } ] } ] }'

HTTP/1.1 403 Forbidden { "error": { "message": "This API key is missing the 'agents:runs' scope, which this endpoint requires. Create a key that includes it in Settings → API keys.", "type": "invalid_request_error", "code": "insufficient_scope", "param": null } }

Developer API

Quickstart

Endpoint reference

Streaming

Cortexa selects the tools

Native streaming

Attaching files

Authentication

Key scopes

Credit charging & HTTP 402

Developer API

Quickstart

Endpoint reference

Streaming

Cortexa selects the tools

Native streaming

Attaching files

Authentication

Key scopes

Credit charging & HTTP 402