Skip to main content
This page documents the SDK’s public surface. For task-oriented examples, see the Quickstart; for the underlying HTTP endpoints, see the API reference.

​
Client

  • user_id is mandatory, validated at construction (^user_[A-Za-z0-9]{20,}$), and applied to every request — resource methods never take it.
  • 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.
See Configuration for the full settings table and resolution order.

​
Resources

​
client.chat

  • start returns a StartedChat — a run whose .thread is guaranteed present.
  • send returns an AssistantRun — no .thread; you hold the thread_id, and threads.get fetches the rest. Use it to answer the agent’s questions.
  • Invalid arguments raise InvalidParams before any request is sent.

​
client.threads

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

​
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).
A run raises StreamInterrupted (carrying .partial) if the server shuts down mid-stream.

​
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
id: UUID · thread_id: UUID · role: MessageRole (user | assistant) · content: str · questions: list[Question] | None · live: bool · status: MessageStatus (pending | running | success | failed | cancelled) · events: list[dict] | None · structured_output: dict | None · files: list[ConversationFile]
​
object
prompt: str · options: list[str]
​
object
id: str · name: str
​
object
id · name · size · mimetype · origin (user | agent) · share_links: list[ShareLink] · url
​
object
id · created_at · last_accessed_at? · access_count · revoked · expires_at? · expired · protected · url

​
disabled_tools

Passed to chat.start and chat.send. Tools are on by default; each entry turns one off: The SDK validates the mcp: arm locally and rejects anything else (with InvalidParams) before sending.

​
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: 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 ...

​
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.