> ## Documentation Index > Fetch the complete documentation index at: https://docs.cominty.ai/llms.txt > Use this file to discover all available pages before exploring further. # Start a thread > Start a conversation and post the first message. The response is the full thread. Send options.agent_id and options.user_id. options.memory_namespace binds the thread to a memory namespace for its whole life. Omit it and the thread uses the namespace already set on the agent, if any. Otherwise the thread runs without long-term memory tools. options.max_steps caps the tool rounds of the first assistant message. Omit it and the server applies its default, currently 60. ## OpenAPI ````yaml /openapi.json post /chat openapi: 3.1.0 info: title: cominty/cominty description: | ### Cominty Meta: ```json { "VERSION_TAG": "eng-997-add-organization-scoped-memory-namespaces.6928eb8", "VERSION_AT": "2026-10-07T14:46:28+02:00", "DEPLOYED_BY": "github-actions::elfominty", "DEPLOYED_AT": "2026-10-07T13:06:50Z", "AWS_SECRET_NAME": "cominty-monorepo-dev-python-api", "AWS_SECRET_VERSION": "3de071f4-5485-4bf2-a676-0f72bf7aa59f", "AWS_SECRET_REGION": "eu-west-3" } ``` version: eng-997-add-organization-scoped-memory-namespaces.6928eb8 servers: - url: https://ds.cominty.com security: - comintyToken: [] paths: /chat: post: tags: - chat - chat summary: Start a thread description: >- Start a conversation and post the first message. The response is the full thread. Send options.agent_id and options.user_id. options.memory_namespace binds the thread to a memory namespace for its whole life. Omit it and the thread uses the namespace already set on the agent, if any. Otherwise the thread runs without long-term memory tools. options.max_steps caps the tool rounds of the first assistant message. Omit it and the server applies its default, currently 60. operationId: start_chat_chat_post parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StartChat' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ThreadOut' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: StartChat: properties: name: anyOf: - type: string - type: 'null' title: Name description: Optional name for the new thread. project_id: anyOf: - type: string - type: 'null' title: Project Id description: Optional project to file the thread under. message: $ref: '#/components/schemas/HumanMessage' options: $ref: '#/components/schemas/StartChatOptions' type: object required: - message - options title: StartChat ThreadOut: properties: id: type: string format: uuid title: Id name: type: string title: Name created_at: type: string format: date-time title: Created At live: type: boolean title: Live starred: type: boolean title: Starred project_id: anyOf: - type: string - type: 'null' title: Project Id messages: items: $ref: '#/components/schemas/MessageOut' type: array title: Messages inception: type: string enum: - conversational - routine title: Inception readOnly: true additionalProperties: false type: object required: - id - name - created_at - live - starred - messages - inception title: ThreadOut HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError HumanMessage: properties: source_ids: anyOf: - items: type: integer type: array - type: 'null' title: Source Ids document_ids: anyOf: - items: type: string type: array - type: 'null' title: Document Ids disabled_tools: anyOf: - items: anyOf: - type: string enum: - web - company_documents - type: string pattern: ^mcp:. type: array - type: 'null' title: Disabled Tools content: type: string maxLength: 30000 title: Content file_ids: anyOf: - items: type: string type: array maxItems: 5 uniqueItems: true - type: 'null' title: File Ids type: object required: - content title: HumanMessage StartChatOptions: properties: agent_id: type: string title: Agent Id description: Agent that runs this thread. user_id: anyOf: - type: string - type: 'null' title: User Id description: >- End user the thread belongs to. Required for an API token. This does not select the memory namespace. max_steps: type: integer minimum: 1 title: Max Steps default: 60 description: >- Maximum tool rounds the agent may run for this message. Integer, at least 1. Omit it to use the server default, currently 60. Reaching the cap is not an error: the message still ends with status success. memory_namespace: anyOf: - type: string maxLength: 128 - type: 'null' title: Memory Namespace description: >- Namespace the thread may read and update. At most 128 characters. Omit it to use the agent's namespace, or to run without memory tools when the agent has none. The follow-up message call cannot change it. type: object required: - agent_id title: StartChatOptions MessageOut: properties: id: type: string format: uuid title: Id thread_id: type: string format: uuid title: Thread Id role: type: string title: Role content: type: string title: Content error_code: anyOf: - type: string const: budget_exhausted - type: 'null' title: Error Code questions: anyOf: - items: $ref: '#/components/schemas/Question' type: array - type: 'null' title: Questions live: type: boolean title: Live status: type: string title: Status events: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Events structured_output: anyOf: - additionalProperties: true type: object - type: 'null' title: Structured Output files: items: $ref: >- #/components/schemas/cominty__api__routers__chat__ConversationFileOut type: array title: Files agent: anyOf: - $ref: '#/components/schemas/cominty__api__routers__chat__AgentOut' - $ref: '#/components/schemas/ArchivedAgentSentinel' - type: 'null' title: Agent additionalProperties: false type: object required: - id - thread_id - role - content - error_code - questions - live - status - events - structured_output - files - agent title: MessageOut ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError Question: properties: prompt: type: string title: Prompt description: The actual text of the question you need to ask the user. options: items: type: string type: array title: Options description: >- A list of quick-reply strings to make it easier for the user to answer. Leave empty if specific suggestions don't make sense. additionalProperties: false type: object required: - prompt title: Question description: Represents a clarification or follow-up question for the user. cominty__api__routers__chat__ConversationFileOut: properties: id: type: string title: Id name: type: string title: Name size: type: integer title: Size mimetype: type: string title: Mimetype origin: $ref: '#/components/schemas/ContentOrigin' share_links: items: $ref: '#/components/schemas/ShareLinkOut' type: array title: Share Links url: type: string title: Url readOnly: true additionalProperties: false type: object required: - id - name - size - mimetype - origin - share_links - url title: ConversationFileOut cominty__api__routers__chat__AgentOut: properties: id: type: string title: Id name: type: string title: Name additionalProperties: false type: object required: - id - name title: AgentOut ArchivedAgentSentinel: type: string const: ARCHIVED ContentOrigin: type: string enum: - user - agent title: ContentOrigin ShareLinkOut: properties: created_at: type: string format: date-time title: Created At id: type: string title: Id last_accessed_at: anyOf: - type: string format: date-time - type: 'null' title: Last Accessed At access_count: type: integer title: Access Count revoked: type: boolean title: Revoked expires_at: anyOf: - type: string format: date-time - type: 'null' title: Expires At expired: type: boolean title: Expired protected: type: boolean title: Protected url: type: string title: Url readOnly: true additionalProperties: false type: object required: - created_at - id - last_accessed_at - access_count - revoked - expires_at - expired - protected - url title: ShareLinkOut securitySchemes: comintyToken: type: apiKey in: header name: x-cominty-token description: >- A Cominty Platform API secret. A key created now starts with sk-cmt-. Send it as is, or as Bearer sk-cmt-..., with at most one Bearer prefix. A key created before the prefix existed has no sk-cmt- and still works. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.