Chats

Endpoints for creating and managing AI chat conversations.

GET /api/chats

Get a paginated list of chats ordered by pinned status and last update time.

Authentication: Required (session)

Query Parameters:

Parameter	Type	Default	Description
limit	integer	20	Number of results per page
offset	integer	0	Pagination offset

Response:

{
  "total": 150,
  "limit": 20,
  "offset": 0,
  "results": [
    {
      "id": "abc123",
      "name": "Product Analysis",
      "autoRename": true,
      "stale": false,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T14:22:00Z",
      "modelId": "model-123",
      "tier": "advanced",
      "ownerAssistantId": null,
      "primaryAssistantId": "asst-456",
      "web": false,
      "directory": "reports",
      "outputSize": "medium",
      "pinned": true
    }
  ]
}

---

POST /api/chats

Create a new chat conversation with optional initial messages and associations.

Authentication: Required (session)

Request Body:

Field	Type	Required	Description
name	string	No	Chat name (null for auto-generated)
modelId	string	Yes	Model ID to use for chat
tier	string	No	Model tier: everyday, advanced, strategic
ownerAssistantId	string	No	Assistant that owns this chat
primaryAssistantId	string	No	Primary assistant for the chat
assistantIds	array	No	Array of assistant IDs to associate
datasetIds	array	No	Array of dataset IDs to associate
libraryIds	array	No	Array of library IDs to associate
instructions	string	No	Custom instructions for the chat
messages	array	No	Initial messages (defaults to empty)
web	boolean	No	Enable web access (default: false)
helpCenter	boolean	No	Enable help center (default: false)
magicReport	boolean	No	Enable App (default: false)
pinned	boolean	No	Pin chat to top (default: false)
directory	string	No	Directory path for organization
outputSize	string	No	Output size: small, medium, large (default: medium)

Example Request:

{
  "name": "Sales Analysis",
  "modelId": "claude-opus-4",
  "tier": "advanced",
  "assistantIds": ["asst-123"],
  "datasetIds": ["ds-456"],
  "messages": [],
  "web": false,
  "outputSize": "medium"
}

Response:

Returns the created chat object with associated IDs.

---

GET /api/chats-list

Get a simple list of all chats ordered by update time (legacy compatibility endpoint).

Authentication: Required (session)

Response:

Array of chat objects without pagination.

---

GET /api/chats/{id}

Retrieve a specific chat with full details including attachments, assistants, datasets, and memory summaries.

Authentication: Required (session)

Pre-blocks: chat.lookupForUi

Response:

