Tutor chat - Hawkings

The tutor sub-API is client.activities.tutor.*. See Build an AI tutor for a full walkthrough.

Start a thread

const thread = await hk.activities.tutor.start({
  activity_id: "act_123",
  student_id: "usr_42",
  research_id: "res_...",   // optional
});

$thread = $hk->activities->tutor->start([
    'activity_id' => 'act_123',
    'student_id' => 'usr_42',
    'research_id' => 'res_...',   // optional
]);

Returns:

{
  "id": "thr_01HX9...",
  "object": "tutor_thread",
  "activity_id": "act_123",
  "student_id": "usr_42",
  "created_at": "2026-05-10T12:00:00Z"
}

Send a message

Non-streaming:

const reply = await hk.activities.tutor.send(thread.id, {
  message: "Why does time dilate at high speeds?",
});
// reply.text, reply.citations

$reply = $hk->activities->tutor->send($thread->id, [
    'message' => 'Why does time dilate at high speeds?',
]);
// $reply->text, $reply->citations

Streaming:

const stream = hk.activities.tutor.sendStream(thread.id, { message });
for await (const chunk of stream) {
  process.stdout.write(chunk.text_delta);
}

$stream = $hk->activities->tutor->sendStream($thread->id, ['message' => $message]);
foreach ($stream as $chunk) {
    echo $chunk->text_delta;
}

Read history

const history = await hk.activities.tutor.history("act_123", {
  student_id: "usr_42",
});
// history.messages: [{ role, text, citations, created_at }, ...]

$history = $hk->activities->tutor->history('act_123', [
    'student_id' => 'usr_42',
]);
// $history->messages: [{ role, text, citations, created_at }, ...]

Message object

{
  "id": "msg_01HX9...",
  "thread_id": "thr_01HX9...",
  "role": "assistant" | "user",
  "text": "...",
  "citations": [
    { "lesson_id": "lsn_...", "anchor": "p:14", "snippet": "..." }
  ],
  "created_at": "2026-05-10T12:34:56Z"
}