Database reference
The exact tables and columns the Agents API reads and writes.
Identity mapping
The public id of an agent, chat, or connector is the uid column (a UUID), never the numeric primary key. Files are the exception: their public id is the numeric ai_project_files.id.
ai_projects (agents)
| Column | Type | Nullable | Notes |
|---|
uid | char(36) | yes | The public agent id |
name | varchar(255) | no | Display name |
description | text | yes | Optional description |
instructions | longtext | yes | Persistent system prompt |
last_activity_at | timestamp | yes | Bumped on conversation activity |
is_public | tinyint(1) | no (default 0) | Globally shared read-only flag; managed from the dashboard, read-only here |
created_at / updated_at | timestamp | yes | |
ai_chats (chats)
| Column | Type | Nullable | Notes |
|---|
uid | char(36) | yes | The public chat id |
title | varchar(255) | no (default New chat) | Renameable |
model | varchar(255) | yes | Model id chosen for the thread |
provider | varchar(255) | no | Model provider identifier (informational) |
last_message_at | timestamp | yes | |
ai_chat_messages (messages)
| Column | Type | Nullable | Notes |
|---|
id | bigint unsigned | no | The public message id; also the before_id cursor |
role | enum(user,assistant) | no | |
content | longtext | no | Max 20,000 characters at the API boundary |
model | varchar(255) | yes | |
prompt_tokens / completion_tokens / total_tokens | int unsigned | no (default 0) | Billing counters; surfaced as usage on fresh replies |
ai_project_files (knowledge files)
| Column | Type | Nullable | Notes |
|---|
id | bigint unsigned | no | The public file id |
original_name | varchar(255) | no | As uploaded |
mime | varchar(255) | yes | |
size | bigint unsigned | no (default 0) | Bytes |
vector_count | int unsigned | no (default 0) | > 0 means indexed for retrieval |
ai_mcp_connectors + ai_project_mcp_connectors
ai_mcp_connectors (the connector registry — only API-exposed columns listed):
| Column | Type | Nullable | Notes |
|---|
uid | char(36) | no | The public connector id |
name | varchar(255) | no | |
description | text | yes | |
server_url | varchar(255) | no | The connector’s tool-server endpoint |
tools_count | int unsigned | no (default 0) | |
is_active | tinyint(1) | no (default 1) | Inactive connectors are never offered |
ai_project_mcp_connectors (per-agent state):
| Column | Type | Nullable | Notes |
|---|
is_enabled | tinyint(1) | no (default 1) | Written by the connector toggle |
disabled_tools | json | yes | List of tool names switched off for this agent |
