Overview

What this reference explains

An agent is a configurable AI assistant inside your Sulus account. It has a name, an optional description, persistent instructions (its system prompt), long-term memory, attached knowledge files, and optional connector tools it may call while answering.

This reference shows how the agent system works under the hood. Everything you do in the dashboard — creating an agent, chatting, uploading a file, switching a tool on or off — goes through the endpoints documented here. Each one lists its exact fields, which are required or nullable, the validation limits, the database columns behind them, and the precise error responses — so you can understand exactly what the system accepts, stores, and returns.

Where the system serves this API

All paths in this reference are relative to:

https://app.sulus.ai/api/v1

Response envelope

Successful responses are flat JSON objects with an object discriminator — there is no success key and no pagination key:

• Lists: {"object":"list","data":[ … ]} (messages additionally carry has_more)
• Single resources: {"object":"agent"|"chat"|"message"|"file","data":{ … }}
• Deletions: {"object":"agent.deleted","id":"…","deleted":true} (same pattern for chat.deleted, file.deleted)

Resource shapes are documented field-by-field on the Fields & validation page.

Pagination

List endpoints accept per_page (agents: default 50, max 100 · messages: default 30, max 100) but the list responses do not include page cursors.

For messages, page backwards through history with before_id: the response returns messages oldest → newest plus has_more; to fetch the previous (older) page, pass the id of the first message you received as before_id on the next request.

Feature availability

The Agents API is gated by the ai_chat feature on your account. When it is disabled, every endpoint returns 403:

{"message":"This feature is not enabled for your account. Please contact your administrator.","feature":"ai_chat"}

Core concepts and access rules

• Agent — identified everywhere by its id (a UUID). Reading requires view access; changing it requires edit access; deleting requires ownership.
• Chat — a conversation thread inside an agent. Chats are private to their creator: only the token that created a chat may read its messages, send to it, rename it, or delete it.
• Message — one turn in a chat, role user or assistant. Sending a message runs the full pipeline: connector tools, memory, knowledge retrieval, and prepaid-token billing.
• Files — reference documents attached to an agent. Text-based types are extracted and indexed for retrieval; other allowed types are stored for reference.
• Connectors — external tool servers the agent may call. Enable a connector per agent, then optionally switch individual tools off; a disabled tool is never offered to the model.
• Memory — readable on the agent resource. It is maintained by the platform during conversations and cannot be written through this API.
• Sharing — agents shared with you appear in your agent list with read or write access. Sharing management itself is dashboard-only; it is not part of this API.