Reference - Cominty Docs

This page documents the SDK’s public surface. For task-oriented examples, see the Quickstart and the guides. For the underlying HTTP endpoints, see the API reference.

Client

AsyncCominty(
    *,
    user_id: str | None = None,    # required (arg or COMINTY_USER_ID); validated locally
    api_token: str | None = None,  # required (arg or COMINTY_API_KEY)
    base_url: str | None = None,   # default https://ds.cominty.com (or COMINTY_BASE_URL)
    timeout: float | None = None,  # seconds, default 60
)

user_id is mandatory, validated at construction (^user_[A-Za-z0-9]{20,}$). Chat and thread requests send it. Memory requests do not. Resource methods never take user_id.
Use it as an async context manager (async with) or call await client.close().
Properties: client.user_id, client.base_url.
Sub-resources: client.chat, client.threads, client.memory, and, since 1.2.0, client.mcp, client.agents, client.skills, client.sources, client.documents. The last five do not take user_id either.

See Configuration for the full settings table and resolution order.

Resources

`client.chat`

Method	Signature	Returns
`start`	`start(*, agent_id, message, name=None, file_ids=None, thread_capabilities=None, message_scope=None, max_steps=SERVER_DEFAULT)`	`StartedChat`
`send`	`send(thread_id, *, message, agent_id, file_ids=None, message_scope=None, max_steps=SERVER_DEFAULT)`	`AssistantRun`
`stream`	`stream(message_id)`	`AssistantRun` (no I/O until consumed)
`cancel`	`cancel(message_id)`	`Message` (`status` becomes `cancelled`)
`export`	`export(message_id, *, format)`	`bytes` (raw file content)
`upload_file`	`upload_file(file, *, filename=None, mimetype=None)`	`ConversationFile`
`download_file`	`download_file(file_id)`	`bytes` (raw file content)

start returns a StartedChat, a run whose .thread is guaranteed present. thread_capabilities is optional and only accepted here. Passing it to send is a TypeError. message_scope is accepted by both. See Capabilities.
max_steps caps the tool rounds of one message. See max_steps below and Limiting agent steps.
send returns an AssistantRun with no .thread. You hold the thread_id, and threads.get fetches the rest. Use it to answer the agent’s questions. Read the previous message to the end, or cancel it, before you call send: see One message at a time.
Invalid arguments raise InvalidParams before any request is sent.

Stop a message

cancel stops an assistant message that is still being generated. It returns the message with status set to cancelled. What the agent produced before the stop stays in events.

Case	Result
The message is running	Returns the `Message`, `status` is `cancelled`
The message finished, failed, or was already cancelled	`APIError` (400, `Message is not live`)
A user message	`APIError` (400): user messages are never live
An unknown message	`NotFoundError` (404)
`message_id` is not a UUID	`ValueError` (`message_id must be a UUID, got 'x'`)

cancel is not idempotent. A “stop” button should treat the 400 as “too late, nothing to stop”. A cancelled message frees the thread right away: you can send the next message without reading the cancelled message’s events. See One message at a time. ▶ examples/12_cancel_message.py

Export a message: `export`

export(message_id, *, format) renders a message to a document and returns the raw bytes. format is "pdf" or "docx" (type ExportFormat, importable from cominty_sdk).

Case	Result
A message with content	The file as `bytes`
Any other `format`	`InvalidParams` before any request
A message with no content, for example one still running	`APIError` (400, `Message has no content`)
An unknown message	`NotFoundError` (404)

The server sends no file name. Pick one when you write the bytes. ▶ examples/13_export_message.py

Upload and download files

upload_file registers a file and returns a ConversationFile. Pass its id in file_ids on start and send, at most 5 files per message.

`file`	`filename`	Result
A `pathlib.Path`	Optional. Defaults to the file’s name.	Name and mimetype are inferred
`bytes`	Required	The mimetype is guessed from the name
A plain `str`, or anything else	-	`InvalidParams`: a `str` is ambiguous between a path and text, so wrap a path in `Path(...)`

filename is 1 to 255 characters and cannot contain /.
mimetype is optional. It is guessed from the file name, with application/octet-stream as a fallback. An empty string is refused.
A file is at most 500 MiB. A bigger one raises InvalidParams before anything is sent.
A path that cannot be read raises OSError.
The whole file is held in memory, in both directions.

