API reference
Skills
Create, use, teach and manage skills.
Base URL https://api.wity.alphanimble.com, the same key as every other call (Authorization: Bearer wity_…). Skills belong to the key's account. Wherever a path takes {skill}, use the skill's id (sk_…) or its name. For what skills are and how they learn, see Skills and Parts.
The skill object#
{"id": "sk_4f1c9e…","object": "skill","name": "urgent-ticket","description": "Urgent = the customer cannot use the product, a security problem, or money taken wrongly.","question": { "type": "noul", "instructions": "Does this support ticket need a reply within the hour?" },"parts": null,"combine": null,"metadata": {},"examples": 72,"status": "ready","answered_by": "examples","active": true,"version": 3,"quality": { "accuracy": 0.94, "accuracy_without_skill": 0.67, "checked_on": 72 },"created_at": 1792400000,"updated_at": 1792400004}
| field | meaning |
|---|---|
status | needs_examples, learning or ready |
answered_by | question, rule, parts or examples: how decisions are answered now |
active | true when decisions use what the skill learned from its examples |
quality | null until it has learned; then accuracy on its own held-back examples, with and without the skill |
version | goes up each time it learns or changes |
created_at, updated_at | Unix seconds |
Create a skill#
_, - and .; unique in your account; not starting with sk_.{"state", "answer"} objects. answer is yes / no (or true / false) for noul, an option id for choice."auto" for Wity to write them. See Parts.and, or, not and brackets. noul skills only.Returns the skill object with usage: adding examples is billed once, on the tokens of their states (with the question and its parts). 409 if the name is taken.
Use a skill#
In any request's questions, "<id>": {"skill": "<skill>"}. The answer has the skill's type and adds skill (id, name, version, answered_by, active) and, for skills with parts, parts. A skill question takes no other fields.
List, get, update and delete#
Newest first. limit 1 to 100 (default 20) and after (the last id of the page before). Returns a list:
{ "object": "list", "data": [ … ], "has_more": false }
Any of name, description, question, parts, combine and metadata. A new question, parts or rule makes the skill learn again (status becomes learning); "parts": null removes the parts and their rule. A new question must still offer every answer its examples use.
Deletes the skill and its examples. Returns {"id", "object": "skill", "deleted": true}.
Examples#
{"examples": [ … ]}, 1 to 1,000 per call. Returns the added examples, the updated skill and usage. The skill starts learning a moment later.
Newest first, with limit and after. Each example:
{ "id": "ex_a62d…", "object": "skill.example", "state": "…", "answer": "no","source": "session", "session_id": "ses_9a…", "created_at": 1792400100 }
source is api for examples you sent and session for feedback from a session.
Limits and errors#
| limit | value |
|---|---|
| skills per account | 500 |
| examples per skill | 20,000 |
| examples per call | 1,000 |
| parts per skill | 32 |
| to start learning | 8 examples, at least 2 for each of two answers |
Errors are {"error": "<what is wrong and how to fix it>", "code": "invalid_request" | "not_found" | "conflict"} with status 400, 404 or 409. Unknown fields are rejected with 400.
Note