> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dimedove.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create conversation

> Creates a new conversation linked to your app's AI agent. Optionally associate an external user ID for tracking and set a custom title.



## OpenAPI

````yaml /openapi/apps-api.json post /apps/{app_id}/conversations
openapi: 3.1.0
info:
  title: Dimedove API
  version: 1.0.0
  description: >-
    Programmatically manage conversations and interact with your AI agents
    through the Dimedove API.
servers:
  - url: https://api.dimedove.com/v1
    description: Production
security: []
paths:
  /apps/{app_id}/conversations:
    post:
      tags:
        - Conversations
      summary: Create conversation
      description: >-
        Creates a new conversation linked to your app's AI agent. Optionally
        associate an external user ID for tracking and set a custom title.
      operationId: apps_api_create_conversation
      parameters:
        - in: path
          name: app_id
          schema:
            description: The unique identifier of the app.
            title: App Id
            type: string
          required: true
          description: The unique identifier of the app.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationCreateRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationSchema'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorSchema'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorSchema'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorSchema'
      security:
        - AppsApiKeyAuth: []
components:
  schemas:
    ConversationCreateRequest:
      example:
        external_user_id: user_abc123
        metadata:
          first_name: John
          plan_type: term_life
        title: Support inquiry
      properties:
        external_user_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Your application's unique identifier for the user. When provided,
            conversations are linked to this user for retrieval via the list
            user conversations endpoint.
          title: External User Id
        title:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            A custom title for the conversation. If not provided, the system
            will auto-generate a title after the first exchange.
          title: Title
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            Arbitrary key-value context to enrich the AI agent's responses for
            this conversation. Injected into the agent's runtime context on
            every response. Can be updated by passing metadata on subsequent
            message requests. Maximum 16KB.
          title: Metadata
      title: ConversationCreateRequest
      type: object
    ConversationSchema:
      properties:
        id:
          description: Unique identifier for the conversation.
          title: Id
          type: string
        object:
          default: conversation
          description: The object type. Always 'conversation'.
          title: Object
          type: string
        created_at:
          description: Unix timestamp (in seconds) of when the conversation was created.
          title: Created At
          type: integer
        external_user_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The external user identifier associated with this conversation, if
            one was provided at creation.
          title: External User Id
        title:
          anyOf:
            - type: string
            - type: 'null'
          description: The custom title set for this conversation, if any.
          title: Title
        generated_title:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          description: >-
            AI-generated conversation title in supported locales. Keys are
            locale codes (e.g. 'en-ca', 'fr-ca').
          example:
            en-ca: <generated title in English>
            fr-ca: <generated title in French>
          title: Generated Title
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            The latest metadata snapshot associated with this conversation, if
            any has been provided.
          title: Metadata
      required:
        - id
        - created_at
      title: ConversationSchema
      type: object
    OpenAIErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/OpenAIErrorDetail'
          description: The error detail object.
      required:
        - error
      title: OpenAIErrorSchema
      type: object
    OpenAIErrorDetail:
      properties:
        message:
          description: A human-readable description of the error.
          title: Message
          type: string
        type:
          description: >-
            The error type identifier (e.g. 'invalid_api_key', 'not_found',
            'rate_limit_exceeded').
          title: Type
          type: string
        param:
          anyOf:
            - type: string
            - type: 'null'
          description: The parameter that caused the error, if applicable.
          title: Param
        code:
          anyOf:
            - type: string
            - type: 'null'
          description: An error code providing additional detail, if applicable.
          title: Code
      required:
        - message
        - type
      title: OpenAIErrorDetail
      type: object
  securitySchemes:
    AppsApiKeyAuth:
      type: http
      scheme: bearer

````