Create Conversation And Message

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.

x-api-key: YOUR_API_KEY

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

Error Responses

400 Bad Request

The endpoint validates that message content is not empty.

{
  "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.

401 Unauthorized

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

Solution: Include a valid API key in the request header.

500 Internal Server Error

The endpoint returns this error when unexpected exceptions occur.

{
  "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.

Complete Workflow

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

Advanced Usage

With Node Context

Focus the query on specific code elements:

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:

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

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

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

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

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

Authorizations

x-api-key

string

header

required

API key authentication. Get your key from potpie settings page

Path Parameters

project_id

string

required

The project ID to query about

Query Parameters

hidden

boolean

default:true

Whether to hide this conversation from the web UI

Body

application/json

content

string

required

Your question about the codebase

agent_id

string

default:codebase_qna_agent

Agent to use (defaults to codebase_qna_agent)

node_ids

object[]

Optional node context

Show child attributes

Response

Message sent and response received

message

string

AI agent's response content

citations

string[]

Source code references used in the response

tool_calls

any[]

Tool invocations made by the agent during response generation

​Overview

​Key Benefits

​Use Cases

​Authentication

​Error Responses

​Complete Workflow

​Advanced Usage

​With Node Context

​Make Visible in UI

​Complete Integration Example

​Comparison with Standard Flow

​Troubleshooting

​When to Use Standard vs. Direct Flow

Authorizations

Path Parameters

Query Parameters

Body

Response

Overview

Key Benefits

Use Cases

Authentication

Error Responses

Complete Workflow

Advanced Usage

With Node Context

Make Visible in UI

Complete Integration Example

Comparison with Standard Flow

Troubleshooting

When to Use Standard vs. Direct Flow