Chat API Guide

Build conversational experiences powered by PILOT's knowledge graph.

Overview

The Chat API gives you access to PILOT's conversational AI, which has full context from your:

• Knowledge graph (people, projects, decisions, entities)
• Task list and RPM projects
• Email history and triage
• Calendar events
• Decision log and relationship health data

This means PILOT can answer questions like "What did I decide about the pricing model last month?" or "Who haven't I talked to in 2 weeks?" without you needing to provide context.

Basic Usage

Send a message to PILOT and get an AI response:

curl -X POST https://app.withpilot.ai/api/v1/chat \
  -H "Authorization: Bearer pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are my top priorities for today?"
      }
    ]
  }'

Response:

{
  "reply": "Based on your tasks and calendar, here are today's priorities:\n\n1. Review the Q3 proposal (due today, linked to Jaime)\n2. Reply to the BigCorp partnership email (flagged as high urgency)\n3. Weekly team sync at 2pm — prep the PILOT demo\n\nYou also have 2 relationship alerts: Patrick and Ren haven't been contacted in 10+ days."
}

Multi-Turn Conversations

Send the full conversation history in the messages array for context-aware follow-ups:

curl -X POST https://app.withpilot.ai/api/v1/chat \
  -H "Authorization: Bearer pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are my open tasks related to askSOPia?"
      },
      {
        "role": "assistant",
        "content": "You have 4 open tasks related to askSOPia:\n1. Update pricing page copy\n2. Send follow-up to Prospect A\n3. Review Patrick knowledge graph implementation\n4. Prepare direct mail batch #3"
      },
      {
        "role": "user",
        "content": "Mark the first one as done and add a new task to review the landing page analytics"
      }
    ]
  }'

PILOT understands the conversation context and can take actions (like completing tasks or creating new ones) based on your instructions.

Message Format

Each message in the messages array has two required fields:

{
  "role": "user",      // "user" or "assistant"
  "content": "Your message text"
}

Roles

• user — Your messages (the human)
• assistant — PILOT's previous responses (for multi-turn context)

What PILOT Can Do in Chat

PILOT is not just a Q&A bot. During chat, it can:

• Create tasks — "Add a task to follow up with the investor next week"
• Log decisions — "We decided to go with the freemium model, rationale is faster adoption"
• Search your graph — "What do I know about BigCorp?" or "Show me all decisions about pricing"
• Triage email — "What's urgent in my inbox?"
• Generate briefings — "Give me my morning briefing"
• Relationship health — "Who am I losing touch with?"
• Meeting prep — "Prep me for my meeting with Jaime tomorrow"

Python Example

import requests

API_KEY = "pk_live_YOUR_KEY"
BASE_URL = "https://app.withpilot.ai"

def chat(messages: list[dict]) -> str:
    response = requests.post(
        f"{BASE_URL}/api/v1/chat",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"messages": messages},
    )
    response.raise_for_status()
    return response.json()["reply"]

# Single message
reply = chat([{"role": "user", "content": "What's on my plate today?"}])
print(reply)

# Multi-turn
history = []
while True:
    user_input = input("You: ")
    if user_input.lower() in ("quit", "exit"):
        break
    history.append({"role": "user", "content": user_input})
    reply = chat(history)
    print(f"PILOT: {reply}")
    history.append({"role": "assistant", "content": reply})

Best Practices

• Keep conversation history reasonable — Send the last 10-20 messages, not the entire history
• Be specific — "What tasks are due this week for the PILOT project?" is better than "What's going on?"
• Use natural language — PILOT is designed for conversational input, not structured commands
• Action words trigger actions — "Create", "add", "mark", "schedule" will cause PILOT to take action, not just answer