Skip to main content
POST
/
api
/
v2
/
conversations
/
{conversation_id}
/
message
curl --request POST \
  --url https://production-api.potpie.ai/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'
{
  "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
LocationFieldTypeRequiredDefaultDescription
Pathconversation_idstringrequired-The unique identifier of the conversation (obtained from Create Conversation endpoint)
QuerystreambooleanoptionaltrueStream response in real-time. Set to false for complete response.
Querysession_idstringoptionalnullSession ID for reconnection to existing streaming session
Queryprev_human_message_idstringoptionalnullPrevious message ID for deterministic session handling
QuerycursorstringoptionalnullStream cursor position for replay functionality
Formcontentstringrequired-Your message or question. Cannot be empty or whitespace-only.
Formnode_idsstringoptional-JSON-encoded array of NodeContext objects to reference specific code nodes
Formtunnel_urlstringoptional-VS Code extension tunnel URL for local server routing
Fileimagesfile[]optional-Image attachments to include with your message
Responsemessagestring--AI agent’s response content
Responsecitationsarray[string]--Source code references used in the response
Responsetool_callsarray--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

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?"
}
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.
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.
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.
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

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(
  'https://production-api.potpie.ai/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

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