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

# Create Conversation And Message

> Convenience endpoint that creates a new conversation and sends a message in a single request.
Perfect for one-off queries or integrating Potpie into external tools.

**Use Cases:**
- Quick code questions without managing conversations
- Integration with CI/CD pipelines
- Chatbot integrations
- API-first workflows


## Overview

Create a new conversation and send the first message in a single API call. This streamlined endpoint is perfect for quick interactions where you want to ask a question about your codebase without managing conversation state.

## Key Benefits

* **Simplified Workflow**: Combine conversation creation and messaging in one request
* **Auto-hidden Conversations**: Conversations are automatically hidden from the UI (configurable)
* **Default Agent**: Uses the Q\&A agent by default for codebase queries
* **Immediate Response**: Get AI responses without managing conversation IDs

## Use Cases

* Quick codebase queries without managing conversations
* Automated analysis scripts
* CI/CD integration for code insights
* Stateless API integrations
* One-off questions about specific projects

## Authentication

This endpoint requires API key authentication via the `x-api-key` header.

```bash theme={null}
x-api-key: YOUR_API_KEY
```

<AccordionGroup>
  <Accordion title="Request & Response">
    | Location | Field        | Type           | Required | Default              | Description                                                    |
    | -------- | ------------ | -------------- | -------- | -------------------- | -------------------------------------------------------------- |
    | Path     | `project_id` | string         | required | -                    | The ID of the project to query about                           |
    | Query    | `hidden`     | boolean        | optional | `true`               | Whether to hide this conversation from the web UI              |
    | Body     | `content`    | string         | required | -                    | The message content to send (your question about the codebase) |
    | Body     | `agent_id`   | string         | optional | `codebase_qna_agent` | The ID of the agent to use                                     |
    | Body     | `node_ids`   | array\[object] | optional | -                    | Array of node context objects to focus the conversation        |
    | Response | `message`    | string         | -        | -                    | AI agent's response content                                    |
    | Response | `citations`  | array\[string] | -        | -                    | Source code references used in the response                    |
    | Response | `tool_calls` | array          | -        | -                    | Tool invocations made by the agent during response generation  |
  </Accordion>
</AccordionGroup>

## Error Responses

<AccordionGroup>
  <Accordion title="400 Bad Request">
    The endpoint validates that message content is not empty.

    ```json theme={null}
    {
      "detail": "Message content cannot be empty"
    }
    ```

    **Causes:**

    * Empty string provided in `content` field
    * Whitespace-only content
    * Missing `content` field

    **Solution:** Provide non-empty message content.
  </Accordion>

  <Accordion title="401 Unauthorized">
    The endpoint requires a valid API key for authentication.

    ```json theme={null}
    {
      "detail": "API key is required"
    }
    ```

    **Causes:**

    * Missing `x-api-key` header
    * Invalid or expired API key

    **Solution:** Include a valid API key in the request header.
  </Accordion>

  <Accordion title="500 Internal Server Error">
    The endpoint returns this error when unexpected exceptions occur.

    ```json theme={null}
    {
      "detail": "An unexpected error occurred while creating the conversation."
    }
    ```

    **Causes:**

    * Invalid project ID
    * Project not yet ready (still parsing)
    * Database connection failures
    * Invalid agent ID

    **Solution:** Verify project ID is valid and project has completed parsing. Retry after a brief delay.
  </Accordion>
</AccordionGroup>

## Complete Workflow

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Quick codebase query
  const response = await fetch(
    `http://localhost:8001/api/v2/project/${projectId}/message/`,
    {
      method: 'POST',
      headers: {
        'x-api-key': process.env.POTPIE_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        content: 'Explain how the authentication system works',
        agent_id: 'codebase_qna_agent'
      })
    }
  );

  const answer = await response.json();
  console.log(answer);
  ```

  ```python Python theme={null}
  # Quick question about your codebase
  response = requests.post(
      f'http://localhost:8001/api/v2/project/{project_id}/message/',
      headers={
          'x-api-key': os.environ["POTPIE_API_KEY"],
          'Content-Type': 'application/json'
      },
      json={
          'content': 'What are the main API endpoints in this project?',
          'agent_id': 'codebase_qna_agent'
      }
  )

  answer = response.json()
  print(answer)
  ```

  ```bash cURL theme={null}
  curl -X POST \
    "http://localhost:8001/api/v2/project/${PROJECT_ID}/message/" \
    -H 'x-api-key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "content": "Show me the database schema",
      "agent_id": "codebase_qna_agent"
    }'
  ```
</CodeGroup>

## Advanced Usage

### With Node Context

Focus the query on specific code elements:

```typescript theme={null}
const response = await fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify({
    content: 'How does this function handle errors?',
    node_ids: [
      {
        node_id: 'func_process_payment_xyz',
        name: 'processPayment'
      }
    ]
  })
});
```

### Make Visible in UI

Create a conversation that appears in the web interface:

```bash theme={null}
curl -X POST \
  "http://localhost:8001/api/v2/project/${PROJECT_ID}/message/?hidden=false" \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "Review the security implementation"
  }'