download_file(file_id) returns the bytes of any conversation file, including the ones the agent produced. An empty file_id raises ValueError. An unknown file raises NotFoundError. The call is not scoped to the client’s user_id: any file created through the API in your organization can be downloaded.

upload_file makes 3 calls: it requests a presigned upload permission, sends your bytes directly to the storage host, then confirms the upload with Cominty. download_file also fetches from a presigned URL. Your API key is only sent to the Cominty API, never to the storage host. Storage calls never follow redirects, and a presigned signature never appears in an error message. A storage refusal raises APIError with the storage reason as its message, for example EntityTooLarge. The multi-step flow only matters if you call the HTTP endpoints yourself. See Files and exports.

The API has no call to list or delete uploaded files, and it enforces a daily upload quota per organization. Another deployment can also set a lower size limit. httpx logs full request URLs at INFO, presigned signatures included, so keep its logger at WARNING.

▶ examples/14_upload_files.py

`max_steps`

max_steps is a keyword-only argument of start and send, typed MaxSteps = int | SERVER_DEFAULT. Import both from cominty_sdk:

from cominty_sdk import SERVER_DEFAULT, MaxSteps

Value	Result
Not passed, or `SERVER_DEFAULT`	The field is left out of the request. The server applies its own default.
Integer `>= 1`	Sent as `options.max_steps`.
`None`, `0`, a negative integer, a float, a bool, or a string	`InvalidParams` is raised before any request.

from cominty_sdk import InvalidParams

try:
    await client.chat.start(agent_id=AGENT_ID, message="hi", max_steps=0)
except InvalidParams as exc:
    print(exc)

▶ examples/10_max_steps.py

`client.threads`

Scoped to the client’s user_id automatically. thread_id accepts a str or a uuid.UUID.

Method	Signature	Returns
`list`	`list(*, limit=50, page=0, terms=None)`	`list[ThreadSummary]`
`get`	`get(thread_id)`	`Thread` (full history)
`update`	`update(thread_id, *, name=None, starred=None)`	`ThreadSummary`
`archive`	`archive(thread_id)`	`None`

`client.memory`

Scoped to a caller-chosen namespace, shared by the API key. Not scoped to user_id. client.memory does not send user_id. Concepts: Memory namespaces.

Method	Signature	Returns
`list`	`list(*, namespace=None)`	`list[MemoryFileSummaryOut]` (no `content`)
`list_namespaces`	`list_namespaces()`	`list[str]`
`create`	`create(*, path, namespace, purpose, content)`	`MemoryFileOut`
`get`	`get(path, *, namespace)`	`MemoryFileOut`
`update`	`update(path, *, namespace, version, content=..., purpose=...)`	`MemoryFileOut`
`delete`	`delete(path, *, namespace)`	`None`

namespace is required on create, get, update, and delete. It is a str of at most 128 characters, checked locally. path may have at most one folder segment. "notes/todo.md" is fine, "a/b/todo.md" isn’t. The SDK raises InvalidParams before any request. content may be an empty string. There’s no minimum length.

update is partial: only the fields you pass are sent. There is currently no way to clear content or purpose once set. The API silently ignores an explicit null (200, value unchanged), so the SDK raises InvalidParams locally for content=None or purpose=None instead of sending a request that looks like it succeeded but did nothing. version is required and must be the value from your last read of the file; a stale one raises ConflictError (409), a malformed one raises APIError (422). Treat version as an opaque token. Round-trip it, never parse or compare it.

delete is not idempotent: deleting an already-deleted (or never-existing) path raises NotFoundError (404) rather than succeeding again.

list() with no filter returns every file visible to the API key. Pass namespace= to keep one namespace. Omitting namespace on create, get, update, or delete is a TypeError. Thread, ThreadSummary, and Message do not expose the thread’s namespace.

Migrate from per-user memory

Memory used to be scoped to the client’s user_id. It is now scoped to a namespace you choose. client.user_id is still required and still applied to chat and threads.

