AI

Kolony AI analyses published media and lets users talk to that knowledge.

After an image, video, or audio file is published, the platform analyses it in the background:

Published file	What AI writes
Image	Identifying metadata tags plus an English visual description
Video	Identifying metadata tags (including timed / per-frame) plus an English transcription of the soundtrack
Audio	An English transcription of the recording

Tags land on the asset’s metadata (prefixed ai: so they sit beside any tags a person typed). Descriptions and speech transcripts are stored with the asset. Chat and search can then find “the clip where someone mentions the river” or “photos tagged as a cracked pipe” — without anyone labelling every file by hand.

That write-back is automatic on published Space assets. It is not a separate upload call on /v0/ai, and it is not the Tags Space module or channel /tags slash-commands.

The public /v0/ai routes are the conversational workspace: threads (topics), chats (conversation chains on a thread), and turns (user / assistant messages). A session-authenticated client can ask about the caller’s own Spaces, Channels, messages, and that analysed media.

Why it exists

Headless products get both halves: media that explains itself (tags + English text), and an assistant that can list and search the caller’s own data without embedding the web UI. Create a thread, send a turn, and render the assistant reply plus entity refs (spaces, channels, assets, and so on) for click-through in the host application.

Model

Resource	Role
Thread	A topic owned by the current user. Creating a thread also creates its first empty chat.
Chat	One conversation chain under a thread. A thread can have many chats.
Turn	One message in a chat (user, assistant, or tool). Bodies live in object storage; list/send return content and optional refs.

There is no standalone “send without a chat” route. Create a thread (or an extra chat), then POST /v0/ai/chats/{chatId}/turns.

Endpoints

Method	Path	Purpose
GET	/v0/ai/threads	List the caller’s threads (skip pagination)
POST	/v0/ai/threads	Create a thread and its first empty chat
GET	/v0/ai/threads/{threadId}	Fetch one thread
PATCH	/v0/ai/threads/{threadId}	Rename a thread ({ "title" })
GET	/v0/ai/threads/{threadId}/chats	List chats on a thread
POST	/v0/ai/threads/{threadId}/chats	Create another empty chat
PATCH	/v0/ai/chats/{chatId}	Rename a chat ({ "title" })
GET	/v0/ai/chats/{chatId}/turns	List turns (newest first)
POST	/v0/ai/chats/{chatId}/turns	Send a user turn; receive the assistant reply

Same license + Bearer session as the rest of /v0. Requires app.ai.* permissions on the caller’s role.

What send can do today

The assistant may use read-only list and search tools against the caller’s own data — including published assets whose tags and English transcripts AI already wrote. It does not create spaces, send messages, or mutate records from this route.

Send is not channel Tags NLP. Do not post /tags … here expecting a module card.

You do not POST bytes to /v0/ai to analyse a file. Publish the asset on a Space (Publish, approve, fetch); analysis runs afterwards. Media analyze / transcribe HTTP routes stay internal.

Limits

• ai.chats.send.perDay — plan entitlement; overage is 403 ENTITLEMENT_LIMIT_EXCEEDED
• Send can take up to five minutes (inference plus tool rounds). Size client timeouts accordingly
• List limit is capped at 100; titles are capped at 80 characters
• Threads and chats are owned by the current user — there is no share or delete in this contract

Guide: AI chat. Reference: API reference (tag AI).