```

## Complete Integration Example

```python theme={null}
class PotpieQuickQuery:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = 'http://localhost:8001'

    def ask_codebase(self, project_id: str, question: str, agent_id: str = None):
        """
        Ask a quick question about your codebase.
        Returns the AI response directly.
        """
        url = f'{self.base_url}/api/v2/project/{project_id}/message/'

        payload = {'content': question}
        if agent_id:
            payload['agent_id'] = agent_id

        response = requests.post(
            url,
            headers={
                'x-api-key': self.api_key,
                'Content-Type': 'application/json'
            },
            json=payload
        )

        response.raise_for_status()
        return response.json()

# Usage
client = PotpieQuickQuery(api_key='your-api-key')
answer = client.ask_codebase(
    project_id='proj_123',
    question='What design patterns are used in this codebase?'
)
print(answer)
```

## Comparison with Standard Flow

| Feature         | Create Conversation + Message | Direct Message (This Endpoint) |
| --------------- | ----------------------------- | ------------------------------ |
| API Calls       | 2 separate calls              | 1 combined call                |
| Conversation ID | You manage it                 | Automatically managed          |
| UI Visibility   | Configurable                  | Hidden by default              |
| Use Case        | Multi-turn conversations      | Quick queries                  |
| Complexity      | Higher                        | Lower                          |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Project not ready">
    **Problem:** Error occurs even with valid project ID.

    **Solution:**

    * Check the project's parsing status using the Get Parsing Status endpoint
    * Wait for parsing to complete before sending messages
    * Ensure the project status is "ready" before querying
  </Accordion>

  <Accordion title="Response takes too long">
    **Problem:** Request times out or takes very long.

    **Solution:**

    * Complex queries may take longer to process
    * Implement appropriate timeout values (30-60 seconds recommended)
    * Consider breaking complex questions into simpler ones
    * Check if the project is very large
  </Accordion>
</AccordionGroup>

## When to Use Standard vs. Direct Flow

**Use This Endpoint When:**

* Making quick, one-off queries
* Building stateless integrations
* Automating codebase analysis
* Don't need conversation history

**Use Standard Flow When:**

* Building interactive chat experiences
* Need multi-turn conversations
* Managing conversation history
* Require fine-grained control over conversation state


## OpenAPI

````yaml POST /api/v2/project/{project_id}/message/
openapi: 3.1.0
info:
  title: Potpie API
  version: 2.0.0
  description: >-
    AI-powered codebase intelligence API. Build powerful integrations with
    Potpie's parsing, conversation, search, and agent capabilities.
  contact:
    name: Potpie Support
    email: hi@potpie.ai
    url: https://potpie.ai
  license:
    name: Proprietary
    url: https://potpie.ai/terms
servers:
  - url: http://localhost:8001
    description: Local server
security:
  - ApiKeyAuth: []
tags:
  - name: Parsing
    description: Repository parsing and status management
  - name: Projects
    description: Project management and listing
  - name: Conversations
    description: AI conversation management
  - name: Agents
    description: AI agent information and selection
  - name: Search
    description: Codebase semantic search
  - name: Integrations
    description: External service integrations
paths:
  /api/v2/project/{project_id}/message/:
    post:
      tags:
        - Conversations
      summary: Create Conversation And Message
      description: >-
        Create a new conversation and send a message in a single API call.
        Perfect for quick, one-off queries without managing conversation state.
        The conversation is automatically hidden from the UI by default.
      operationId: createConversationAndMessage
      parameters:
        - name: project_id
          in: path
          required: true
          description: The project ID to query about
          schema:
            type: string
          example: proj_abc123def456
        - name: hidden
          in: query
          required: false
          description: Whether to hide this conversation from the web UI
          schema:
            type: boolean
            default: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - content
              properties:
                content:
                  type: string
                  description: Your question about the codebase
                agent_id:
                  type: string
                  description: Agent to use (defaults to codebase_qna_agent)
                  default: codebase_qna_agent
                node_ids:
                  type: array
                  items:
                    $ref: '#/components/schemas/NodeContext'
                  description: Optional node context
            examples:
              quick_query:
                summary: Quick query
                value:
                  content: What are the main API endpoints?
              with_agent:
                summary: With specific agent
                value:
                  content: What changed in the auth module?
                  agent_id: debugging_agent
      responses:
        '200':
          description: Message sent and response received
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: AI agent's response content
                  citations:
                    type: array
                    items:
                      type: string
                    description: Source code references used in the response
                  tool_calls:
                    type: array
                    items: {}
                    description: >-
                      Tool invocations made by the agent during response
                      generation
              example:
                message: The main API endpoints are...
                citations:
                  - src/api/router.py
                tool_calls: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    NodeContext:
      type: object
      required:
        - node_id
        - name
      properties:
        node_id:
          type: string
          description: Node identifier from the knowledge graph
        name:
          type: string
          description: Name of the code element
  responses:
    BadRequest:
      description: Bad request - Invalid parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
          example:
            detail: Either repo_name or repo_path must be provided
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
          example:
            detail: Invalid API key
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key authentication. Get your key from <a
        href="https://app.potpie.ai/settings" style="color: #60a5fa;
        font-weight: bold; text-decoration: none !important;">potpie settings
        page</a>

````