Skip to main content
POST https://api.humalike.com/v1/foresee/actions/foresee
Send a transcript and your agent’s draft reply. In one call, the Theory of Mind API returns:
  • a mental-state read for each modelled subject — what they currently believe, want, and feel,
  • a predicted reaction — what each subject likely says or does next if the draft is sent as-is, with a risk rating,
  • a refined reply in your agent’s voice that heads off the predicted damage, plus a one-line refinement_rationale explaining why it changed.
Use it before any user-facing message where landing well matters: support replies, sensitive negotiations, recovery from a misstep, or any agent that has to read the room.

​
Authorization

​
Authorization
string
required
Your bearer token: Bearer <token>. See Authentication. Tokens are issued as ak_... keys tied to your account.

​
Request body

​
transcript
Turn[]
required
The conversation so far, in order. Must contain at least one turn.
​
candidate_reply
string
required
The agent’s draft reply — what would be sent if you did nothing. This is the message the API evaluates and rewrites.
​
agent_name
string
default:"agent"
Which speaker in transcript is your agent. The service never infers this: the agent’s draft is the one being refined; everyone else is treated as someone the agent is replying to, whose reaction is predicted.
​
subject_name
string
Optional. Restrict the mental-state read and predicted reaction to a single person by name. If omitted, all non-agent speakers are modelled.
Each Turn has:
​
speaker
string
required
Who sent the message. Used both to identify the agent (via agent_name) and to label each modelled subject in the response.
​
text
string
required
The message text.
Request
{
  "transcript": [
    {"speaker": "customer", "text": "invoices won't download."},
    {"speaker": "agent",    "text": "which browser? check the popup icon"},
    {"speaker": "customer", "text": "Chrome. no popup icon there."},
    {"speaker": "customer", "text": "ok i'll try later. thanks anyway."}
  ],
  "candidate_reply": "No problem! Reach out if it still doesn't work.",
  "agent_name": "agent"
}

​
Response

The response holds parallel arrays — one entry per modelled subject — plus the rewritten reply.
​
mental_state
MentalState[]
What each modelled subject currently believes, wants, and feels.
​
predicted_reaction
PredictedReaction[]
How each modelled subject is predicted to react if candidate_reply is sent as-is. Same order as mental_state.
​
refined_reply
string
An improved reply, written in the agent’s voice, rewritten to head off the predicted damage.
​
refinement_rationale
string
One line: why the reply changed.
Each MentalState has:
​
name
string
The modelled speaker.
​
beliefs
string[]
What the subject currently believes about the situation.
​
goals
string[]
What the subject currently wants.
​
emotions
Emotion[]
The subject’s emotional state. Each emotion has a type (e.g. resignation, frustration) and an intensity between 0.0 and 1.0.
Each PredictedReaction has:
​
name
string
The subject this reaction is for.
​
summary
string
One line: what the subject does next.
​
predicted_message
string
The likely next message the subject would send, or "(no reply)" if they are predicted to disengage.
​
risk
string
How badly the draft is predicted to land for this subject: low, medium, or high. Treat medium and high as a signal to send refined_reply instead.
200 OK
{
  "mental_state": [
    {
      "name": "customer",
      "beliefs": ["the agent didn't actually help", "the problem is still unresolved"],
      "goals": ["disengage without further frustration"],
      "emotions": [
        {"type": "resignation", "intensity": 0.7},
        {"type": "mild_frustration", "intensity": 0.4}
      ]
    }
  ],
  "predicted_reaction": [
    {
      "name": "customer",
      "summary": "the customer leaves unhappy and is unlikely to return",
      "predicted_message": "(no reply)",
      "risk": "high"
    }
  ],
  "refined_reply": "Sorry that didn't get you there — invoices not downloading in Chrome with no popup icon is usually a blocked-download setting. I'll send a 2-step fix you can try whenever you're back, and I'll keep this ticket open so we finish it together.",
  "refinement_rationale": "The draft accepts the customer's exit; the refined reply takes ownership, names a concrete next step, and keeps the door open."
}

​
Errors

StatusCodeWhen
400VALIDATION_ERRORThe transcript is too large to analyze, or it could not be analyzed.
401UNAUTHORIZEDThe bearer token is missing, invalid, or expired.
402PAYMENT_REQUIREDYour account does not have enough credits to cover this request. Top up and retry. You are not charged.
403forbiddenThe token is valid but not allowed to call foresee.
422VALIDATION_ERRORThe body is malformed, transcript is empty, or candidate_reply is missing.
502UPSTREAM_ERRORA dependency the request relies on was unavailable. The request is not billed; safe to retry.
Foresee is a billable operation. A request is priced and checked against your credit balance before it is processed: an uncovered request is rejected with 402 and is not billed, and a request that fails is not billed either. See Credits and billing.

​
Example

curl https://api.humalike.com/v1/foresee/actions/foresee \
  -H "Authorization: Bearer $HUMALIKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transcript": [
      {"speaker": "customer", "text": "invoices won'\''t download."},
      {"speaker": "agent",    "text": "which browser? check the popup icon"},
      {"speaker": "customer", "text": "Chrome. no popup icon there."},
      {"speaker": "customer", "text": "ok i'\''ll try later. thanks anyway."}
    ],
    "candidate_reply": "No problem! Reach out if it still doesn'\''t work.",
    "agent_name": "agent"
  }'