Skills & sessions

Sessions

Keep a state on Wity's side and add to it over time. Each decision reads the latest state and everything added since; you never send the same text twice.

A support thread, a claim being worked on, an agent run, a game: the facts arrive one at a time and you decide again after each. Without a session you resend the whole history with every request. With one, you send only what is new, and the session keeps the log: every update, every decision and every correction, in order.

The flow#

# 1. Open a session: a state, and the skills it decides with by default
curl https://api.wity.alphanimble.com/v1/sessions \
  -H "Authorization: Bearer $WITY_API_KEY" -H "Content-Type: application/json" \
  -d '{ "state": "Support ticket #5120 from Northwind Foods (premium plan).", "skills": ["urgent-ticket"] }'
# -> { "id": "ses_9a…", "object": "session", ... }
 
# 2. Add what happens, as it happens
curl https://api.wity.alphanimble.com/v1/sessions/ses_9a…/events \
  -H "Authorization: Bearer $WITY_API_KEY" -H "Content-Type: application/json" \
  -d '{ "events": [{ "type": "update", "content": "Customer: since your update none of our cashiers can log in." }] }'
 
# 3. Decide: the session's skills, or any questions you pass
curl https://api.wity.alphanimble.com/v1/sessions/ses_9a…/decide \
  -H "Authorization: Bearer $WITY_API_KEY" -H "Content-Type: application/json" \
  -d '{}'

A session decision is an ordinary decision, plus where it sits in the session:

{
  "answers": {
    "urgent-ticket": { "type": "noul", "noul": 0.999, "skill": { "name": "urgent-ticket", "version": 3, ... } }
  },
  "decision_id": "ev_be9f…",
  "session_id": "ses_9a…",
  "context": { "updates_read": 2, "updates_left_out": 0 },
  "cached": false,
  "usage": { "input_tokens": 202, "output_tokens": 0 }
}

Events#

Add up to 100 events per call with POST /v1/sessions/{id}/events. Each one is kept in the session's log, oldest first.

type	what it does
`update`	text (or a JSON object) added to what Wity reads, after everything before it
`state`	Wity reads from this point on, starting over: use it when the situation is replaced, not added to. Earlier events stay in the log
`note`	kept in the log for you and your team; Wity never reads it
`feedback`	the right answer to an earlier skill decision; see below

Decisions are added to the log by Wity, as decision events. With "remember": true on a decide call, its answer is also added to what later decisions read (“Earlier decision. … Answer: yes.”), so a later question can build on an earlier one.

Deciding#

POST /v1/sessions/{id}/decide takes the same questions, reasoning and max_latency_ms as /v1/systemone, but no state: the state is the session. Leave questions out to run the session's skills, each named by its skill name.

Repeats are free. The same session contents and the same questions (and skill versions) give the same answer, straight back, with "cached": true and usage.input_tokens 0. A note doesn't change what Wity reads, so it doesn't change the answer either.
Long sessions keep their newest updates. When the state and its updates pass the state limit, the oldest updates are left out first; context says how many were read and left out. Add a state event with a summary to start over.
Fast. A session decision costs what the same request to /v1/systemone would, and adding an event takes a few milliseconds.

Feedback teaches the skill#

When a decision from a skill was wrong (or right), say so with a feedback event: the decision's id and the right answer. Add question when the decision had more than one skill question. The feedback becomes an example of that skill, with exactly what the decision read, and the skill learns from it within seconds (its version goes up when the new one is ready).

curl https://api.wity.alphanimble.com/v1/sessions/ses_9a…/events \
  -H "Authorization: Bearer $WITY_API_KEY" -H "Content-Type: application/json" \
  -d '{ "events": [{ "type": "feedback", "decision_id": "ev_be9f…", "answer": "no" }] }'

Tip

Wire feedback to whatever already tells you the right answer: an agent changing a ticket's priority, a reviewer overturning a flag, a customer reopening a case. Every correction makes the skill better at your definition.

Lifetime

Sessions expire 7 days after they are created unless you set expires_in (60 seconds to 90 days) when creating or updating them.PATCH also changes a session's skills and metadata; its state changes only through events, so the log stays complete. Deleting a session deletes its log; examples made from its feedback stay with their skills.

Try a full session in the console's Skills & sessions demos, and see every endpoint in the sessions API reference.

← Parts

Decide: POST /v1/systemone →