Chat API

import requests
from datetime import datetime, timezone

# Fetch active conversations for a project
response = requests.get(
  "http://localhost:3000/api/chat/conversations",
  params={"status": "active", "projectId": "proj-8f3a-4b2c", "limit": 20},
)
conversations: list[dict] = response.json()

for c in conversations:
  updated = datetime.fromisoformat(c["updatedAt"].replace("Z", "+00:00"))
  age_hours = int((datetime.now(timezone.utc) - updated).total_seconds() / 3600)
  title = c.get("title") or "Untitled"
  print(f"{title} ({c['runtimeId']}) — {age_hours}h ago")

import requests

# Create a conversation with a specific model
response = requests.post(
  "http://localhost:3000/api/chat/conversations",
  json={
      "runtimeId": "claude-code",
      "projectId": "proj-8f3a-4b2c",
      "title": "Debug auth flow",
      "modelId": "sonnet",
  },
)
conversation: dict = response.json()

print(conversation["id"])      # "conv-d4e2-7b1a"
print(conversation["status"])  # "active"

import requests

# Get conversation with message count
response = requests.get("http://localhost:3000/api/chat/conversations/conv-d4e2-7b1a")
conv: dict = response.json()

print(f"{conv['title']}: {conv['messageCount']} messages")

import requests

# Switch to a faster model for quick follow-up questions
requests.patch(
  "http://localhost:3000/api/chat/conversations/conv-d4e2-7b1a",
  json={"modelId": "haiku"},
)

import requests

# Permanently delete a conversation and its messages
requests.delete("http://localhost:3000/api/chat/conversations/conv-d4e2-7b1a")

import requests

# Fetch the last 50 messages
response = requests.get(
  "http://localhost:3000/api/chat/conversations/conv-d4e2-7b1a/messages",
  params={"limit": 50},
)
messages: list[dict] = response.json()

# Use cursor-based pagination to load more
if len(messages) == 50:
  last_id: str = messages[-1]["id"]
  older_response = requests.get(
      "http://localhost:3000/api/chat/conversations/conv-d4e2-7b1a/messages",
      params={"after": last_id, "limit": 50},
  )
  older: list[dict] = older_response.json()

import requests
import json

# Send a message and process the SSE stream
response = requests.post(
  "http://localhost:3000/api/chat/conversations/conv-d4e2-7b1a/messages",
  json={"content": "What tasks are running right now?"},
  stream=True,
)

for line in response.iter_lines(decode_unicode=True):
  if not line or not line.startswith("data: "):
      continue
  event: dict = json.loads(line[6:])

  match event["type"]:
      case "delta":
          print(event["content"], end="", flush=True)
      case "status":
          print(f"[status] {event['phase']}: {event['message']}")
      case "permission_request":
          print(f"[permission] {event['toolName']}: {json.dumps(event['toolInput'])}")
          # Respond via /respond endpoint
      case "done":
          print(f"\nComplete: {event['messageId']}")
      case "error":
          print(f"Error: {event['message']}")

import requests

# Approve a permission request and save a permanent rule
requests.post(
  "http://localhost:3000/api/chat/conversations/conv-d4e2-7b1a/respond",
  json={
      "requestId": "req-b7c3-2e4f",
      "behavior": "allow",
      "alwaysAllow": True,
      "toolName": "Read",
      "toolInput": {"file_path": "/src/auth/login.ts"},
  },
)

# Deny a permission with an explanation
requests.post(
  "http://localhost:3000/api/chat/conversations/conv-d4e2-7b1a/respond",
  json={
      "requestId": "req-c8d4-3f5a",
      "behavior": "deny",
      "message": "Do not modify production config files",
  },
)

import requests
from itertools import groupby
from operator import itemgetter

# Power @-mention autocomplete with entity search
response = requests.get(
  "http://localhost:3000/api/chat/entities/search",
  params={"q": "revenue", "limit": 10},
)
results: list[dict] = response.json()["results"]

# Group results by entity type for the autocomplete dropdown
sorted_results = sorted(results, key=itemgetter("entityType"))
for entity_type, items in groupby(sorted_results, key=itemgetter("entityType")):
  print(f"{entity_type}:")
  for item in items:
      print(f"  @{item['label']} ({item['entityId']})")

import requests
from itertools import groupby
from operator import itemgetter

# Build a model picker grouped by provider
response = requests.get("http://localhost:3000/api/chat/models")
models: list[dict] = response.json()

# Group by provider
sorted_models = sorted(models, key=itemgetter("provider"))
for provider, provider_models in groupby(sorted_models, key=itemgetter("provider")):
  print(f"{provider}:")
  for m in provider_models:
      print(f"  {m['label']} [{m['tier']}] {m['costLabel']}")

import requests

# Populate the chat input with suggested prompt categories
response = requests.get("http://localhost:3000/api/chat/suggested-prompts")
categories: list[dict] = response.json()

for cat in categories:
  print(f"{cat['label']} ({cat['icon']}):")
  for p in cat["prompts"]:
      print(f"  {p['label']}")