--- title: "Ask Heph" method: POST path: "/workspaces/{workspaceSlug}/mentor/turns" tags: ["Mentor"] --- # Ask Heph `POST /workspaces/{workspaceSlug}/mentor/turns` ## Request - Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin) - URL: `/workspaces/{workspaceSlug}/mentor/turns` - Auth: HTTP bearer Stores the question before anything is shown and queues a turn. A question while Heph answers waits as a follow-up. Repeating a requestId returns the first submission. ## Path parameters - `workspaceSlug` string, required ## Request body - MentorTurnRequest: A question to Heph from the app - `pageContext` string: The page the developer asks from, for example "Pull request #421 in acme/web" - `parentEntryId` string, uuid: Ask in the thread on this top-level message; the first reply opens the thread - `requestId` string, uuid, required: Chosen by the app for each message. Sending the same id again returns the first submission, so a retried request never asks twice. - `text` string, required: The developer's words ## Response `200` The stored question and its turn - MentorSubmission: A stored question and the turn that answers it - `question` MentorEntry, required: One message of a Heph conversation - `conversationId` string, uuid, required - `createdAt` string, date-time, required - `deleted` boolean, required: The message was deleted; its text is gone - `digest` WeeklyDigest: A weekly digest as it reads now, from the live facts - `changes` ProfileChange[], required: What changed on the Practice profile in the week; never a change of Practice page feedback, which the waiting count covers - `at` string, date-time, required - `cleanNeeded` integer, nullable, required - `direction` 'UP' | 'DOWN' | 'null', nullable, required - `evidence` ItemRef[], required - `container` string, nullable, required - `id` string, required - `kind` string, required - `label` string, required - `parentId` string, nullable, required - `path` string, nullable, required - `provider` 'GITHUB' | 'GITLAB' | 'SLACK' | 'OUTLINE' | 'null', nullable, required - `removedAt` string, date-time, nullable, required - `title` string, nullable, required - `url` string, nullable, required - `feedbackId` string, uuid, nullable, required - `from` string, nullable, required - `groupName` string, nullable, required - `groupSlug` string, nullable, required - `practiceName` string, nullable, required - `practiceSlug` string, nullable, required - `resolvedBy` 'WORK' | 'DEVELOPER' | 'null', nullable, required - `to` string, nullable, required - `type` 'FEEDBACK_NEW' | 'FEEDBACK_RESOLVED' | 'FEEDBACK_RESET' | 'STANDING_MOVED' | 'TREND_TURNED' | 'GROUP_MOVED' | 'FIRST_RECORDED', required - `feedback` WeeklyDigestFeedback[], required: Feedback delivered to the developer on the work or in conversation in the week, by practice group and practice order - `deliveredAt` string, date-time, required - `destination` 'ON_WORK' | 'PRACTICE_PAGE' | 'CONVERSATION', required: Where it was delivered: on the work (ON_WORK) or in the conversation with Heph (CONVERSATION). Practice page feedback is never listed; the waiting count covers it - `feedbackId` string, uuid, required - `groupName` string - `groupSlug` string - `item` ItemRef - `container` string, nullable, required - `id` string, required - `kind` string, required - `label` string, required - `parentId` string, nullable, required - `path` string, nullable, required - `provider` 'GITHUB' | 'GITLAB' | 'SLACK' | 'OUTLINE' | 'null', nullable, required - `removedAt` string, date-time, nullable, required - `title` string, nullable, required - `url` string, nullable, required - `mentorEntryId` string, uuid: The Heph message it appeared in; only for CONVERSATION, and never when withdrawn - `mentorParentEntryId` string, uuid: The top-level message whose thread holds that Heph message; only for CONVERSATION, and absent when the message is not in a thread - `practiceName` string, required - `practiceSlug` string, required - `replaced` boolean, required: Newer feedback replaced it since; the link opens the current feedback - `withdrawn` boolean, required: A workspace admin withdrew it; only the practice is shown - `timeZone` string, required: The IANA time zone the week was read in - `waiting` integer, required: Pieces of Practice page feedback prepared in the week that still wait unread now - `weekStart` string, date, required: The Monday the week starts on, in the developer's time zone - `windowEnd` string, date-time, required: The next Monday 00:00 in the developer's time zone - `windowStart` string, date-time, required: Monday 00:00 of the week in the developer's time zone - `editedAt` string, date-time: Set when the developer edited the message in Slack - `id` string, uuid, required - `kind` 'USER' | 'HEPH' | 'DIGEST', required - `links` MentorLink[], required: The results, problems and prepared feedback Heph showed in this message, in order - `id` string, uuid, required: The result, problem or feedback id, by kind - `itemId` integer: The item (pull request, issue, conversation or document) it is about, when the developer may still read it: a problem's through its result - `kind` 'RESULT' | 'PROBLEM' | 'FEEDBACK', required - `practiceSlug` string: The practice it is about: a problem's through its result, feedback's when it is about one practice; absent when the developer can no longer read it - `text` string, required: Heph's words about it, shown to the developer - `parentEntryId` string, uuid: Set when the message is in a thread: the top-level message the thread replies to - `requestId` string: The submission that wrote the message; the app matches its own optimistic message by it - `seq` integer, required: Order within its conversation - `slackDelivery` 'PENDING' | 'DELIVERED' | 'UNCERTAIN' | 'FAILED': Only on a question asked in Slack: whether Heph's reply reached Slack. FAILED means Slack does not show the whole reply: it is not there, or a stream showed only part of it before Slack or Silent Mode refused the rest; the full reply is in the app. UNCERTAIN means Slack cannot tell. - `surface` 'APP' | 'SLACK' | 'SYSTEM', required: Where the message was written; SYSTEM for a weekly digest - `text` string, required: The developer's words or Heph's answer; for a weekly digest, the note that points Heph to it; empty when the message was deleted - `thread` MentorThreadSummary: The thread on a top-level message - `conversationId` string, uuid, required: The thread's own conversation - `lastReplyAt` string, date-time - `latestSeq` integer, required: Sequence number of the thread's newest shown message; 0 when it has none - `parentEntryId` string, uuid, required: The message the thread replies to - `replyCount` integer, required: Messages in the thread; can count a Heph message without text whose feedback is no longer shown - `turnError` string: Why the turn this question asked failed, in words for the developer; only when it FAILED - `turnId` string, uuid: The turn the message asked or answered - `turnStatus` 'QUEUED' | 'RUNNING' | 'DONE' | 'FAILED' | 'STOPPED': The status of the turn this question asked; only on the developer's messages - `vote` 'HELPFUL' | 'NOT_HELPFUL': The developer's vote; only on Heph's messages - `turn` MentorTurn, required: One question to Heph and the work to answer it - `attempt` integer, required: Attempts started so far; 0 while the turn waits for its first start. A lost lease queues the turn again with the same attempt, and the next start counts up. Thus, with the same attempt, RUNNING comes before QUEUED or an end. - `conversationId` string, uuid, required - `createdAt` string, date-time, required - `error` string: Why the turn failed, worded for the developer; only on a failed turn - `finishedAt` string, date-time - `id` string, uuid, required - `parentEntryId` string, uuid: Set when the turn runs in a thread: the top-level message the thread replies to - `partial` MentorTurnPartial: What Heph is doing in a running turn - `activity` 'THINKING' | 'WRITING' | 'TOOL', required - `stage` string, required: What Heph is doing, in the developer's words, for example "Reading your practice feedback…" - `text` string, required: The text Heph has written in this turn so far - `tool` string: The tool Heph runs, while the activity is TOOL - `requestId` string, required: The submission that asked; the question's entry carries the same value - `status` 'QUEUED' | 'RUNNING' | 'DONE' | 'FAILED' | 'STOPPED', required - `surface` 'APP' | 'SLACK', required ## Other responses - `409`: Heph declines the developer (mentor-refused), too many follow-ups wait, the requestId was used for another message, or the parent cannot have a thread (mentor-rejected) ## Changes - **2026-10-21** `29ab13db0a39`: 1 info - endpoint added [Operation history](https://skmtc.dev/hephaestus-build/apis/hephaestus-api/changes/workspaces/:workspaceSlug/mentor/turns/post.md) --- [API](https://skmtc.dev/hephaestus-build/apis/hephaestus-api.md) · [All operations](https://skmtc.dev/hephaestus-build/apis/hephaestus-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hephaestus-build/apis/hephaestus-api/revisions/3592ab716973?raw)