> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowengineering.com/llms.txt > Use this file to discover all available pages before exploring further. # Start an agent chat on a project (and optionally a branch) with an opening message > Creates the chat and, when `messages` is given, starts the agent on it. Answers as soon as the chat exists — its `status` is `streaming` while the agent works and `ready` once it has answered — unless `wait: true` holds the request until the opening turn has finished. Poll GET /ai/trigger/runs?agent_ids={id} (the same poll as for an automation run) or GET /ai/agents/{id} for the transcript. ## OpenAPI ````yaml /openapi/customer-api.json post /ai/agents openapi: 3.0.0 info: contact: {} description: >- Flow customer API reference. Start with the [quickstart](/api/quickstart) and [authentication guide](/api/authentication). title: Customer API version: 1.0.0 servers: - description: Flow API url: '{baseUrl}' variables: baseUrl: default: https://backend.branch.flowengineering.com security: [] tags: - name: Automations - name: Branches - name: Comments - name: Convert - name: Data Model - name: Diagrams - name: Entities - name: Files - name: Import - name: Notifications - name: Projects - name: ReqIF - name: ReqIF Import - name: Shared Access Grants - name: User Groups - name: Users paths: /ai/agents: post: tags: - Automations summary: >- Start an agent chat on a project (and optionally a branch) with an opening message description: >- Creates the chat and, when `messages` is given, starts the agent on it. Answers as soon as the chat exists — its `status` is `streaming` while the agent works and `ready` once it has answered — unless `wait: true` holds the request until the opening turn has finished. Poll GET /ai/trigger/runs?agent_ids={id} (the same poll as for an automation run) or GET /ai/agents/{id} for the transcript. operationId: AgentChatController_create parameters: - description: Workspace identifier in: header name: customer required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAgentChatDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/AgentChatResponseDto' description: '' security: - api-key: [] - bearer: [] components: schemas: CreateAgentChatDto: properties: ai_model: description: Model to answer this chat with, instead of the project's. nullable: true type: string branch_id: nullable: true type: string messages: description: >- The opening turn. Each message is `{ "role": "user", "content": "…" }`; given, the agent starts answering as soon as the chat exists. Omitted, the chat is created idle and POST /ai/agents/{id}/messages starts it. items: type: object type: array project_id: type: string title: type: string trigger_info: description: >- The caller's own labels for the chat, kept on it as sent. `api_key_id` is always the calling key, whatever the body says. type: object visibility: default: private enum: - private - shared type: string wait: default: false description: >- Hold the request open until the opening turn has finished and return the complete transcript. Off, the response comes back as soon as the chat exists with `status: "streaming"`; poll GET /ai/trigger/runs or GET /ai/agents/{id} for the outcome, exactly as for an automation run. type: boolean required: - project_id type: object AgentChatResponseDto: properties: ai_model: nullable: true type: string archived: type: boolean branch_id: nullable: true type: string branches: default: [] items: type: object type: array config_id: nullable: true type: string context_usage: allOf: - $ref: '#/components/schemas/AiContextUsageDto' nullable: true type: object created_at: format: date-time type: string created_by: type: string error: nullable: true type: string error_details: nullable: true type: string id: type: string integration_grade: nullable: true type: string integration_response: nullable: true type: string last_user_message_at: format: date-time type: string messages: items: type: object type: array parent_agent_id: nullable: true type: string plan_headline: nullable: true type: string plan_items: default: [] items: $ref: '#/components/schemas/AgentPlanItemDto' type: array project_id: nullable: true type: string root_agent_id: nullable: true type: string shared_with: default: [] items: type: string type: array spawn_depth: type: number spawn_tool_call_id: nullable: true type: string status: type: string title: nullable: true type: string trigger_info: nullable: true type: object trigger_type: enum: - branch - endpoint - import - schedule - slack - github - gitlab - onshape - webhook - assistant - entity_edit - manual - impact_analysis - what_if_analysis - subagent nullable: true type: string updated_at: format: date-time type: string visibility: type: string required: - id - messages - status - title - error - error_details - branch_id - project_id - config_id - parent_agent_id - root_agent_id - spawn_depth - spawn_tool_call_id - visibility - created_by - shared_with - created_at - updated_at - trigger_type - trigger_info - plan_items - plan_headline - ai_model - context_usage - archived - last_user_message_at type: object AiContextUsageDto: properties: budgetTokens: description: Effective input budget for this deployment. type: number droppedCount: description: History turns being withheld from the model (0 = none). type: number usedTokens: description: >- Estimated tokens the conversation occupies. Approximate, and may exceed budgetTokens. type: number required: - usedTokens - budgetTokens - droppedCount type: object AgentPlanItemDto: properties: conclusion: enum: - pass - fail - warning - skipped type: string detail: type: string status: enum: - pending - in_progress - done type: string title: type: string required: - title - status type: object securitySchemes: api-key: in: header name: X-API-Key type: apiKey bearer: bearerFormat: JWT scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.