{
  "id": "abc123",
  "name": "Product Analysis",
  "instructions": "Focus on quarterly metrics",
  "modelId": "claude-opus-4",
  "model": {
    "id": "claude-opus-4",
    "name": "Claude Opus 4",
    "tier": "strategic"
  },
  "assistantIds": ["asst-123", "asst-456"],
  "datasetIds": ["ds-789"],
  "libraryIds": ["lib-012"],
  "messages": [],
  "memories": [
    {
      "id": "mem-345",
      "summary": "Discussed Q4 revenue targets",
      "messageCount": 12
    }
  ],
  "attachments": [
    {
      "id": "file-678",
      "filename": "report.pdf",
      "size": 102400
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T14:22:00Z",
  "_links": {
    "inf:messages": { "href": "/api/chats/abc123/messages" },
    "inf:chat-schedule": { "href": "/api/chats/abc123/schedule" }
  }
}

---

PUT /api/chats/{id}

Update chat properties and associations.

Authentication: Required (session)

Pre-blocks: chat.lookup

Request Body:

Field	Type	Description
name	string	Chat name
instructions	string	Custom instructions
modelId	string	Change model
assistantIds	array	Replace assistant associations
datasetIds	array	Replace dataset associations
libraryIds	array	Replace library associations
primaryAssistantId	string	Set primary assistant
ownerAssistantId	string	Set owner assistant
autoRename	boolean	Enable auto-renaming
autoRenamedAt	date	Last auto-rename timestamp
autosuggest	boolean	Enable auto-suggestions
stale	boolean	Mark as stale
web	boolean	Enable web access
helpCenter	boolean	Enable help center
magicReport	boolean	Enable App
pinned	boolean	Pin to top
directory	string	Organization directory
outputSize	string	small, medium, or large

Response:

Returns the updated chat object.

Transaction Support

This endpoint uses database transactions to ensure consistency when updating multiple associations.

---

DELETE /api/chats/{id}

Delete a chat conversation and all associated messages.

Authentication: Required (session)

Response:

204 No Content

---

POST /api/chats/{id}

Send a message to a chat and receive a streaming AI response.

Authentication: Required (AI access)

Metering: Consumes credits subject to the caller's usage profile (skipped under BYOK).

Pre-blocks:

• chat.lookupForSubmission
• Model resolution
• Credit enforcement (model tier access + credit limits)

Request Body:

Field	Type	Required	Description
message	object	Yes	Message object with content
fileIds	array	No	Array of file IDs to attach
uploadIds	array	No	Array of upload IDs to process
tools	object	No	Tool configuration
functions	array	No	Function names to enable
toolkitIds	array	No	Additional toolkit IDs
system	string	No	System prompt override

Payload Limit: 200MB (209715200 bytes)

Response:

Server-Sent Events (SSE) stream with Content-Type: text/event-stream

Stream Events:

event: message-start
data: {"id":"msg-123","role":"assistant"}

event: content-delta
data: {"delta":"Here is my response..."}

event: tool-use
data: {"toolName":"search","args":{...}}

event: message-complete
data: {"id":"msg-123","cost":0.0042}

Error Handling:

• 402 - Insufficient credits (see the code field; e.g. CREDIT_LIMIT, BUDGET_EXHAUSTED, HARD_CUTOFF)
• 400 - Invalid model or payload
• Connection closed on abort signal

Credit Enforcement

This endpoint runs the credit enforcer before processing. Requests that exceed the caller's profile cap, an entity budget, or the credit pool return 402 Payment Required with a machine-readable code. See the enforcement flow.

---

POST /api/chats/{id}/attachments

Upload a file attachment to a chat with optional embedding generation.

Authentication: Required (session)

Pre-blocks: chat.lookup, upload validation

Request Body:

Field	Type	Required	Description
uploadId	string	Yes	Upload ID from file upload
progress	number	No	Upload progress tracking

Response:

{
  "id": "file-789",
  "filename": "document.pdf",
  "size": 204800,
  "uploadId": "upload-123",
  "embedded": true,
  "createdAt": "2024-01-15T15:30:00Z"
}

---

POST /api/chats/{id}/messages/{messageId}/_explain

Generate an explanation for a specific message in the chat.

Authentication: Required (session)

Pre-blocks: Message and chat lookup

Response:

Server-Sent Events (SSE) stream explaining the message generation process.

---

POST /api/chats/{id}/_summarize

Create memory summaries from chat messages in configurable segments.

Authentication: Required (session)

Pre-blocks: chat.lookup

Request Body:

Field	Type	Default	Description
segmentSize	integer	20	Number of messages per segment

Response:

{
  "memoriesCreated": 3,
  "messagesCovered": 60,
  "segments": [
    {
      "memoryId": "mem-123",
      "messageCount": 20,
      "summary": "Initial project setup discussion"
    }
  ]
}

---

GET /api/chat-models

List models available for chat, filtered for specific use cases.

Authentication: Required (session)

Response:

{
  "_links": {
    "self": { "href": "/api/chat-models" }
  },
  "_embedded": {
    "inf:model": [
      {
        "id": "claude-opus-4",
        "name": "Claude Opus 4",
        "slug": "claude-opus-4",
        "tier": "strategic",
        "chat": true,
        "provider": {
          "id": "anthropic",
          "name": "Anthropic"
        },
        "promptPpm": 15.0,
        "completionPpm": 75.0,
        "contextWindow": 200000
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 1
}

Filtering:

• Excludes deprecated models
• Excludes internal models
• Resolves GO tier aliases (go_everyday, go_advanced, go_strategic)
• Includes prompt-caching cost adjustments

---

GET /api/chats/{id}/files/{fileId}/{filename}

Retrieve file contents from a chat attachment.

Authentication: Required (session)

Pre-blocks: ai.verify, file lookup (attachment role only)

Path Parameters:

Parameter	Type	Description
id	string	Chat ID
fileId	string	File ID
filename	string	Original filename

Response:

File contents with appropriate Content-Type header.

Authorization:

Validates that the requesting user owns the chat containing the file.

---

GET /api/chats/{id}/images/{fileId}

Retrieve an image file from a chat.

Authentication: Required (session)

Path Parameters:

Parameter	Type	Description
id	string	Chat ID
fileId	string	Image file ID

Response:

Image file contents with appropriate Content-Type header.

Authorization:

Validates chat ownership before returning image.