​
Overview

The Chat With Target Context endpoint empowers you to have dynamic, multi-turn conversations with Puppilot. It’s designed for scenarios where understanding previous interactions or external information is crucial for generating the most relevant and coherent responses. Puppilot can leverage two key pieces of information you provide:
  1. Target Context (target_context): This is an external body of text, such as a detailed transcript of a telehealth session with a pet owner, a set of case notes, or any other relevant document. Puppilot uses this as a knowledge base for the conversation.
  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.
This endpoint is ideal for in-depth discussions, follow-up questions, or any interaction where context significantly influences the desired output. Authentication: Calls to this endpoint must be authenticated using a Bearer token in the Authorization header. You can obtain this token via the User Login endpoint documented under the API Reference for Multi-Shot Endpoints.

​
How It Works

When you send a request, you provide:
  • Your current message to Puppilot.
  • The target_context you want Puppilot to reference (optional).
  • A conversation_id to maintain conversation context. 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.
Puppilot processes your message by considering both the specific context provided and the history of your conversation (maintained via conversation_id), aiming to deliver an informed and relevant response.

​
Key Use Cases

  • Analyzing Transcripts: Upload a telehealth consultation transcript as the target_context and ask Puppilot follow-up questions or request summaries based on that specific interaction.
  • Interactive Case Review: Provide patient medical records or case notes as the target_context and discuss diagnostic possibilities or treatment options with Puppilot, referencing details from the notes.
  • Iterative Information Refinement: Engage in a step-by-step dialogue with Puppilot, building upon previous interactions (maintained via conversation_id) to explore a topic thoroughly, all while keeping an external document (in target_context) as a central reference point.

​
Request

  • Endpoint: POST /chat
  • Base URL: https://agents.puppilot.co
  • Authentication: Bearer <YOUR_ACCESS_TOKEN> in the Authorization header.
  • API Versioning: Include the header X-API-Version: 0.2.0 in your requests.

​
Request Body

  • message (string, required): Your current question, statement, or instruction for Puppilot.
  • target_context (string, optional): The external text or transcript that Puppilot should use as a reference for this conversational turn. This provides the background information.
  • 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)

This example shows a user starting a new conversation by asking for guidance on urgent signs for a rabbit named Nibbles, providing the vet-owner chat transcript as context. 
{
  "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)

This example shows a follow-up question in the same conversation, using the conversation_id from the previous response. 
{
  "message": "What about home care options?",
  "conversation_id": "conv_1234567890abcdef"
}

​
Response

​
Successful Response (200 OK)

A successful request will return a JSON object containing Puppilot’s response.
  • output (string): Puppilot’s generated textual response, informed by your message, the target_context, and the conversation history (maintained via conversation_id).
  • conversation_id (string): The unique identifier for this conversation. Use this conversation_id in all subsequent requests to maintain conversation context.

​
Example Successful Response

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

​
Error Responses

The API uses standard HTTP status codes to indicate the success or failure of a request.
  • 400 Bad Request: This may indicate that your request was malformed, such as missing required fields (e.g., message) or if the JSON structure is invalid. Example: 
    {
  "detail": "Missing required field: message"
}
  • 401 Unauthorized: This error means that the Authorization header was missing or contained an invalid or expired Bearer token. Example: 
    {
  "detail": "Invalid or expired token"
}
  • 5xx Server Error: If Puppilot encounters an internal issue while processing your request, a 5xx error may be returned. This usually indicates a problem on our end, and we appreciate it if you report such occurrences.