Before	After
`await client.memory.list()`	Still runs, and now returns every namespace for the API key. Pass `namespace=` to filter.
`await client.memory.create(path=..., purpose=..., content=...)`	Add required `namespace=`.
`await client.memory.get(path)`	`await client.memory.get(path, namespace=...)`
`await client.memory.update(path, version=..., content=...)`	Add required `namespace=`.
`await client.memory.delete(path)`	`await client.memory.delete(path, namespace=...)`
No namespace listing	`await client.memory.list_namespaces()`
`chat.start` had no memory argument	`thread_capabilities=AgentCapabilities(memory=MemoryCapability(activation="always", namespace=...))` on `start` only. See Memory.

MemoryFileOut and MemoryFileSummaryOut each include namespace. Use the value the API returns. Do not assume a namespace named default. For files written before namespaces existed, see Memory namespaces.

`client.mcp`

Lists the MCP integrations the API key can use (GET /mcp/manifest). See MCP integrations.

Method	Signature	Returns
`list`	`list(*, enabled: bool \| None = True)`	`list[McpServerOut]` (may be empty)

enabled=True (the default) keeps the servers that are turned on. enabled=False keeps the ones that are off. enabled=None returns every server, in API order. The API returns all of them, and the SDK filters on is_enabled.
name is the value to store in McpCapability.connections and McpScope.connections.
origin is "builtin" or "remote", and scope is "organization" or "user", today. Both are plain strings, and other values may appear.
requires_oauth_connect is True when someone must connect the integration with OAuth on the platform first. connection_status (for example "connected") is present when known.
If the manifest cannot be loaded, the API answers 500 and the SDK raises ServerError.

▶ examples/19_mcp_servers.py

`client.agents`

Manages custom agents and their model chain. Concepts: Custom agents. Arguments after * are keyword-only.

Method	Signature	Returns
`list`	`list()`	`list[AgentSummaryOut]`
`list_models`	`list_models()`	`list[LLMModelSummaryOut]`
`get`	`get(agent_id)`	`AgentOut`
`create`	`create(*, name, description=None, instructions=None, scope="private", capabilities=None, allow_execution_options_override=False, model_ids=None)`	`AgentOut`
`update`	`update(agent_id, *, name=..., description=..., instructions=..., scope=..., capabilities=..., allow_execution_options_override=...)`	`AgentOut`
`set_models`	`set_models(agent_id, *, model_ids)`	`AgentOut`
`delete`	`delete(agent_id)`	`None`

Case	Result
Empty `name`, `description` over 500 characters, `instructions` over 30000, or an empty `model_ids`	`InvalidParams` before any request
`update` with no argument, or `None` for `name`, `scope`, or `allow_execution_options_override`	`InvalidParams` before any request
`None` for `description`, `instructions`, or `capabilities` on `update`	Clears the value
`skills.include` on `create` names a skill the key cannot read	`APIError` (422)
Unknown agent, a built-in agent, an agent of another organization, or another member’s private agent	`NotFoundError`, `detail` `Not Found`
`set_models` with an unknown model id	`NotFoundError`, `detail` `Bad model_ids`

scope is "private" (the key owner only) or "organization" (every member). The type is Scope.
update is partial: only the arguments you pass are sent. A capabilities object is merged capability by capability: each one you pass replaces the stored one, the others stay.
create(model_ids=...) sets the model chain. Omit it for the organization’s default chain. The chain is a failover order.
On a built-in agent (managed is True), set_models changes the chain of the whole organization for that agent. update and delete raise NotFoundError.
list() returns the built-in agents, the organization agents, and the key owner’s private agents. It returns AgentSummaryOut: no instructions, no models. Call get for the full AgentOut.
The legacy execution_options and memory_namespace are not exposed. Use capabilities (capabilities.memory sets the namespace).
delete is permanent. The API answers 204, and the SDK returns None.

▶ examples/16_agents.py

`client.skills`

Manages custom skills. Concepts: Skills.

Method	Signature	Returns
`list`	`list()`	`list[SkillOut]`
`create`	`create(file, *, display_name, scope="private")`	`SkillOut`
`update`	`update(skill_id, *, display_name=None, active=None, scope=None)`	`SkillOut`
`upload_version`	`upload_version(skill_id, file)`	`SkillOut`
`delete`	`delete(skill_id)`	`None`

