Fields & validation
Every field with its exact validation rule, nullability, and the database column that stores it.
Agent
| Field | In | Type | Required | Nullable | Rules (verbatim) | DB column |
|---|---|---|---|---|---|---|
name | body | string | create: yes · update: when present | no | create required|string|max:255 · update sometimes|required|string|max:255 | ai_projects.name |
description | body | string | no | yes | sometimes|nullable|string|max:5000 | ai_projects.description |
instructions | body | string | no | yes | sometimes|nullable|string|max:10000 | ai_projects.instructions |
memory | — | string | Read-only. Returned on the agent resource; a memory key in an update request is ignored. | ai_project_memories (managed by the platform) | ||
Constraints:
- Sending
null(or omitting on create) clears/leaves emptydescriptionandinstructions;namecan never be null or empty. DELETErequires ownership; a write-shared collaborator can edit but not delete.
Chat
| Field | In | Type | Required | Nullable | Rules (verbatim) | DB column |
|---|---|---|---|---|---|---|
model | body (create) | string | no | yes | sometimes|nullable|string|max:255 | ai_chats.model |
title | body (rename) | string | yes | no | required|string|max:255 | ai_chats.title (default New chat) |
Constraints: every chat operation (read, rename, delete, send) is limited to the token that created the chat — not even the agent owner can read another user’s thread through this API.
Message
| Field | In | Type | Required | Nullable | Rules (verbatim) | DB column |
|---|---|---|---|---|---|---|
content | body | string | yes | no | required|string|max:20000 | ai_chat_messages.content |
model | body | string | no | yes | sometimes|nullable|string|max:255 | ai_chat_messages.model |
Response fields: role is user or assistant (enum in the database); usage (prompt_tokens, completion_tokens, total_tokens) appears only on a freshly generated assistant reply.
Chat-completions request
| Field | Type | Required | Nullable | Rules (verbatim) |
|---|---|---|---|---|
model | string | no | yes | sometimes|nullable|string|max:255 |
messages | array | yes | no | required|array|min:1 — must include at least one user turn |
messages.*.role | string | yes | no | required|string|in:system,user,assistant |
messages.*.content | string | yes | no | required|string|max:20000 |
agent | string | no | yes | sometimes|nullable|string|max:64 |
chat | string | no | yes | sometimes|nullable|string|max:64 |
stream | boolean | no | no | sometimes|boolean — must be false; true returns 400 |
Knowledge file
| Field | In | Type | Required | Rules (verbatim) | DB column |
|---|---|---|---|---|---|
file | multipart | file | yes | required|file|max:20480 (20 MB) + extension allow-list | ai_project_files.path / original_name / mime / size |
Allowed extensions: txt, md, markdown, csv, json, log, text, pdf, doc, docx, rtf. Text extraction and indexing run only for txt, md, markdown, csv, json, log, text, capped at 200,000 characters; the other types are stored for reference.
Connector toggles
| Field | In | Type | Required | Rules (verbatim) | DB column |
|---|---|---|---|---|---|
enabled (connector) | body | boolean | yes | required|boolean | ai_project_mcp_connectors.is_enabled |
tool | body | string | yes | required|string|max:255 | ai_project_mcp_connectors.disabled_tools (JSON list of switched-off tool names) |
enabled (tool) | body | boolean | yes | required|boolean | ai_project_mcp_connectors.disabled_tools |
Constraint: a tool that is switched off is never offered to the model during a conversation.