> ## Documentation Index > Fetch the complete documentation index at: https://docs.custral.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a conversation > Create a conversation, optionally attaching participants and importing an initial transcript. **Requires scope:** `conversations:write`. ## OpenAPI ````yaml /openapi-v1.json post /v1/conversations openapi: 3.1.0 info: title: Custral API version: v1 description: >- The curated, versioned, API-key-authenticated public REST surface (`/v1`). Every endpoint here is what the official SDKs (`@custral/sdk`) and the MCP server are built on. Authenticate with a secret API key (`sk_…`) created in **Settings → Applications**. contact: name: Custral Support email: hello@custral.com url: https://custral.com license: name: Proprietary url: https://custral.com servers: - url: https://api.custral.com description: Production security: - ApiKey: [] tags: - name: Identity description: Introspect the calling API key. - name: Records description: Create, list, retrieve, and update records on any object. - name: Objects description: Read the object (table) schema of your workspace. - name: Conversations description: View, manage, and ingest conversations and their messages. - name: MCP description: Introspect the Model Context Protocol tool surface for a key. - name: Documents description: Read record notes / page documents as markdown. paths: /v1/conversations: post: tags: - Conversations summary: Create a conversation description: >- Create a conversation, optionally attaching participants and importing an initial transcript. **Requires scope:** `conversations:write`. operationId: createConversation requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateConversationBody' responses: '200': description: The created conversation (detail shape). content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Conversation' reqId: $ref: '#/components/schemas/RequestId' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' components: schemas: CreateConversationBody: type: object description: The body of a create-conversation request. properties: title: type: string example: Jane Doe sourceType: type: string description: Free-form source label. Defaults to `api`. example: imessage channelId: type: - string - 'null' description: A channel (`chan_…`) to attach to. status: type: string enum: - open - closed - completed default: open participants: type: array items: $ref: '#/components/schemas/ParticipantInput' messages: type: array items: $ref: '#/components/schemas/AppendMessageBody' Conversation: type: object description: >- A conversation. `messages` + `participants` are present on retrieve/create and absent from list rows. properties: id: type: string example: conv_123 title: type: - string - 'null' example: Jane Doe status: type: - string - 'null' example: open outcome: type: - string - 'null' description: A disposition key, or null. example: won summary: type: - string - 'null' sourceType: type: - string - 'null' example: imessage channelId: type: - string - 'null' example: chan_123 startedAt: type: - string - 'null' format: date-time endedAt: type: - string - 'null' format: date-time createdAt: type: - string - 'null' format: date-time updatedAt: type: - string - 'null' format: date-time messages: type: array items: $ref: '#/components/schemas/Message' participants: type: array items: $ref: '#/components/schemas/Participant' required: - id RequestId: type: string description: >- A per-request id (`req_…`). Quote it to support when reporting a problem. example: req_2a1f9c8e7b6d5 ParticipantInput: type: object description: A participant to attach — a linked record, or a guest by name/email. properties: recordId: type: string description: Link an existing record (`rec_…`). name: type: string description: Guest display name. email: type: string description: Guest email. AppendMessageBody: type: object description: One message to push into a conversation. properties: text: type: string example: On my way! author: type: string description: Display name of the sender. authorId: type: string description: Stable handle of the sender (phone, email, record id). direction: type: string enum: - inbound - outbound timestamp: type: string format: date-time description: ISO 8601. Defaults to now. required: - text Message: type: object description: A single transcript message. properties: id: type: string example: msg_123 text: type: string example: On my way! author: type: - string - 'null' description: Display name of the sender. example: Jane Doe authorId: type: - string - 'null' description: Stable handle of the sender (phone, email, record id). example: '+15551234567' sourceType: type: - string - 'null' example: imessage direction: type: - string - 'null' enum: - inbound - outbound - null example: inbound timestamp: type: - string - 'null' format: date-time required: - id - text Participant: type: object description: A conversation participant — a linked record or a guest. properties: type: type: - string - 'null' enum: - record - guest - user - null example: record name: type: - string - 'null' example: Jane Doe email: type: - string - 'null' example: jane@acme.com recordId: type: - string - 'null' description: Set only for a linked record. example: rec_123 Error: type: object description: >- The failure envelope. Every error carries a machine-readable `code` and the `reqId` of the failing request. properties: error: type: object properties: code: type: string example: insufficient_scope required: - code reqId: $ref: '#/components/schemas/RequestId' required: - error responses: Unauthorized: description: >- The API key is missing, unknown, inactive, or expired (`code: invalid_api_key`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_api_key reqId: req_2a1f9c8e7b6d5 Forbidden: description: >- The key lacks the scope this endpoint requires (`code: insufficient_scope`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: insufficient_scope reqId: req_2a1f9c8e7b6d5 securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: sk_... description: >- A Custral **secret** API key (`sk_…`), created in Settings → Applications. Sent as `Authorization: Bearer sk_…`. The `X-Api-Key: sk_…` header is also accepted and takes precedence. Never expose a secret key in a browser. ```` ## Related topics - [The Conversation object](/dev/api-reference/conversations.md) - [MCP Server](/dev/mcp/overview.md) - [Applications & keys](/dev/api-reference/applications.md) - [Conversations](/dev/webhooks/events/conversations.md)