Case	Result
`file` is a plain `str`, the folder has no `SKILL.md`, `display_name` is not 1 to 100 characters, or the archive is over 30 MB	`InvalidParams` before any request
`update` with nothing to change	`InvalidParams` before any request
The file cannot be read	`OSError`
The zip layout or the frontmatter is wrong	`APIError` (422), `detail` starts with `Invalid zip structure.` for a layout
The archive is too large for the server	`APIError` (413)
Two uploads of one skill within one second	`APIError` (500)
`update`, `upload_version`, or `delete` on a built-in skill, or one the key owner does not own	`NotFoundError`

file is a folder Path (zipped in memory, SKILL.md at its root, entries starting with . skipped), a .zip Path, or bytes (a zip archive). The skill takes the key’s surface: there is no surface argument. ▶ examples/17_skills.py

`client.sources`

Turns local files into an indexed document source. Concepts: Sources.

Method	Signature	Returns
`create`	`create(files, *, name=None)`	`SourceOut` (`pending` or `syncing`)
`list`	`list()`	`list[SourceOut]`
`get`	`get(source_pid)`	`SourceOut`
`update`	`update(source_pid, *, name)`	`SourceOut`
`add_files`	`add_files(source_pid, files)`	`list[FileOut]`, in upload order
`list_files`	`list_files(source_pid)`	`list[FileOut]`
`remove_file`	`remove_file(source_pid, file_id)`	`None`
`download_file`	`download_file(file_id)`	`bytes`
`start`, `pause`, `sync`, `archive`	`start(source_pid)` and the same for the others	`SourceOut`
`wait_synced`	`wait_synced(source_pid, *, timeout=600.0, interval=5.0)`	`SourceOut` (`synced`)

Case	Result
`files` is a plain `str`, an empty list, a missing file, two files with the same name, or more than 50 files	`InvalidParams` before any upload
`update` with a `name` that is not a string	`InvalidParams`
An empty `file_id` (`remove_file`, `download_file`)	`ValueError`
An unknown source, file, or `pid`	`NotFoundError`
`start`, `sync`, or `archive` from a status that does not allow it	`APIError` (400), `detail` `Operation is not valid`
The sync ends in another status than `synced`	`SourceSyncFailed` (carries `.source`)
The sync is still running after `timeout`	`asyncio.TimeoutError`
A storage refusal, or too many drives	`APIError`
An unusable upload permission	`SDKError`

create makes a drive, uploads each file through a presigned URL, then creates a private drag-and-drop source over it. Files upload one after the other, and the mimetype is guessed from the extension (application/octet-stream otherwise).
files is one file Path, a folder Path (its top-level files, hidden files skipped, no recursion), or an iterable of file Paths.
source.pid (a string) goes to every method here. source.id (an integer) goes to IndexedDocumentsCapability(source_ids=[...]) and IndexedDocumentsScope(source_ids=[...]).
list() returns the organization’s sources and the ones the key created, archived ones included.
get(pid) reads the list and picks, so it costs a list().
add_files and remove_file request a sync when the source accepts one (synced, error, out_of_sync, daily_quota_reached). The 50-file cap counts the files already in the source.
download_file fetches a presigned URL valid 5 minutes, then the bytes. The whole file is held in memory.
archive is terminal. It removes the indexed documents and the files, and the source stays listed with status == "archived".
Only drag-and-drop sources can be created with a key.

Server limits: 100 drives per user (each create makes one, and a drive cannot be deleted) and 50 files per source. A chat over a source must run with the key owner’s user_id. See Sources. ▶ examples/15_sources.py

`client.documents`

Method	Signature	Returns
`get`	`get(document_id)`	`DocumentMetadataOut`

Resolves a composite document id, such as the one in a <cite document_id="..."/> tag. The id may contain #: the SDK URL-encodes it. An empty id raises ValueError before any request. An unknown id raises NotFoundError. There is no call that lists documents.

The run handle

Returned by chat.start (StartedChat) and by chat.send / chat.stream (AssistantRun). A run is the assistant’s in-progress reply. Its stream is single-use. Iterate it or await its result (the result is cached either way).

