Post Message

Send a message to an existing conversation. The AI agent will respond based on the conversation context and your codebase knowledge graph.

POST /api/v2/conversations/{conversation_id}/message/

cURL

simple

curl --request POST \
  --url http://localhost:8001/api/v2/conversations/{conversation_id}/message/ \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-key: <api-key>' \
  --form 'content=How does the authentication system work?' \
  --form images.items='@example-file'

200

{
  "message": "The authentication system uses JWT tokens...",
  "citations": [
    "src/auth/jwt.ts",
    "src/middleware/auth.ts"
  ],
  "tool_calls": []
}

Use Cases

• Ask questions about your codebase
• Request debugging assistance
• Get explanations of code functionality
• Ask for code improvements or refactoring suggestions
• Inquire about code relationships and dependencies

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	conversation_id	string	required	-	The unique identifier of the conversation (obtained from Create Conversation endpoint)
Query	stream	boolean	optional	true	Stream response in real-time. Set to false for complete response.
Query	session_id	string	optional	null	Session ID for reconnection to existing streaming session
Query	prev_human_message_id	string	optional	null	Previous message ID for deterministic session handling
Query	cursor	string	optional	null	Stream cursor position for replay functionality
Form	content	string	required	-	Your message or question. Cannot be empty or whitespace-only.
Form	node_ids	string	optional	-	JSON-encoded array of NodeContext objects to reference specific code nodes
Form	tunnel_url	string	optional	-	VS Code extension tunnel URL for local server routing
Form	attachment_ids	string	optional	-	JSON-encoded array of pre-uploaded attachment ID strings to include with your message
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

NodeContext Object Structure:

{
  "node_id": "string",
  "name": "string"
}

Request Form Data Example:

content=How does the authentication system work?
node_ids=[{"node_id":"node_123","name":"auth.ts"}]

Node Context

Providing node_ids helps the agent focus on specific parts of your codebase. Because the endpoint uses multipart/form-data, pass node_ids as a JSON-encoded string in the form field:

content=How does this authentication function work?
node_ids=[{"node_id":"node_123","name":"AuthService.authenticate"},{"node_id":"node_456","name":"TokenValidator"}]

You can find node IDs by using the Search Codebase endpoint or through the Potpie UI.

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 entirely

Solution: Provide non-empty message content:

{
  "content": "How does authentication work?"
}

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.

402 Payment Required

The endpoint returns this error when you have exceeded your plan’s usage limits.

{
  "detail": "Subscription required to create a conversation."
}

Causes:

• Message limit exceeded for your current plan
• Subscription has expired

Solution: Upgrade your subscription plan or wait for limits to reset.

404 Not Found

The endpoint returns this error when the conversation doesn’t exist or you lack access.

{
  "detail": "Conversation not found"
}

Causes:

• Invalid conversation_id in URL path
• Conversation was deleted
• You don’t have access to this conversation

Solution: Verify the conversation ID and ensure you have proper access permissions.

500 Internal Server Error

The endpoint returns this error when unexpected exceptions occur during message processing.

{
  "detail": "Internal server error"
}

Causes:

• Celery worker unavailable for message processing
• Database connection failures
• Invalid node IDs or attachment IDs

Solution: Retry the request after a brief delay. Verify all node IDs and attachment IDs are valid.

Complete Workflow

TypeScript

const formData = new FormData();
formData.append('content', 'How does the authentication flow work in this codebase?');
// Optionally attach node context as a JSON string:
// formData.append('node_ids', JSON.stringify([{ node_id: 'node_123', name: 'AuthService' }]));

const response = await fetch(
  'http://localhost:8001/api/v2/conversations/conv_789/message/?stream=false',
  {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY'
      // Do not set Content-Type — the browser sets it automatically with the multipart boundary
    },
    body: formData
  }
);

const data = await response.json();
console.log('Response:', data.message);

Message Types

Different message patterns for different tasks:

Question & Answer

"What does the parseUserData function do?"
"Where is the JWT token validated?"
"How are database migrations handled?"

Debugging

"I'm getting 'TypeError: Cannot read property...' in UserService"
"Why is the authentication failing for OAuth users?"
"The cache is not invalidating properly, can you investigate?"

Code Review

"Review the error handling in the payment service"
"Is the API endpoint properly secured?"
"Suggest improvements for the authentication middleware"

Response Streaming

When stream=true (the default), the endpoint returns a streaming response via Server-Sent Events. Each event chunk contains a partial or complete agent response. When stream=false, the endpoint returns a single JSON object with the complete response:

{
  "message": "The authentication system uses JWT tokens...",
  "citations": ["src/auth/jwt.ts", "src/middleware/auth.ts"],
  "tool_calls": []
}

Authorizations

x-api-key · string · header · required

API key authentication. Get your key from potpie settings page

Path Parameters

conversation_id · string · required

The conversation ID to send the message to

Query Parameters

stream · boolean · default: true

Whether to stream the response

Body

multipart/form-data

content · string · required

Your message or question. Cannot be empty or whitespace-only.

Minimum string length: 1

node_ids · string

JSON-encoded array of NodeContext objects to reference specific code nodes. Example: [{"node_id":"node_123","name":"AuthService"}]

tunnel_url · string

VS Code extension tunnel URL for local server routing

images · file[]

Image attachments to include with your message

Response

200

application/json

Message sent successfully 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