Quick Start

The Neocortex Web API lets you talk to your characters from any engine, language or platform over plain HTTP. Everything Neocortex SDKs do goes through these endpoints.

Requirements

A Neocortex account, sign up here
An API key, generate one in the dashboard
A character, create one here

Base URL

https://api.neocortex.link/v3

Every request sends your key in the x-api-key header. JSON requests also send Content-Type: application/json.

Sending your first message

Grab your key and character id

Copy an API key from API Keys, and a character id from the URL of any character in Characters.

You can also list your characters programmatically with GET /characters.

Call the chat endpoint

characterIds is an array, because one endpoint serves both a single character and a whole cast. One id is a normal single character conversation and works on any plan.

curl -X POST https://api.neocortex.link/v3/chat \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "characterIds": ["YOUR_CHARACTER_ID"],
    "message": "Hey, who are you and where am I?"
  }'

const res = await fetch('https://api.neocortex.link/v3/chat', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    characterIds: ['YOUR_CHARACTER_ID'],
    message: 'Hey, who are you and where am I?',
  }),
});

const data = await res.json();
console.log(data.messages[0].lines.map(l => l.text).join(' '));

import requests

res = requests.post(
    "https://api.neocortex.link/v3/chat",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "characterIds": ["YOUR_CHARACTER_ID"],
        "message": "Hey, who are you and where am I?",
    },
)

data = res.json()
print(" ".join(line["text"] for line in data["messages"][0]["lines"]))

Read the reply

{
  "sessionId": "RETURNED_SESSION_ID",
  "messages": [
    {
      "characterId": "cmrkiw4f100017k7sfnicq08e",
      "name": "Aria",
      "lines": [
        { "text": "You're at the edge of the Hollow.", "emotion": "CURIOUS" },
        { "text": "And I'd rather ask you the same thing.", "emotion": "CONFIDENT" }
      ],
      "actions": [],
      "flowState": ""
    }
  ],
  "metadata": []
}

Every reply is an ordered list of chat lines, each with its own emotion, so you can reveal them one at a time and drive an expression or a voice per line. Join their text for the whole reply.

Continue the conversation

Send the sessionId you got back with the next message and the character remembers the exchange. Omit it and you start a fresh conversation.

{
  "characterIds": ["YOUR_CHARACTER_ID"],
  "sessionId": "RETURNED_SESSION_ID",
  "message": "The Hollow? What happened there?"
}