Member	Description
`async for event in run`	yields progress events only; the terminal message is captured internally
`await run.result()`	drains the stream and returns the final `Message`
`await run.text()`	the final reply string (`result().content`)
`await run.questions()`	the agent’s clarifying `Question`s, or `[]`
`run.message_id`	the assistant message id (`UUID`)
`run.thread`	the `Thread` (`StartedChat` only; absent on a bare `AssistantRun`)
`async with run:` / `await run.aclose()`	release the stream early. It does not stop the message: see One message at a time

A run raises StreamInterrupted (carrying .partial) if the server shuts down mid-stream.

One message at a time

A thread processes one message at a time. A message stays pending until you read its events to the end, or cancel it. If you start a message and walk away, the thread stays busy, and the next chat.send fails with APIError (400, Cannot process multiple messages at the same time).

What happened to the previous message	Next `chat.send`
You read it to the end: `await run.result()`, `await run.text()`, or an `async for` that ran to the end	Works
You cancelled it with `chat.cancel`, even without reading its events	Works
You dropped the run, or left the `async for` early, and did not cancel	400, the message is still pending
You closed the stream with `run.aclose()`, or left an `async with run:` block, and did not cancel	400: closing the stream does not stop the message

Leaving a stream early only releases the connection. The message keeps running on the server. To stop reading and free the thread, cancel:

async with run:
    async for event in run:
        if user_clicked_stop():
            await client.chat.cancel(run.message_id)
            break

Use async with run: whenever you can leave the loop early. It closes the stream cleanly. Without it, Python can print “asynchronous generator” errors when the half-read stream is garbage collected. If you lost the run, or an earlier call left a message unread, free the thread by reading it. Message.live tells you which messages are still pending:

thread = await client.threads.get(thread_id)
for message in thread.messages:
    if message.live:
        await client.chat.stream(message.id).result()  # drains it, or cancel it

reply = await client.chat.send(thread_id, agent_id=AGENT_ID, message="Next question")

thread.live is True while any message is pending. A 400 from chat.send that says Cannot process multiple messages at the same time always means this. It is not the concurrency rate limit (RateLimitError with scope concurrency, HTTP 429), which counts simultaneous chats across all threads.

Data models

All models are Pydantic. Response models ignore unknown fields, so they are forward-compatible.

ThreadSummary + messages

Everything in ThreadSummary, plus messages: list[Message].

object

id: UUID · name: str · created_at: datetime · live: bool · agent: Agent · starred: bool · project_id: str | None

object

object

prompt: str · options: list[str]

object

id: str · name: str

object

id · name · size · mimetype · origin (user | agent) · share_links: list[ShareLink] · url

id · created_at · last_accessed_at? · access_count · revoked · expires_at? · expired · protected · url

object

Returned by memory.create, memory.get, and memory.update. path: str · namespace: str · purpose: str · content: str · created_at: datetime · updated_at: datetime · version: str (opaque, see client.memory)

object

Returned by memory.list. Everything in MemoryFileOut except content.

object

Returned by mcp.list. name: str (the value for connections) · title: str · description: str · is_enabled: bool · origin: str · scope: str · requires_oauth_connect: bool · connection_status: str | None · icon_uri? · mcp_url? · owner_id? · created_at? · updated_at?

object

Returned by agents.list. id: str · name: str · description: str | None · capabilities: AgentCapabilities | None · memory_namespace: str | None · managed: bool (True for built-in agents) · scope: Scope · owner: str (the user_id to chat with over the key’s sources) · execution_options: dict | None (legacy). Capabilities the SDK does not know yet are left out.

AgentSummaryOut + details

Returned by agents.get, create, update, and set_models. Everything in AgentSummaryOut, plus instructions: str | None · allow_execution_options_override: bool · models: list[LLMModelSummaryOut] (the chain, in failover order).

object

Returned by agents.list_models. id: str · name: str

object

Returned by skills.list, create, update, and upload_version. id: str · display_name: str · active: bool · scope: Scope | None (None for a built-in skill) · source: SkillSource · frontmatter: SkillFrontmatter · created_at: datetime · updated_at: datetime

object

The YAML frontmatter of SKILL.md, parsed by the server. name: str · description: str · license: str | None · compatibility: str | None · metadata: dict[str, str] · allowed_tools: list[str]

