API Reference

The Neocortex Web API provides a set of HTTP endpoints that allow you to interact with Smart NPCs programmatically. This reference covers all available endpoints, including chat, session history, text-to-speech, and speech-to-text.

Endpoints

Method	URL	Description
`POST`	`/api/v2/chat`	Send a chat message to a character and receive it's reply.
`POST`	`/api/v2/chat/session`	Request message history of a chat session.
`POST`	`/api/v2/audio/generate`	Generate speech of a character.
`POST`	`/api/v2/audio/transcribe`	Transcribe audio into text.

Using your API Key

With each request do not forget to send your API Key with x-api-key header.

Headers x-api-key: YOUR_API_KEY

Chat with a character

Sends a message to a Smart NPC and receives a response.

POST https://neocortex.link/api/v2/chat

Headers Content-Type: application/json

{
  "sessionId" : "",                             // Optional: If you want to continue from existing chat
  "characterId": "cm9qurmiq0001l503rapmxln6",   // Required: Your project (character) ID
  "message": "Hey there!"                       // Required: Message to send to the NPC
}

{
    "sessionId": "cmdruuvyr0000jr04lteh35te",
    "response": "Good evening. What can I get you tonight?",
    "action": "",
    "emotion": "NEUTRAL"
}

Get past messages

Retrieves past chat sessions and messages for a specific character.

POST https://neocortex.link/api/v2/chat/session

Headers Content-Type: application/json

{
  "sessionId" : "cmdruuvyr0000jr04lteh35te",  // Required: If you want to continue from existing chat
  "limit": 10                                 // Optional: Number of past messages to fetch. Default 10
}

{
  "sessionId": "cmdruuvyr0000jr04lteh35te",
  "messages": [
    {
      "content": "Hey there!",
      "sender": "USER",
      "createdAt": "2025-07-31T20:36:36.845Z"
    },
    {
      "content": "Good evening. What can I get you tonight?",
      "sender": "ASSISTANT",
      "createdAt": "2025-07-31T20:36:38.138Z"
    }
  ]
}

Generate speech

Generates speech from a text input using the character's configured voice.

POST https://neocortex.link/api/v2/audio/generate

Headers Content-Type: application/json

{
    "characterId": "cmdivwjpz00357kngoxn0b97t",   // Required: Your project (character) ID
    "message": "This is all I can tell you."      // Required: Text to convert to speech
}

Binary audio data

Transcribe audio

POST https://neocortex.link/api/v2/audio/transcribe

Headers Content-Type: multipart/form-data

Key	Value
audio	audio_file.wav
characterId	cmdivwjpz00357kngoxn0b97t

{
    "response": "Hey, how are you doing today?"
}