Interactables

Two optional fields on POST /chat connect a character to your running game:

• metadata, what the character can perceive right now: the things around it and where they are.
• events, what has happened recently in the world.

Both are sent per request. Neocortex is stateless and stores no world state.

Perception

Send the entities the character can sense.

{
  "characterIds": ["cmrkiw4f100017k7sfnicq08e"],
  "message": "Go to the blue cube, then the red one.",
  "metadata": [
    {
      "id": "cube-blue",
      "name": "Blue Cube",
      "position": { "x": 3.0, "y": 0.0, "z": 1.5 },
      "properties": [
        { "name": "type", "value": "cube" },
        { "name": "color", "value": "blue" }
      ]
    },
    {
      "id": "cube-red",
      "name": "Red Cube",
      "position": { "x": -2.0, "y": 0.0, "z": 4.0 },
      "properties": [
        { "name": "type", "value": "cube" },
        { "name": "color", "value": "red" }
      ]
    }
  ]
}

Perceiving itself

Include an entity whose characterId matches the speaking character to define its own position and properties. Other entities' positions are evaluated relative to this coordinate. In group scenes, the entity list is shared and evaluated relative to the active speaker's coordinate.

Actions and targets

Actions come from the Action nodes you author on the character. Each triggered action carries the entity it applies to:

"actions": [
  { "name": "GO_TO", "targetId": "cube-blue" },
  { "name": "GO_TO", "targetId": "cube-red" }
]

A single response can include multiple actions. The targetId is empty ("") for actions that do not require a target.

If an entity has no id, an ID is automatically generated from its name. Using stable, unique IDs is recommended.

Response format

This is the shape you receive. Each action carries the id of the entity it applies to, and your entities come back once at the top level with isSubject marking whatever was targeted:

{
  "messages": [
    {
      "actions": [
        { "name": "GO_TO", "targetId": "cube-blue" }
      ]
    }
  ],
  "metadata": [
    { "id": "cube-blue", "name": "Blue Cube", "isSubject": true,  "...": "..." },
    { "id": "cube-red",  "name": "Red Cube",  "isSubject": false, "...": "..." }
  ]
}

The echo is built on the server from what you sent plus what the character targeted, so it always matches your input and can never invent an entry. For anything that moves, resolve the live object by targetId rather than trusting the echoed position.

Events

A log of recent events in the world.

"events": [
  { "priority": 2, "content": "The village was attacked at dawn.", "date": "2026-07-18T06:00:00Z" },
  { "priority": 1, "content": "A bridge on the north road collapsed." },
  { "priority": 0, "content": "A merchant arrived selling apples." }
]

Up to 20 events are processed per request, ordered by priority and timestamp.

Limits

Limits applied to payloads on the server:

It is recommended to filter entities (e.g., by distance) before sending them to the API.

Both fields accept a string

The metadata and events fields can be sent as a JSON array or as a serialized JSON string.