CoreStory OLD_conversations API

openapi: 3.2.0
info:
  title: Crowdbotics API Documentation OLD Conversations API
  description: '# CoreStory API Overview


    The CoreStory API provides programmatic access to structured insights derived from software source code.'
  version: 1.26.2
servers:
- url: /
  description: Current server
security:
- BearerAuth: []
tags:
- name: OLD_conversations
paths:
  /api/projects/{project_id}/chat/conversations/list:
    get:
      tags:
      - OLD_conversations
      summary: 'DEPRECATED: Get all Project''s conversations for a User with pagination'
      description: 'DEPRECATED: Use GET / instead. Retrieve all conversations related to the Project for a User.'
      operationId: list_conversations_deprecated
      deprecated: true
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: Number of items per page
          default: 100
          title: Limit
        description: Number of items per page
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of items to skip
          default: 0
          title: Offset
        description: Number of items to skip
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedConversationListResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/chat/conversations/{conversation_id}/settings:
    get:
      tags:
      - OLD_conversations
      summary: Get conversation settings
      description: 'Retrieve persona and context scope settings for a conversation. DEPRECATED: Settings are now embedded in ConversationResponse from GET /{conversation_id}.'
      operationId: get_conversation_settings
      deprecated: true
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: integer
          title: Conversation Id
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationSettingsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
    patch:
      tags:
      - OLD_conversations
      summary: Update conversation settings
      description: 'Update persona and/or context scope for a conversation. DEPRECATED: Use PATCH /{conversation_id} instead.'
      operationId: update_conversation_settings
      deprecated: true
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: integer
          title: Conversation Id
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationSettingsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationSettingsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/chat/conversations/create-conversation:
    post:
      tags:
      - OLD_conversations
      summary: 'DEPRECATED: Create a new conversation'
      description: 'DEPRECATED: Use POST / instead. Create a new conversation for a specific project and user.'
      operationId: create_conversation_deprecated
      deprecated: true
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/chat/conversations/{conversation_id}/new-message:
    post:
      tags:
      - OLD_conversations
      summary: 'DEPRECATED: Add a chat message to a conversation'
      description: 'DEPRECATED: Use POST /{conversation_id}/messages instead.'
      operationId: add_chat_message_deprecated
      deprecated: true
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: conversation_id
        in: path
        required: true
        schema:
          type: integer
          title: Conversation Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
      responses:
        '200':
          description: Server-Sent Events (SSE) stream of JSON objects.
          content:
            text/event-stream:
              schema:
                $defs:
                  StreamEventType:
                    description: 'Types of events streamed to the frontend during chat/agent operations.


                      These events are emitted as Server-Sent Events (SSE) during orchestrator execution

                      and provide real-time progress updates to the frontend.'
                    enum:
                    - plan
                    - task_start
                    - task_complete
                    - continuation
                    - token
                    - reasoning
                    - reasoning_complete
                    - streaming_done
                    - synthesis_corrected
                    - sources
                    - title
                    - results_available
                    - plan_available
                    - error
                    - step_evaluation
                    - workflow_updated
                    - done
                    title: StreamEventType
                    type: string
                description: 'Event model for streaming responses from chat/agent operations.


                  This model represents various event types that can be streamed to the frontend

                  during orchestrator execution. The event_type field determines which additional

                  fields are relevant for each event.'
                properties:
                  event_type:
                    $ref: '#/$defs/StreamEventType'
                    default: token
                  delta:
                    default: ''
                    description: Token content (for token/reasoning events)
                    title: Delta
                    type: string
                  seq:
                    description: Sequence number for ordering events
                    title: Seq
                    type: integer
                  conversation_id:
                    description: ID of the conversation this event belongs to
                    title: Conversation Id
                    type: integer
                  project_id:
                    description: ID of the project this event belongs to
                    title: Project Id
                    type: integer
                  title:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: Conversation title (for title events)
                    title: Title
                  has_sources:
                    anyOf:
                    - type: boolean
                    - type: 'null'
                    default: false
                    description: Whether the message has source file references (for done events)
                    title: Has Sources
                  summary:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: Reasoning summary text (for reasoning_complete events)
                    title: Summary
                  message_id:
                    anyOf:
                    - type: integer
                    - type: 'null'
                    description: ID of the chat message this event belongs to (for done events)
                    title: Message Id
                  error_code:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: Error code or type (for error events)
                    title: Error Code
                  error_message:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: Detailed error message (for error events)
                    title: Error Message
                required:
                - seq
                - conversation_id
                - project_id
                title: TokenEvent
                type: object
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
components:
  schemas:
    ConversationCreateRequest:
      properties:
        title:
          type: string
          title: Title
        context:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Context
        persona:
          anyOf:
          - $ref: '#/components/schemas/ChatPersona'
          - type: 'null'
        context_scope:
          anyOf:
          - $ref: '#/components/schemas/ContextScope'
          - type: 'null'
      type: object
      required:
      - title
      title: ConversationCreateRequest
      description: Request model for creating a conversation
    FeedbackType:
      type: string
      enum:
      - thumbs_up
      - thumbs_down
      title: FeedbackType
      description: Types of user feedback
    ImportStatus:
      type: string
      enum:
      - original
      - pending
      - in_progress
      - completed
      - failed
      title: ImportStatus
    ConversationMeta:
      properties:
        message_count:
          type: integer
          title: Message Count
          description: Total number of messages in the conversation
          default: 0
        last_message_preview:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Message Preview
          description: Preview of the last message content (up to 100 chars)
        last_message_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Message At
          description: Timestamp of the last message
      type: object
      title: ConversationMeta
      description: Metadata about conversation messages.
    ConversationOrigin:
      type: string
      enum:
      - ui
      - mcp
      title: ConversationOrigin
      description: Origin source of conversation creation
    ErrorBody:
      properties:
        message:
          type: string
          title: Message
        type:
          type: string
          title: Type
        details:
          additionalProperties: true
          type: object
          title: Details
          description: Optional extra context for the error.
      type: object
      required:
      - message
      - type
      title: ErrorBody
    ChatMessageResponse:
      properties:
        id:
          type: integer
          title: Id
          description: Chat message ID
        conversation_id:
          type: integer
          title: Conversation Id
          description: Conversation ID this message belongs to
        role:
          type: string
          title: Role
          description: Role of the message sender (e.g., 'user', 'assistant')
        content:
          type: string
          title: Content
          description: Content of the chat message
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
          description: When the message was created
        updated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Updated At
          description: When the message was last updated
        has_sources:
          type: boolean
          title: Has Sources
          description: Indicates if the message has source references
          default: false
        feedback:
          anyOf:
          - $ref: '#/components/schemas/FeedbackType'
          - type: 'null'
          description: Feedback for the message, if any
      type: object
      required:
      - id
      - conversation_id
      - role
      - content
      - created_at
      - updated_at
      - feedback
      title: ChatMessageResponse
      description: Response model for chat message data
    QueryRequest:
      properties:
        query:
          type: string
          title: Query
        reasoning_mode:
          type: boolean
          title: Reasoning Mode
          default: false
        model:
          anyOf:
          - type: string
            pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$
          - type: 'null'
          title: Model
          description: LLM model for this request (e.g. claude-sonnet-4-0, gpt-4o). Auto-detects provider from model name prefix.
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
          description: BCP-47 language code for responses (ja, es, fr-CA).
        include_source_markers:
          type: boolean
          title: Include Source Markers
          description: When true, sources are numbered ([1], [2]) and the LLM adds inline citations.
          default: false
        verify_build_claims:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Verify Build Claims
          description: Per-request override for post-synthesis build/dependency claim verification. When true, package/tool claims in the answer are cross-checked against build-manifest metadata stored during ingestion (trades streaming latency for claim accuracy). When false, verification is skipped for this request. When omitted (null), the server falls back to the BUILD_CLAIM_VERIFICATION_ENABLED environment setting.
      type: object
      required:
      - query
      title: QueryRequest
    ConversationSettingsResponse:
      properties:
        conversation_id:
          type: integer
          title: Conversation Id
        persona:
          $ref: '#/components/schemas/ChatPersona'
        context_scope:
          $ref: '#/components/schemas/ContextScope'
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        updated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Updated At
      type: object
      required:
      - conversation_id
      - persona
      - context_scope
      - created_at
      - updated_at
      title: ConversationSettingsResponse
      description: 'Response model for conversation settings (deprecated: settings now in ConversationResponse)'
    ContextScope:
      type: string
      enum:
      - automatic
      - artifacts
      - code
      title: ContextScope
      description: Context scope for knowledge retrieval
    ConversationSettingsRequest:
      properties:
        persona:
          anyOf:
          - $ref: '#/components/schemas/ChatPersona'
          - type: 'null'
        context_scope:
          anyOf:
          - $ref: '#/components/schemas/ContextScope'
          - type: 'null'
      type: object
      title: ConversationSettingsRequest
      description: 'Request model for updating conversation settings (deprecated: use UpdateConversationRequest)'
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
    ConversationResponse:
      properties:
        id:
          type: integer
          title: Id
          description: Conversation ID
        project_id:
          type: integer
          title: Project Id
          description: Project ID this conversation belongs to
        user_id:
          type: string
          format: uuid
          title: User Id
          description: User ID who owns this conversation
        title:
          type: string
          title: Title
          description: Conversation title
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
          description: When the conversation was created
        updated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Updated At
          description: When the conversation was last updated
        origin:
          $ref: '#/components/schemas/ConversationOrigin'
          description: Where the conversation originated (UI-based or MCP session)
          default: ui
        persona:
          $ref: '#/components/schemas/ChatPersona'
          description: Chat persona for this conversation
          default: general
        context_scope:
          $ref: '#/components/schemas/ContextScope'
          default: automatic
        context:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Context
          description: Additional context for the conversation
        meta:
          $ref: '#/components/schemas/ConversationMeta'
          description: Message metadata
        is_imported:
          type: boolean
          title: Is Imported
          description: Indicates if the conversation was imported
        is_read_only:
          type: boolean
          title: Is Read Only
          description: Indicates if the conversation is read-only
        import_status:
          anyOf:
          - $ref: '#/components/schemas/ImportStatus'
          - type: 'null'
          description: Import status (only present for imported conversations)
        chat_messages:
          items:
            $ref: '#/components/schemas/ChatMessageResponse'
          type: array
          title: Chat Messages
          description: 'DEPRECATED: Use GET /{conversation_id}/messages endpoint instead.'
          deprecated: true
      type: object
      required:
      - id
      - project_id
      - user_id
      - title
      - created_at
      - updated_at
      - is_imported
      - is_read_only
      title: ConversationResponse
      description: Response model for conversation data with settings and metadata
    ChatPersona:
      type: string
      enum:
      - general
      - developer
      - business_analyst
      - product_manager
      - project_manager
      - designer
      title: ChatPersona
      description: Personas for chat behavior customization
    PaginatedConversationListResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/ConversationResponse'
          type: array
          title: Results
          description: List of conversations
        count:
          type: integer
          title: Count
          description: Total number of conversations
        limit:
          type: integer
          title: Limit
          description: Items per page
        offset:
          type: integer
          title: Offset
          description: Items skipped
      type: object
      required:
      - results
      - count
      - limit
      - offset
      title: PaginatedConversationListResponse
      description: Response model for paginated conversation list
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Enter the Bearer token from Clerk authentication
x-tagGroups:
- name: Ingest Your Codebase
  tags:
  - vector_store
  - projects
  - pre_ingestion
  - reingestion
- name: Generate Code Intelligence
  tags:
  - documents
  - document_generation
  - document_formatters
  - prd
  - prd_version
  - tech_spec
  - quality_metrics
  - sample_projects
- name: Query Your Codebase
  tags:
  - conversations
  - workflows
  - discovery
  - context
  - artifacts
- name: Manage and Inspect Intelligence
  tags:
  - api_debugging
  - events
  - version
  - files
  - cache
  - token_tracking
- name: Authenticate and Manage Access
  tags:
  - clerk_authentication
  - github_webhooks
  - github_integration
  - organizations
  - api_key_management
  - mcp_token_management
  - user
- name: (Advanced) Prompt Tuning
  tags:
  - prompts
- name: MCP Protocol
  tags:
  - mcp_protocol
- name: Administration
  tags:
  - admin