> ## Documentation Index > Fetch the complete documentation index at: https://docs.conduit.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Agent > Creates a V2 chat agent and its initial trigger set. Requires a token with write access. ## OpenAPI ````yaml POST /v1/agents openapi: 3.0.0 info: title: Conduit API version: 1.0.0 description: Public API for Conduit. servers: - url: https://api.conduit.ai description: Production security: [] tags: - name: meta description: Discovery and API metadata endpoints. - name: agents description: >- V2 chat agent configuration, including instructions, skills, triggers, and automation behavior. - name: contacts description: >- Contact profile and contact-scoped related resources such as tickets and calls. - name: workspaces description: Workspaces accessible to the current API token. - name: escalations description: >- Chat escalations that require operator review, including message, proposed response, and disposition context when available. - name: conversations description: >- Canonical message threads. Use these endpoints to list threads, inspect conversation state, read transcripts, and send replies. - name: conversation-tags description: >- Conversation labels, root topics, and subtopics used for classification and topic analytics. - name: tickets description: >- Operational queue items tied to conversations, including ticket-scoped transcripts and replies. - name: calls description: Phone call records, transcripts, summaries, and recordings when available. - name: reservations description: >- PMS reservations synced from the workspace's integrations (Hostaway, Guesty, Airbnb, etc.), including guest identity, payment status, and stay dates. - name: appointments description: >- Scheduled appointments (bookings) backed by the Conduit booking service. Exposes allocation context and the upstream booking-service `external_id`. - name: helpdesk_tickets description: >- Helpdesk tickets mirrored from external helpdesk integrations (Zendesk, Pylon, Plain), including requester identity and upstream metadata. - name: kb description: >- Knowledge base search and node management. Nodes represent knowledge base entries (files or directories), chunks are the indexed retrieval units used by search. - name: skills description: >- Workspace agent skills that can be attached to V2 chat agents. Sidebar/global-assistant skills are intentionally excluded. - name: custom_tools description: >- Custom code tools: user-authored Python/JavaScript functions executed in a sandbox when an agent calls them. Includes a runtimes endpoint describing the entrypoint signature, return shape, and available dependencies per language. - name: inbox_types description: >- Workspace inbox types. Each id is stable and usable as a message trigger's `inboxTypeId` and as the `inbox_type_id` filter on list conversations. - name: workflows description: >- Workspace automation workflows: definitions, executions, and per-execution event timelines. - name: insights description: Aggregated workspace analytics, such as conversation automation rate. paths: /v1/agents: post: tags: - agents summary: Create V2 chat agent description: >- Creates a V2 chat agent and its initial trigger set. Requires a token with write access. operationId: createAgent requestBody: required: true content: application/json: schema: type: object properties: workspace_id: type: string name: type: string minLength: 1 description: type: string minLength: 1 color: type: string minLength: 1 icon_id: type: integer minimum: 0 instructions: type: string minLength: 1 model: type: string nullable: true minLength: 1 description: >- Override the LLM this agent runs on. Must be a `model_string` from `GET /v1/models` (MCP: `list_supported_models`), e.g. `openai:gpt-4o`. Omit to leave unchanged; send null to reset to the workspace default. Reads return the configured value, or `default` when none is set. guardrails: type: array items: type: object properties: title: type: string knowledge: type: string required: - title - knowledge skill_ids: type: array items: type: string operation_mode: type: string enum: - autopilot - copilot - inactive autopilot_schedule: type: object properties: timezone: type: string description: >- IANA timezone the schedule is evaluated in, e.g. "America/New_York". days: type: array items: type: object properties: day: type: string enum: - sunday - monday - tuesday - wednesday - thursday - friday - saturday description: Day of the week this window applies to. enabled: type: boolean description: Whether autopilot is active on this day. ranges: type: array items: type: object properties: start: type: string description: >- Window start as a 12-hour clock time, e.g. "09:00 AM". end: type: string description: >- Window end as a 12-hour clock time, e.g. "05:00 PM". required: - start - end description: >- Time windows during which autopilot is active on this day. required: - day - enabled - ranges description: Per-day autopilot windows. required: - timezone - days description: >- Autopilot schedule. Autopilot only sends inside the enabled day windows; outside them the agent falls back to copilot. Omit or set null for always-on autopilot. custom_response_delay_ms: type: integer minimum: 0 auto_mark_as_done: type: boolean response_language: type: string nullable: true enum: - English - Original - Spanish - French - German - Italian - Portuguese responseflow: type: boolean output_schema: type: array items: type: object properties: name: type: string description: type: string type: type: string is_required: type: boolean required: - name - type enabled: type: boolean triggers: type: array items: oneOf: - type: object properties: type: type: string enum: - message name: type: string minLength: 1 description: type: string nullable: true minLength: 1 config: oneOf: - type: object properties: scopeType: type: string enum: - all required: - scopeType additionalProperties: false - type: object properties: scopeType: type: string enum: - inbox inboxTypeId: type: string required: - scopeType - inboxTypeId additionalProperties: false - type: object properties: scopeType: type: string enum: - channel channelType: type: string enum: - airbnb - booking_com - sms - whatsapp - messenger - email - unthreaded_email - pms - widget - instagram - vrbo - expedia - helpdesk - slack - line_oa - portal required: - scopeType - channelType additionalProperties: false enabled: type: boolean required: - type - name - config - type: object properties: type: type: string enum: - webhook name: type: string minLength: 1 description: type: string nullable: true minLength: 1 config: nullable: true enabled: type: boolean required: - type - name - type: object properties: type: type: string enum: - cron name: type: string minLength: 1 description: type: string nullable: true minLength: 1 config: type: object properties: prompt: type: string minLength: 1 spec: oneOf: - type: object properties: kind: type: string enum: - once atMs: type: number required: - kind - atMs additionalProperties: false - type: object properties: kind: type: string enum: - interval everyMinutes: type: integer minimum: 1 required: - kind - everyMinutes additionalProperties: false - type: object properties: kind: type: string enum: - daily hour: type: integer minimum: 0 maximum: 23 minute: type: integer minimum: 0 maximum: 59 required: - kind - hour - minute additionalProperties: false - type: object properties: kind: type: string enum: - weekly dayOfWeek: type: integer minimum: 0 maximum: 6 hour: type: integer minimum: 0 maximum: 23 minute: type: integer minimum: 0 maximum: 59 required: - kind - dayOfWeek - hour - minute additionalProperties: false timezone: type: string minLength: 1 overlapPolicy: type: string enum: - skip required: - prompt - spec - timezone - overlapPolicy additionalProperties: false enabled: type: boolean required: - type - name - config - type: object properties: type: type: string enum: - event name: type: string minLength: 1 description: type: string nullable: true minLength: 1 config: type: object properties: eventType: type: string enum: - CONTACT_NEW - CONTACT_ATTRIBUTE_UPDATED - CONTACT_LABEL_ADDED - CONVERSATION_TAG_ADDED - TASK_NEW - TASK_STATUS_CHANGED - TASK_COMPLETED - TASK_STARTED - TASK_ASSIGNED - RESERVATION_NEW - RESERVATION_MODIFIED - RESERVATION_LABEL_ADDED - BOOKING_NEW - BOOKING_MODIFIED - CLEANING_STATUS_CHANGED - ESCALATION_CREATED - CALL_COMPLETED - CALL_MISSED - WIDGET_FORM_SUBMITTED - WIDGET_SESSION_ENDED - AI_TRIGGER - WEBHOOK_RECEIVED - STRIPE_WEBHOOK - PORTAL_VIEWED - PORTAL_OFFER_VIEWED - PORTAL_OFFER_ADDED_TO_CART - PORTAL_OFFER_REMOVED_FROM_CART - PORTAL_CHECKOUT_OPENED - PORTAL_CHECKOUT_STARTED - PORTAL_PAYMENT_SUBMITTED - PORTAL_CHECKOUT_SUCCEEDED - PORTAL_PAYMENT_FAILED - PORTAL_REFUND_ISSUED - PORTAL_SESSION_COMPLETED - PORTAL_SESSION_EXPIRED - PORTAL_REQUEST_SUBMITTED - PORTAL_REQUEST_APPROVED - PORTAL_REQUEST_DECLINED - PORTAL_REQUEST_EXPIRED - PORTAL_DELIVERY_FAILED - PORTAL_MANDATORY_FEE_PAID - PORTAL_SECURITY_DEPOSIT_AUTHORIZED - PORTAL_SECURITY_DEPOSIT_CAPTURED - PORTAL_SECURITY_DEPOSIT_RELEASED - PORTAL_SECURITY_DEPOSIT_RENEWAL_REQUIRED - PORTAL_AGREEMENT_SIGNED - PORTAL_DAMAGE_WAIVER_SIGNED - PORTAL_DAMAGE_WAIVER_PAID - PORTAL_GUEST_DETAILS_SUBMITTED - PORTAL_ADDITIONAL_QUESTIONS_SUBMITTED - PORTAL_OTHER_GUESTS_SUBMITTED - PORTAL_CHECK_IN_RATED prompt: type: string minLength: 1 required: - eventType - prompt additionalProperties: false enabled: type: boolean required: - type - name - config - type: object properties: type: type: string enum: - mention name: type: string minLength: 1 description: type: string nullable: true minLength: 1 config: oneOf: - type: object properties: tool: type: string enum: - slack slackTeamId: type: string minLength: 1 slackChannelId: type: string minLength: 1 required: - tool additionalProperties: false - type: object properties: tool: type: string enum: - linear linearTeamId: type: string minLength: 1 required: - tool additionalProperties: false - type: object properties: tool: type: string enum: - microsoft_teams tenantId: type: string minLength: 1 teamId: type: string minLength: 1 channelId: type: string minLength: 1 required: - tool additionalProperties: false enabled: type: boolean required: - type - name - config - type: object properties: type: type: string enum: - manual name: type: string minLength: 1 description: type: string nullable: true minLength: 1 config: nullable: true enabled: type: boolean required: - type - name minItems: 1 required: - workspace_id - name - triggers description: >- Request body for creating a V2 chat agent with one or more triggers. example: workspace_id: j57demo8f8x7c9v0n2q4r6t8y1u3i5o name: Reservations description: Handles booking and cancellation flows. color: '#2563EB' icon_id: 12 instructions: >- Answer booking questions, use policies before escalating, and keep replies concise. guardrails: - title: Do not promise refunds knowledge: >- Only cite refund terms from approved policy docs or escalate. skill_ids: - ks77c0dy0mgdpzmqz6tesry8w184002s operation_mode: autopilot response_language: English responseflow: true custom_response_delay_ms: 10000 auto_mark_as_done: false output_schema: - name: resolution description: Short summary of the final outcome. type: string is_required: true triggers: - name: All Messages description: Runs for every inbound message. type: message config: scopeType: all enabled: true - name: Contact Inbox description: Runs only for contact-type inbox messages. type: message config: scopeType: inbox inboxTypeId: guest enabled: true responses: '201': description: Agent created content: application/json: schema: type: object properties: data: type: object properties: id: type: string workspace_id: type: string name: type: string description: type: string nullable: true color: type: string nullable: true icon_id: type: number nullable: true version: type: string enum: - v2 instructions: type: string nullable: true model: type: string description: >- The LLM this agent runs on: a kb_api `model_string` (e.g. `openai:gpt-4o`), or `default` when no override is set. guardrails: type: array items: type: object properties: id: type: string title: type: string knowledge: type: string required: - title - knowledge operation_mode: type: string enum: - autopilot - copilot - inactive autopilot_schedule: type: object nullable: true properties: timezone: type: string description: >- IANA timezone the schedule is evaluated in, e.g. "America/New_York". days: type: array items: type: object properties: day: type: string enum: - sunday - monday - tuesday - wednesday - thursday - friday - saturday description: Day of the week this window applies to. enabled: type: boolean description: Whether autopilot is active on this day. ranges: type: array items: type: object properties: start: type: string description: >- Window start as a 12-hour clock time, e.g. "09:00 AM". end: type: string description: >- Window end as a 12-hour clock time, e.g. "05:00 PM". required: - start - end description: >- Time windows during which autopilot is active on this day. required: - day - enabled - ranges description: Per-day autopilot windows. required: - timezone - days description: >- Autopilot schedule. Autopilot only sends inside the enabled day windows; outside them the agent falls back to copilot. Omit or set null for always-on autopilot. custom_response_delay_ms: type: number auto_mark_as_done: type: boolean response_language: type: string nullable: true enum: - English - Original - Spanish - French - German - Italian - Portuguese responseflow: type: boolean output_schema: type: array items: type: object properties: name: type: string description: type: string type: type: string is_required: type: boolean required: - name - type skill_ids: type: array items: type: string connection_ids: type: array items: type: string description: >- Ids of the integration connections linked to this agent. Use list_agent_connections (GET /v1/agents/{id}/connections) for the full connection details and their tools. enabled: type: boolean triggers: type: array items: oneOf: - type: object properties: id: type: string workspace_id: type: string name: type: string description: type: string nullable: true type: type: string enum: - message config: oneOf: - type: object properties: scopeType: type: string enum: - all required: - scopeType additionalProperties: false - type: object properties: scopeType: type: string enum: - inbox inboxTypeId: type: string required: - scopeType - inboxTypeId additionalProperties: false - type: object properties: scopeType: type: string enum: - channel channelType: type: string enum: - airbnb - booking_com - sms - whatsapp - messenger - email - unthreaded_email - pms - widget - instagram - vrbo - expedia - helpdesk - slack - line_oa - portal required: - scopeType - channelType additionalProperties: false - nullable: true enabled: type: boolean created_at: type: string updated_at: type: string required: - id - workspace_id - name - description - type - config - enabled - created_at - updated_at - type: object properties: id: type: string workspace_id: type: string name: type: string description: type: string nullable: true type: type: string enum: - webhook config: nullable: true enabled: type: boolean created_at: type: string updated_at: type: string required: - id - workspace_id - name - description - type - enabled - created_at - updated_at - type: object properties: id: type: string workspace_id: type: string name: type: string description: type: string nullable: true type: type: string enum: - cron config: nullable: true enabled: type: boolean created_at: type: string updated_at: type: string required: - id - workspace_id - name - description - type - enabled - created_at - updated_at - type: object properties: id: type: string workspace_id: type: string name: type: string description: type: string nullable: true type: type: string enum: - event config: nullable: true enabled: type: boolean created_at: type: string updated_at: type: string required: - id - workspace_id - name - description - type - enabled - created_at - updated_at - type: object properties: id: type: string workspace_id: type: string name: type: string description: type: string nullable: true type: type: string enum: - mention config: oneOf: - type: object properties: tool: type: string enum: - slack slackTeamId: type: string minLength: 1 slackChannelId: type: string minLength: 1 required: - tool additionalProperties: false - type: object properties: tool: type: string enum: - linear linearTeamId: type: string minLength: 1 required: - tool additionalProperties: false - type: object properties: tool: type: string enum: - microsoft_teams tenantId: type: string minLength: 1 teamId: type: string minLength: 1 channelId: type: string minLength: 1 required: - tool additionalProperties: false enabled: type: boolean created_at: type: string updated_at: type: string required: - id - workspace_id - name - description - type - config - enabled - created_at - updated_at - type: object properties: id: type: string workspace_id: type: string name: type: string description: type: string nullable: true type: type: string enum: - manual config: nullable: true enabled: type: boolean created_at: type: string updated_at: type: string required: - id - workspace_id - name - description - type - enabled - created_at - updated_at created_at: type: string updated_at: type: string required: - id - workspace_id - name - description - color - icon_id - version - instructions - model - guardrails - operation_mode - autopilot_schedule - custom_response_delay_ms - auto_mark_as_done - response_language - responseflow - output_schema - skill_ids - connection_ids - enabled - triggers - created_at - updated_at required: - data description: Single V2 chat agent response. example: data: id: ag77c0dy0mgdpzmqz6tesry8w184002s workspace_id: j57demo8f8x7c9v0n2q4r6t8y1u3i5o name: Reservations description: Handles booking and cancellation flows. color: '#2563EB' icon_id: 12 version: v2 instructions: >- Answer booking questions, use policies before escalating, and keep replies concise. model: default guardrails: - id: guardrail_1 title: Do not promise refunds knowledge: >- Only cite refund terms from approved policy docs or escalate. operation_mode: autopilot autopilot_schedule: null custom_response_delay_ms: 10000 auto_mark_as_done: false response_language: English responseflow: true output_schema: - name: resolution description: Short summary of the final outcome. type: string is_required: true skill_ids: - ks77c0dy0mgdpzmqz6tesry8w184002s connection_ids: - cn77c0dy0mgdpzmqz6tesry8w184002s enabled: true triggers: - id: tr77c0dy0mgdpzmqz6tesry8w184002s workspace_id: j57demo8f8x7c9v0n2q4r6t8y1u3i5o name: All Messages description: Runs for every inbound message. type: message config: scopeType: all enabled: true created_at: '2026-04-01T17:22:10.000Z' updated_at: '2026-04-03T03:14:15.000Z' - id: tr88c0dy0mgdpzmqz6tesry8w184003s workspace_id: j57demo8f8x7c9v0n2q4r6t8y1u3i5o name: Contact Inbox description: Runs only for contact-type inbox messages. type: message config: scopeType: inbox inboxTypeId: guest enabled: true created_at: '2026-04-01T17:22:10.000Z' updated_at: '2026-04-03T03:14:15.000Z' - id: tr99c0dy0mgdpzmqz6tesry8w184004s workspace_id: j57demo8f8x7c9v0n2q4r6t8y1u3i5o name: SMS Channel description: Runs only for SMS channel messages. type: message config: scopeType: channel channelType: sms enabled: true created_at: '2026-04-01T17:22:10.000Z' updated_at: '2026-04-03T03:14:15.000Z' created_at: '2026-04-01T17:22:10.000Z' updated_at: '2026-04-03T03:14:15.000Z' '400': description: Invalid request content: application/json: schema: type: object properties: error: type: string required: - error description: Standard error response. example: error: Invalid workspace id '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string required: - error description: Standard error response. example: error: Invalid workspace id '403': description: Forbidden content: application/json: schema: type: object properties: error: type: string required: - error description: Standard error response. example: error: Invalid workspace id '409': description: Conflict content: application/json: schema: type: object properties: error: type: string required: - error description: Standard error response. example: error: Invalid workspace id '429': description: Rate limit exceeded content: application/json: schema: type: object properties: error: type: string required: - error description: Standard error response. example: error: Invalid workspace id security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Token description: >- Conduit API token. Use `Authorization: Bearer `. Read/write endpoints require a token with write access. ````