object

Returned by the client.sources methods that return a source. id: int (for source_ids) · pid: str (for every client.sources method) · name: str · scope: Scope · created_by: str · store: SourceStore · status: SourceStatus · size: int · embedded_size: int · documents_synced: int · documents_failed: int · oversized_documents: int · documents_embedded: int · last_synced_at: datetime | None · archived_at: datetime | None · created_at: datetime · config: dict · drive_id (property, str | None)

object

A file of a source. id: str · name: str · size: int · mimetype: str · created_at: datetime · updated_at: datetime

object

Returned by documents.get. document_id: str · source_id: int · source_pid: str · source_type: SourceStore · document_name: str · document_uri: str | None · document_extension: str · document_mime_type: str

Literal

"private" (the key owner only) or "organization" (every member). Used by agents, skills, and sources.

enum

cominty (built in, read-only) or custom (uploaded by the organization).

enum

draganddrop, googledrive, or sharepoint. An API key can only create draganddrop sources.

enum

pending · syncing · synced · error · out_of_sync · cancelling · pausing · paused · archived · disconnected · inoperative_connection · expired_connection · invalid_configuration · daily_quota_reached

Capabilities

Capabilities replace disabled_tools, source_ids, document_ids, and memory_namespace, which SDK 1.0.0 removes. Concepts and recipes: Capabilities and Use cases. To move old code, see Migrate from SDK 0.5.0.

from cominty_sdk import (
    ALL,
    AgentCapabilities,
    ImageGenerationCapability,
    ImageGenerationScope,
    IndexedDocumentsCapability,
    IndexedDocumentsScope,
    McpCapability,
    McpScope,
    MemoryCapability,
    MessageScope,
    MusicGenerationCapability,
    MusicGenerationScope,
    SkillsCapability,
    VideoGenerationCapability,
    VideoGenerationScope,
    WebCapability,
    WebScope,
)

Argument	On	Type	Lasts
`thread_capabilities`	`chat.start` only	`AgentCapabilities`	The whole thread. Frozen at start.
`message_scope`	`chat.start` and `chat.send`	`MessageScope`	One message

`AgentCapabilities`

Every field is optional and defaults to None. A field you do not pass keeps the agent’s value. A field you pass replaces the agent’s value entirely.

Field	Class	`activation`	Filters (default `ALL`)
`web`	`WebCapability`	`always`, `on_request`, `never`	-
`indexed_documents`	`IndexedDocumentsCapability`	`always`, `on_request`, `never`	`source_ids: list[int]`, `document_ids: list[str]`
`mcp`	`McpCapability`	`always`, `on_request`, `never`	`connections: list[str]`
`skills`	`SkillsCapability`	`always`, `never`	`include: list[str]`
`image_generation`	`ImageGenerationCapability`	`always`, `on_request`, `never`	-
`video_generation`	`VideoGenerationCapability`	`always`, `on_request`, `never`	-
`music_generation`	`MusicGenerationCapability`	`always`, `on_request`, `never`	-
`memory`	`MemoryCapability`	`always`, `never`	`namespace: str` (see Memory)

activation is required on every capability. There are no shortcuts: web=True and web="never" raise InvalidParams.

`MessageScope`

Every field is optional and defaults to None.

Field	Class	Filters (default `ALL`)
`web`	`WebScope`	-
`indexed_documents`	`IndexedDocumentsScope`	`source_ids`, `document_ids`
`mcp`	`McpScope`	`connections`
`image_generation`	`ImageGenerationScope`	-
`video_generation`	`VideoGenerationScope`	-
`music_generation`	`MusicGenerationScope`	-

enabled: bool is required on every scope. There is no scope for skills or memory. A scope can turn a capability on or off, or narrow a filter. It can never widen what the thread allows.

`ALL` and filters

ALL is the string "*": no restriction. It is the default of every filter, so passing it only makes the intent explicit. A filter is either ALL or a non-empty list.

Value	Result
Not passed, or `ALL`	No restriction
A non-empty list	Allowlist
`None`, `[]`, or `"*"` inside a list	`InvalidParams` before any request
Any filter with `activation="never"` or `enabled=False`	`InvalidParams` before any request

Memory

