Reference

Training requests

Ask us to train VAKYN on your decisions when tuning the wording is not enough. You send a description of the decision and your measured results; we reply in the console.

A training request starts the VAKYN loop for your use case: we measure VAKYN on your cases, find where it is wrong or unsure, train exactly there and measure again. The train-request skill writes the request from your project and sends it once you have read it. You can also send it yourself. Sending one is free and needs no balance.

What to send

Field	Required	What it holds
`schema_version`	yes	Always `1`.
`title`	yes	The use case in one line, up to 200 characters.
`decision`	yes	What is decided, by whom today, and what happens to unsure answers.
`questions`	yes	1 to 20 questions: `name`, `type` (`noul`, `choice` or `score`), and optionally `instructions`, `options` and a description of the `state`.
`contact`	yes	`email`, and optionally `name` and `company`. We reply to this address.
`results`	no	Measured results per question: `set`, `stage`, `cases`, `right`, `metric`, `value` and the `source` file.
`losing_cells`	no	Where VAKYN is still wrong or unsure: `question`, `kind` (such as `DSP -> CRD`), `count`, `of`, `note`.
`examples`	no	Up to 50 made-up examples: `input`, `answer`, and `made_up: true`.
`needs`	no	The `target` accuracy, `volume`, `latency`, what a mistake costs (`value`), and `constraints`.
`can_share`	no	How many `labeled_cases` exist, who labeled them, and under what `terms`.
`runs_on`, `model`	no	Where it must run (`where`, `region`) and the model you use now.
`proposal_markdown`	no	The full proposal as Markdown, up to 20,000 characters. Shown as text: HTML and images are not displayed.
`client`	no	What sent it: `skill` and `skills_version`.

Every object accepts only the fields above; anything else is refused, so a typo is caught instead of lost.

What not to send

No real records. Examples must be made up and marked made_up: true; results are counts. Your labeled cases are shared later, once the terms are agreed (a DPA, or a BAA for health data), and not through this API.
No personal data, no customer names, no API keys, no internal code.

Send a request

POST https://api.vakyn.com/v1/training-requests with your API key, the same one you use for /v1/systemone:

Request

curl https://api.vakyn.com/v1/training-requests \  -H "Authorization: Bearer $VAKYN_API_KEY" \  -H "Content-Type: application/json" \  -d @training-request.json

training-request.json

{  "schema_version": 1,  "title": "Routing bank support messages to the right team",  "decision": "Each customer message goes to one of five teams or a general queue; below 0.8 confidence to a person.",  "runs_on": {    "where": "cloud",    "region": "EU"  },  "model": "vakyn-fast",  "questions": [    {      "name": "intent",      "type": "choice",      "options": {        "CRD": "the card itself",        "DSP": "a payment the customer wants reversed",        "OTH": "anything else"      },      "state": "message: the customer's message, English, 1-3 sentences"    }  ],  "examples": [    {      "input": "My card was used in two shops abroad but it is still in my pocket.",      "answer": "DSP",      "made_up": true    }  ],  "results": [    {      "question": "intent",      "set": "reserved",      "stage": "after_tuning",      "cases": 20,      "right": 17,      "metric": "accuracy",      "value": 0.85,      "source": "optimize-run/report.md"    }  ],  "losing_cells": [    {      "question": "intent",      "kind": "DSP -> CRD",      "count": 1,      "of": 44,      "note": "fraud where the customer still has the card"    }  ],  "needs": {    "target": "95% right on what is routed automatically",    "volume": "3,000/day",    "latency": "2 s",    "constraints": [      "GDPR",      "EU only"    ]  },  "can_share": {    "labeled_cases": 1500,    "labeled_by": "support team leads",    "terms": "DPA"  },  "contact": {    "name": "Ana Pop",    "email": "ana@example.com"  },  "proposal_markdown": "# Routing bank support messages\n\n…",  "client": {    "skill": "train-request",    "skills_version": "0.8.0"  }}

Response · 201

{  "id": "tr_8Jf2kQ0mVb3xLc9a",  "status": "received",  "url": "https://vakyn.com/console/training/tr_8Jf2kQ0mVb3xLc9a"}

The url opens the request in your console, where you see its status and our replies and can add a note.

Check on your requests

GET /v1/training-requests lists your organization's requests, newest first, with id, title, status, created_at, updated_at, url and quote. GET /v1/training-requests/{id} adds our messages and the request as you sent it. The quote is null until we send one.

Status	Meaning
`received`	Received
`reviewing`	Reviewing
`quoted`	Quoted
`in_training`	In training
`delivered`	Delivered
`declined`	Declined

Errors and limits

Status	When
`400`	The body is not JSON.
`401`	The API key is missing, wrong or revoked.
`403`	The organization is suspended.
`404`	GET of an id that is not in your organization.
`413`	The body is over 128 KB.
`422`	A field is missing, too long, of the wrong type or unknown. `detail.errors` lists every problem with its path.
`429`	More than 10 requests from your organization in 24 hours. Wait for `retry-after` seconds.

Response · 422

{  "detail": {    "error_type": "invalid_request",    "message": "The training request has a problem: examples[0].made_up must be true: send only made-up examples, never real records.",    "errors": [      {        "path": "examples[0].made_up",        "message": "must be true: send only made-up examples, never real records"      }    ]  }}