API reference

Sessions

Create sessions, add events, decide, and read the log.

Base URL https://api.wity.alphanimble.com, the same key as every other call. Sessions belong to the key's account. For how sessions work, see Sessions.

The session object#

{
  "id": "ses_9a41c0…",
  "object": "session",
  "state": "Support ticket #5120 from Northwind Foods (premium plan).",
  "skills": ["sk_4f1c9e…"],
  "metadata": {},
  "events": 4,
  "created_at": 1792400000,
  "updated_at": 1792400310,
  "expires_at": 1793004800
}

skills are skill ids. events counts the log. Times are Unix seconds.

Create a session#

POST/v1/sessions

state

string

What Wity reads first. May be empty. Up to the state limit.

skills

array

Skill ids or names the session decides with when decide names no questions.

metadata

object

Yours to keep, such as your own ticket id. Up to 8,000 characters as JSON.

expires_in

integer

Seconds until the session and its log are deleted: 60 to 7,776,000 (90 days). Default 7 days.

List, get, update and delete#

GET/v1/sessions

Newest first. limit 1 to 100 (default 20) and after (the last id of the page before).

GET/v1/sessions/{id}

PATCH/v1/sessions/{id}

Any of skills, metadata and expires_in (counted from now). The state changes only through events.

DELETE/v1/sessions/{id}

Deletes the session and its log. Examples made from its feedback stay with their skills.

Add events#

POST/v1/sessions/{id}/events

{"events": [ … ]}, 1 to 100 per call, kept in order. Returns the added events and the updated session.

event	fields
`update`	`content`: text or a JSON object, added to what Wity reads
`state`	`content`: what Wity reads from here on, instead of everything before (may be empty)
`note`	`content`: kept in the log, never read by Wity
`feedback`	`decision_id`, `answer`, and `question` when that decision had more than one skill question. Adds an example to the skill

Decide#

POST/v1/sessions/{id}/decide

questions

object

As in /v1/systemone, skills included. Leave out to run the session's skills, each keyed by its name.

reasoning

string

off, auto or always, as in /v1/systemone; skill questions are answered in fast mode. Default off.

max_latency_ms

integer

As in /v1/systemone.

remember

boolean

Add this decision's answers to what later decisions read. Default false.

{
  "model": "wity-1",
  "answers": { "urgent-ticket": { "type": "noul", "noul": 0.999, "skill": { … } } },
  "metadata": { "reasoning": "off", "elapsed_ms": 39.5 },
  "decision_id": "ev_02…",
  "session_id": "ses_9a41c0…",
  "context": { "updates_read": 2, "updates_left_out": 0 },
  "cached": false,
  "usage": { "input_tokens": 202, "output_tokens": 0 }
}

context says how many updates the decision read and how many of the oldest were left out to fit. cached is true when the same session contents and questions were already answered: the answer is the same and usage is 0.

The log#

GET/v1/sessions/{id}/events

Oldest first, with limit (default 50, at most 100) and after (an event id).

{
  "object": "list",
  "data": [
    { "id": "ev_01…", "object": "session.event", "type": "update", "content": { "content": "Customer: …" }, "created_at": 1792400120 },
    { "id": "ev_02…", "object": "session.event", "type": "decision",
      "content": { "questions": { … }, "answers": { … }, "remember": false, … }, "created_at": 1792400121 },
    { "id": "ev_03…", "object": "session.event", "type": "feedback",
      "content": { "decision_id": "ev_02…", "question": "urgent-ticket", "answer": "no", "skill": "sk_4f1c9e…", "example_id": "ex_a62d…" },
      "created_at": 1792400300 }
  ],
  "has_more": false
}

Limits#

limit	value
events per call	100
events per session	100,000
what a decision reads	the state limit; oldest updates are left out first
lifetime	60 seconds to 90 days; 7 days by default

Errors have the same shape as for skills. Session decisions are billed like /v1/systemone on their input tokens; repeats, events and reads are free.

← Skills: /v1/skills

Errors, limits & billing →