MemoryCapability(activation="always", namespace=...) attaches the thread to a memory bag. The namespace is required and is 1 to 128 characters. MemoryCapability(activation="never") runs the thread without memory and takes no namespace. Without a memory entry, the thread uses the agent’s namespace, or runs without memory if the agent has none. The bag is frozen for the thread: a follow-up cannot change it. See Memory namespaces.

Errors

Invalid objects raise InvalidParams as soon as you build them. The server answers 422 (APIError) when a message widens an allowlist, targets a capability the thread does not have, or sets enabled=False on an on_request capability. See Troubleshooting. ▶ examples/11_capabilities.py

Streamed events

from cominty_sdk import events Every event has id: str, correlation_id: int, at: datetime, status: "running" | "success" | "error", and a name. Match on the type:

Class	`name`	Payload (`event.data`)
`WaitingForStart`	`waiting_for_start`	-
`SettingUpSandbox`	`setting_up_sandbox`	-
`UploadingFile`	`uploading_file`	`filename`
`LlmStep`	`llm`	`description`, `model`
`IntermediaryUpdate`	`intermediary_update`	`message`
`ToolCall`	`tool_call`	`name`, `description`, `message?`, `error?`
`Result`	`result`	`reply`, `files`, `questions?`, `metadata?`, `cost`
`UnknownEvent`	(any new name)	`data: dict	None` (forward-compatible)

Result.data.cost is a Cost: failed, input_tokens, cached_tokens, output_tokens, input_cost, output_cost, total (all Decimal).

Exceptions

from cominty_sdk import ...

ComintyError
├── APIError              # HTTP 4xx/5xx. .status_code, .detail, .body, .headers
│   ├── AuthError         # 401
│   ├── PermissionError   # 403
│   ├── NotFoundError     # 404
│   ├── ConflictError     # 409
│   ├── RateLimitError    # 429
│   └── ServerError       # 5xx
├── APIConnectionError    # network error / timeout (no response)
├── StreamInterrupted     # server shut down mid-stream. .partial: Message
├── SourceSyncFailed      # a source did not reach "synced". .source: SourceOut
├── InvalidParams         # client-side validation failed. .errors: list[InvalidParam]
└── SDKError              # internal SDK bug

cominty_sdk.PermissionError shadows the Python built-in PermissionError once you write from cominty_sdk import PermissionError. Import it as cominty_sdk.PermissionError, or under another name, if your code also catches the built-in. SourceSyncFailed is not an APIError: sources.wait_synced raises it when the source settles in a status other than synced, such as error, paused, or daily_quota_reached. Read exc.source.status to see which one.

`RateLimitError`

Turns the terse 429 into a clear, actionable message and exposes:

scope → "organization" | "user" | "concurrency"
retry_after → seconds (from the Retry-After header), or None
reset_at → datetime (from reset_at / X-RateLimit-Reset), or None

Example messages:

Organization rate limit reached: your organization’s total request quota is exhausted. Ask an organization admin to raise your plan’s limit. Quota resets at 2026-06-30T00:00:00+00:00.
User rate limit reached: your user request quota is exhausted. Ask an organization admin to raise your plan’s limit.
Too many concurrent requests: your plan’s limit on simultaneous chat sessions is reached. Wait for an in-flight request to finish and retry, or raise the limit.

​Client

​Resources

​client.chat

​Stop a message

​Export a message: export

​Upload and download files

​max_steps

​client.threads

​client.memory

​Migrate from per-user memory

​client.mcp

​client.agents

​client.skills

​client.sources

​client.documents

​The run handle

​One message at a time

​Data models

​Capabilities

​AgentCapabilities

​MessageScope

​ALL and filters

​Memory

​Errors

​Streamed events

​Exceptions

​RateLimitError

Client

Resources

`client.chat`

Stop a message

Export a message: `export`

Upload and download files

`max_steps`

`client.threads`

`client.memory`

Migrate from per-user memory

`client.mcp`

`client.agents`

`client.skills`

`client.sources`

`client.documents`

The run handle

One message at a time

Data models

Capabilities

`AgentCapabilities`

`MessageScope`

`ALL` and filters

Memory

Errors

Streamed events

Exceptions

`RateLimitError`