Nurama Developers
AI

Create a new (empty) AI chat topic.

Creates a `ChatAi` row plus its backing `Chat`. The topic is always empty — send the first message through `POST /v1/chats/{topic.chatId}/new-message`; `chat.service` detects `chatType === 'ai'` and fires the orchestrator (which runs the balance check). No credits are charged by this endpoint. The first user→assistant exchange triggers an auto-naming pass; the resulting title arrives via the `aiChatTopicUpdate` notification. Gate stack: `requireScopeAccess()` → active subscription → `ai` capability → `aiChatEnabled`.

POST
/ai/chat/topics

Creates a ChatAi row plus its backing Chat. The topic is always empty — send the first message through POST /v1/chats/{topic.chatId}/new-message; chat.service detects chatType === 'ai' and fires the orchestrator (which runs the balance check). No credits are charged by this endpoint.

The first user→assistant exchange triggers an auto-naming pass; the resulting title arrives via the aiChatTopicUpdate notification.

Gate stack: requireScopeAccess() → active subscription → ai capability → aiChatEnabled.

Authorization

AuthorizationBearer <token>

OAuth 2.1 authorization code flow with PKCE (required of every client, public or confidential). Scopes are a ceiling on the credential, not a grant of access: a token also cannot exceed what the user who approved it may already do. A write scope does not imply its matching read — ask for both.

In: header

Scope: ai:use

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/ai/chat/topics" \  -H "Content-Type: application/json" \  -d '{    "workspaceId": "0193e4a1-b2c3-7000-8000-000000000001",    "scopeType": "project",    "scopeId": "0193e4a1-b2c3-7000-8000-000000000aaa"  }'
{  "topic": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "chatType": "ai",    "scopeType": "workspace",    "scopeId": "65fafe40-a220-4dd7-8724-4598b81c0643",    "billedResourceType": "workspace",    "billedResourceId": "e4cc728d-50b5-41bd-80c9-0479f99d7ce7",    "creatorId": "688ebf54-d343-4104-8711-82c2feac534a",    "chatId": "f255124e-3419-4f6e-b7ee-17a6577db94d",    "title": "string",    "titleGenerationFailed": true,    "totalMessages": 0,    "totalBilledCredits": 0,    "lastMessagePreview": "string",    "lastMessageAt": "2019-08-24T14:15:22Z",    "contextItems": [      {        "type": "asset",        "id": "string"      }    ],    "archived": true,    "status": "active",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}