POST
/
chat
Agent Chat with Target Context
curl --request POST \
  --url https://agents.puppilot.co/chat \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Version: <x-api-version>' \
  --data '{
  "message": "Yes please provide guidance on urgent signs",
  "target_context": "Owner: Hi, my rabbit Nibbles has been acting strangely... Vet: Thank you, that'\''s very helpful.",
  "conversation_id": "conv_1234567890abcdef"
}'
{
  "output": "For Nibbles, urgent veterinary signs include: no fecal output or very small, dry pellets >24 hrs...",
  "conversation_id": "conv_1234567890abcdef"
}

​
Overview

This endpoint allows for multi-turn conversational interactions with Puppilot. It is designed for continuous dialogue where Puppilot can reference:
  1. A Target Context: This is an external piece of information you provide, such as a transcript of a conversation between a pet owner and a veterinarian. Puppilot can use this context to inform its responses.
  2. Chat History: The backend automatically maintains the history of your conversation with Puppilot using a unique conversation_id. This allows for natural, connected dialogue across multiple requests.
Authentication is required for this endpoint. You must include a Bearer token (obtained via the authentication endpoint) in the Authorization header of your request. Additionally, you must include the header X-API-Version: 0.2.0 in your requests.

​
Request Body

  • message (string, required): The latest message or query from the user.
  • target_context (string, optional): A string containing the target contextual information that Puppilot should be aware of. For example, this could be a detailed case history or a prior conversation transcript.
  • conversation_id (string, optional): For the first request, omit this field and the API will generate a new conversation_id. Include this in subsequent requests to maintain conversation context.

​
Example Request (First Request)

{
  "message": "Please provide guidance on urgent signs",
  "target_context": "Owner: Hi, my rabbit Nibbles has been acting strangely—she's not eating her hay and just sits in the corner of her cage. Vet: I'm sorry to hear that—how long has she been like this? Owner: Since yesterday afternoon. She usually runs to me when I open the cage but now she just stays still. Vet: Has she passed any stool or urine in the last 24 hours? Owner: Very little stool, and it looks smaller than usual. I haven't noticed any urine. Vet: Any signs of drooling, teeth grinding, or discomfort when you touch her belly? Owner: She did grind her teeth a little last night and flinched when I tried to pick her up. Vet: Has her diet changed recently, or could she have chewed on anything unusual? Owner: No diet changes, but she might have nibbled a bit of cardboard from her play area. Vet: Is she usually free-roaming, or has she had any recent stress—like a loud noise or new pet? Owner: She's free-roaming in the afternoons, and my nephew was over a couple days ago—he was a bit loud. Vet: How old is Nibbles and has she had any history of dental or digestive issues? Owner: She's 3 and has never had any problems until now. Vet: Thank you, that's very helpful."
}

​
Example Request (Subsequent Request)

{
  "message": "What about home care options?",
  "conversation_id": "conv_1234567890abcdef"
}

​
Response (200 OK)

  • output (string): Puppilot’s response to the user’s message, taking into account the provided target_context and chat history.
  • conversation_id (string): The unique identifier for this conversation. Use this conversation_id in all subsequent requests to maintain conversation context.

​
Example Response (200 OK)

{
    "output": "For Nibbles, urgent veterinary signs include: no fecal output or very small, dry pellets >24 hrs; no urination or urinary obstruction signs; severe lethargy/unresponsiveness; worsening anorexia despite care; severe pain (teeth grinding, vocalizing, flinching); abdominal bloating; labored/rapid breathing; collapse or inability to stand. Immediate vet care is critical to prevent serious complications.",
    "conversation_id": "conv_1234567890abcdef"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
X-API-Version
string
required

API versioning is required. Include the header X-API-Version with current version value in all requests.

Example:

"0.2.0"

Body

application/json
​
message
string
required

The latest message input from the user to Puppilot.

Example:

"Yes please provide guidance on urgent signs"

​
target_context
string

The target context for the chat, e.g., a transcript of a conversation between an owner and a vet.

Example:

"Owner: Hi, my rabbit Nibbles has been acting strangely... Vet: Thank you, that's very helpful."

​
conversation_id
string

A unique identifier for the conversation. For the first request, omit this field and the API will generate a new conversation_id. For all subsequent requests, use the conversation_id returned in the previous response.

Example:

"conv_1234567890abcdef"

Response

Successful response from the chat agent.

​
output
string
required

The agent's response message.

Example:

"For Nibbles, urgent veterinary signs include: no fecal output or very small, dry pellets >24 hrs..."

​
conversation_id
string

The unique identifier for this conversation. Use this conversation_id in all subsequent requests to maintain conversation context.

Example:

"conv_1234567890abcdef"