Skip to main content
POST
/
api
/
v2
/
conversations
Create Conversation
curl --request POST \
  --url http://localhost:8001/api/v2/conversations/ \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "user_id": "YOUR_USER_ID",
  "title": "Untitled",
  "status": "active",
  "project_ids": [
    "proj_abc123def456"
  ],
  "agent_ids": [
    "codebase_qna_agent"
  ]
}
'
{
  "message": "Conversation created successfully.",
  "conversation_id": "conv_xyz789abc123"
}

​
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. 
x-api-key: YOUR_API_KEY
LocationFieldTypeRequiredDefaultDescription
QueryhiddenbooleanoptionaltrueControls visibility in the web UI. Set to false to show the conversation in your dashboard.
Bodyproject_idsarray[string]required-List of project UUIDs to include in the conversation context
Bodyagent_idsarray[string]required-List of agent identifiers to enable (e.g., ["codebase_qna_agent"])
Responsemessagestring--Confirmation message indicating successful creation
Responseconversation_idstring--Unique identifier for the conversation. Use this ID to send messages.

​
Complete Workflow

// 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

​
Error Responses

The endpoint requires a valid API key for authentication.
{
  "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:
x-api-key: YOUR_API_KEY
The endpoint returns this error when you have exceeded your plan’s usage limits.
{
  "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.
{
  "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

Authorizations

​
x-api-key
string
header
required

API key authentication. Get your key from potpie settings page

Query Parameters

​
hidden
boolean
default:false

Whether to hide this conversation from the web UI

Body

application/json
​
user_id
string
required

User identifier. The server uses the authenticated user ID from the API key.

​
title
string
required

Name for the conversation. Pass "Untitled" to auto-generate a name from the project.

​
status
enum<string>
required

Initial conversation status. Use "active" for a standard new conversation.

Available options:
active,
archived,
deleted
​
project_ids
string[]
required

List of project IDs to include in the conversation

​
agent_ids
string[]
required

List of agent IDs to use in the conversation

Response

Conversation created successfully

​
message
string
​
conversation_id
string