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

# Create Thread

> Opens a new conversation session backed by a Custom Agent. Returns the conversationId required for the streaming endpoint.



## OpenAPI

````yaml POST /ai/api/v2/conversations
openapi: 3.1.0
info:
  title: DataGOL Custom Agents API
  description: >-
    Complete API for creating, configuring, sharing, and interacting with Custom
    AI Agents on the DataGOL platform. Covers agent CRUD, permissions,
    conversations, and streaming.
  version: 1.0.0
  contact:
    name: DataGOL Support
    url: https://datagol.ai
servers:
  - url: https://be.datagol.ai
    description: Backend API (Production) — agent management, conversations, permissions
  - url: https://ai.datagol.ai
    description: AI Core (Production) — streaming, chat completion, conversation naming
security:
  - ServiceAccountAuth: []
  - BearerAuth: []
tags:
  - name: Custom Agents
    description: Create, read, and manage Custom AI Agents.
  - name: Permissions
    description: View and manage who has access to an agent.
  - name: Conversations
    description: Open and list conversation sessions backed by an agent.
  - name: Messaging
    description: Send messages and stream AI responses.
  - name: Reference Data
    description: >-
      Lookup APIs for workspaces, connectors, and team members used when
      building agent configs.
paths:
  /ai/api/v2/conversations:
    post:
      tags:
        - Conversations
      summary: Create Thread
      description: >-
        Opens a new conversation session backed by a Custom Agent. Returns the
        conversationId required for the streaming endpoint.
      operationId: initiateConversation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateConversationRequest'
            example:
              name: Data Summary Request
              agentType: CustomAgent
              uiMetadata:
                type: CustomAgent
                parameters:
                  customAgentId: 1526da2b-3264-4118-b141-87857369b0bd
                configuration:
                  llmModel: gpt-5.2
      responses:
        '200':
          description: >-
            Conversation created. Contains conversationId for the streaming
            endpoint.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: conversationId — pass to the streaming endpoint.
                  name:
                    type: string
                  scope:
                    type: string
                  agentType:
                    type: string
                  active:
                    type: boolean
components:
  schemas:
    InitiateConversationRequest:
      type: object
      required:
        - name
        - agentType
        - uiMetadata
      properties:
        name:
          type: string
          description: Display name for this conversation.
          example: Data Summary Request
        agentType:
          type: string
          enum:
            - CustomAgent
          description: Must be CustomAgent for custom agent conversations.
        uiMetadata:
          type: object
          required:
            - type
            - parameters
            - configuration
          properties:
            type:
              type: string
              enum:
                - CustomAgent
            parameters:
              type: object
              properties:
                customAgentId:
                  type: string
                  format: uuid
                  description: UUID of the Custom Agent backing this conversation.
                  example: 1526da2b-3264-4118-b141-87857369b0bd
            configuration:
              type: object
              properties:
                llmModel:
                  type: string
                  description: >-
                    Active LLM model for this conversation. Must be in the
                    agent's supportedModels.
                  example: gpt-5.2
  securitySchemes:
    ServiceAccountAuth:
      type: apiKey
      in: header
      name: x-auth-token
      description: >
        For server-to-server or automated access, use a DataGOL Service Account
        key.
                Pass it via the `x-auth-token` header instead of `Authorization`:
                `x-auth-token: <service-account-key>`
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        JWT token issued by the DataGOL Identity Provider. Embed `Authorization:
        Bearer <token>` in every request. Tokens contain `companyId`, `userId`,
        `roles`, and `permissions` claims.

````