AI Assistant

These endpoints power the Entu AI assistant. The flow has two steps: the chat endpoint returns the assistant's reply and, when it suggests changes, a proposal of write operations — nothing is applied yet. After the user confirms, the proposal's operations are passed unchanged to the execute endpoint, which applies them.

Both endpoints require a JWT token in the Authorization: Bearer <token> header and run with the calling user's rights — the assistant can only see and change what the user could see and change manually.

Chat

Sends the conversation to the assistant and returns its reply. The assistant can read the account's configuration and data, and propose (but never apply) write operations.

POST /api/{db}/ai/chat

Parameter	In	Description
db	path	Database name

Request body:

{
  "messages": [
    { "role": "user", "content": "Add birthyear property to person" }
  ]
}

Field	Description
messages	Conversation history, newest last — 1 to 40 messages. Each message has role (user or assistant) and content (max 8000 characters). Total content across all messages is limited to 100 000 characters.

Conversations are not stored on the server — send the full history with every request.

Response — assistant reply, optionally with proposed operations:

{
  "message": "I'll add a birthyear property to the person entity type.",
  "proposal": {
    "operations": [
      {
        "op": "add_property_definition",
        "tempId": "$1",
        "params": { "...": "..." },
        "description": "Add number property \"birthyear\" to entity type \"person\""
      }
    ]
  }
}

• message — assistant reply text
• proposal — present only when the assistant proposed write operations
• op — operation type, one of the types below
• tempId — temporary id ($1, $2, …) that later operations may reference, e.g. a new property definition pointing at an entity type created earlier in the same proposal
• params — operation parameters, generated by the assistant
• description — human-readable description, shown to the user for review

Operation types:

Op	Description
create_entity_type	Create a new entity type
add_property_definition	Add a property definition to an entity type
create_entity	Create a data entity
update_entity	Update a data entity's properties
delete_property	Delete a property value

Errors:

Status	Description
400	Invalid request body (missing, malformed, or over-limit messages)
402	Monthly AI token limit reached
403	Not authenticated
502	The AI service returned an error

Execute

Applies a confirmed proposal. Pass the operations array from the chat response unchanged — operations are re-validated and executed sequentially as the calling user.

POST /api/{db}/ai/execute

Parameter	In	Description
db	path	Database name

Request body:

{
  "operations": [
    {
      "op": "add_property_definition",
      "tempId": "$1",
      "params": { "...": "..." },
      "description": "Add number property \"birthyear\" to entity type \"person\""
    }
  ]
}

Field	Description
operations	Operations from the chat proposal — 1 to 25 items, executed in order

Response:

{
  "results": [
    { "tempId": "$1", "_id": "6798938432faaba00f8fc72f", "op": "add_property_definition" }
  ]
}

• results — successfully applied operations in order; _id is the affected entity's id (absent for delete_property)
• error — present when execution stopped at a failing operation: { index, statusCode, statusMessage }

WARNING

Execution stops at the first failure and already applied operations are not rolled back. When error is present, operations before error.index are applied, the operation at error.index failed, and the rest were skipped.

Errors:

Status	Description
400	Invalid operations array
403	Not authenticated