> ## 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
> Create a new conversation with AI agents. Conversations maintain context across multiple messages and allow for interactive discussions about your codebase.
## Use Cases
* Start a new debugging session
* Begin a code review conversation
* Ask questions about specific parts of your codebase
* Generate test plans for a feature
* Request code changes or improvements
## Authentication
This endpoint requires API key authentication via the `x-api-key` header.
```bash theme={null}
x-api-key: YOUR_API_KEY
```
| Location | Field | Type | Required | Default | Description |
| -------- | ----------------- | -------------- | -------- | ------- | --------------------------------------------------------------------------------------------- |
| Query | `hidden` | boolean | optional | `true` | Controls visibility in the web UI. Set to `false` to show the conversation in your dashboard. |
| Body | `project_ids` | array\[string] | required | - | List of project UUIDs to include in the conversation context |
| Body | `agent_ids` | array\[string] | required | - | List of agent identifiers to enable (e.g., `["codebase_qna_agent"]`) |
| Response | `message` | string | - | - | Confirmation message indicating successful creation |
| Response | `conversation_id` | string | - | - | Unique identifier for the conversation. Use this ID to send messages. |
## Complete Workflow
```javascript TypeScript theme={null}
// Create a conversation
const response = await fetch(
'http://localhost:8001/api/v2/conversations',
{
method: 'POST',
headers: {
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
project_ids: ['550e8400-e29b-41d4-a716-446655440000'],
agent_ids: ['codebase_qna_agent']
})
}
);
const data = await response.json();
console.log('Conversation ID:', data.conversation_id);
// Use conversation_id to send messages
// See the Post Message endpoint
```
```python Python theme={null}
import requests
response = requests.post(
'http://localhost:8001/api/v2/conversations',
headers={
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'project_ids': ['550e8400-e29b-41d4-a716-446655440000'],
'agent_ids': ['codebase_qna_agent']
}
)
data = response.json()
print(f"Conversation ID: {data['conversation_id']}")
```
```bash cURL theme={null}
curl -X POST \
'http://localhost:8001/api/v2/conversations' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"project_ids": ["550e8400-e29b-41d4-a716-446655440000"],
"agent_ids": ["codebase_qna_agent"]
}'
```
## Error Responses
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
* API key doesn't match any user account
**Solution:** Include a valid API key in the request header:
```bash theme={null}
x-api-key: YOUR_API_KEY
```
The endpoint returns this error when you have exceeded your plan's usage limits.
```json theme={null}
{
"detail": "Subscription required to create a conversation."
}
```
**Causes:**
* You have reached the maximum number of conversations for your current plan
* Your subscription has expired
* Usage limits have been exceeded
**Solution:**
* Upgrade your subscription plan to increase limits
* Delete unused conversations to free up capacity
* Contact support to review your usage limits
The endpoint returns this error when unexpected exceptions occur during conversation creation.
```json theme={null}
{
"detail": "An unexpected error occurred while creating the conversation."
}
```
**Causes:**
* Database connection failures
* Invalid project or agent IDs
* Service unavailability
**Solution:** Retry the request after a brief delay. If the issue persists, contact support.
## Troubleshooting
**Problem:** Response doesn't contain expected `conversation_id`.
**Solution:**
* Check the HTTP status code (should be 200 for success)
* Verify the response body is valid JSON
* Ensure all required fields are included in the request
* Check server logs if you have access
**Problem:** Conversation created but doesn't work properly.
**Solution:**
* Verify project IDs are valid UUIDs from successful parse operations
* Use the List Projects endpoint to confirm project IDs
* Use the List Available Agents endpoint to get valid agent IDs
* Ensure at least one project and one agent are specified
## OpenAPI
````yaml POST /api/v2/conversations/
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/conversations/:
post:
tags:
- Conversations
summary: Create Conversation
description: >-
Create a new conversation with AI agents. Conversations maintain context
across multiple messages and allow for interactive discussions about
your codebase.
operationId: createConversation
parameters:
- name: hidden
in: query
required: false
description: Whether to hide this conversation from the web UI
schema:
type: boolean
default: false
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- user_id
- title
- status
- project_ids
- agent_ids
properties:
user_id:
type: string
description: >-
User identifier. The server uses the authenticated user ID
from the API key.
title:
type: string
description: >-
Name for the conversation. Pass "Untitled" to auto-generate
a name from the project.
status:
type: string
enum:
- active
- archived
- deleted
description: >-
Initial conversation status. Use "active" for a standard new
conversation.
project_ids:
type: array
items:
type: string
description: List of project IDs to include in the conversation
agent_ids:
type: array
items:
type: string
description: List of agent IDs to use in the conversation
example:
user_id: YOUR_USER_ID
title: Untitled
status: active
project_ids:
- proj_abc123def456
agent_ids:
- codebase_qna_agent
responses:
'200':
description: Conversation created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateConversationResponse'
example:
message: Conversation created successfully.
conversation_id: conv_xyz789abc123
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
components:
schemas:
CreateConversationResponse:
type: object
properties:
message:
type: string
conversation_id:
type: string
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
PaymentRequired:
description: Payment required - Subscription or usage limit issue
content:
application/json:
schema:
type: object
properties:
detail:
type: string
example:
detail: Subscription required to create a conversation
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
API key authentication. Get your key from potpie settings
page
````