Intents

GET /v1/agents/{name}/intent-candidates#

List intent candidates. What callers asked this agent for that its taxonomy does not cover, most frequent first. Each entry carries how often it recurred and which existing intent it came closest to, a high nearest_score usually means the fix is one more example on an intent you already have, not a new one. **Reading the scores.** threshold is the cut these phrasings failed to clear and threshold_source says whether you set it (agent) or the platform default applies (default). Every nearest_score here is below that number by definition, so the threshold is what makes the scores mean anything. **tuning is the what-if ladder.** Each rung is a lower threshold with how many of the phrasings BELOW, and how many turns they account for, would have been routed to their nearest_intent instead of landing here. It is computed over the rows in this response and nothing else, so you can check any rung by hand, and limit / min_count narrow it along with the feed. A phrasing with no nearest_intent is never counted on any rung: nothing scored against it, so no threshold recovers it and it needs a new intent. An empty ladder means exactly that for the whole page. Entries expire on their own after sixty days, so this is a review feed rather than an archive. truncated: true means the read stopped at its row budget and this is a top-N over the rows it reached.

Parameters

Responses

Example request

curl "https://api.voiceland.ai/v1/agents/{name}/intent-candidates" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a IntentCandidatesResponse.

Example response

{
  "agent": "front-desk",
  "items": [
    {
      "count": 34,
      "hash": "9f2c1a7e4b3d4e219c0a5f6d7e8a9b0c",
      "nearest_intent": "billing_invoice",
      "nearest_score": 0.19,
      "text": "τι ωρα ανοιγετε σημερα"
    }
  ],
  "threshold": 0.35,
  "threshold_source": "default",
  "truncated": false,
  "tuning": [
    {
      "candidates": 0,
      "threshold": 0.3,
      "turns": 0
    },
    {
      "candidates": 0,
      "threshold": 0.25,
      "turns": 0
    },
    {
      "candidates": 0,
      "threshold": 0.2,
      "turns": 0
    },
    {
      "candidates": 1,
      "threshold": 0.15,
      "turns": 34
    },
    {
      "candidates": 1,
      "threshold": 0.1,
      "turns": 34
    },
    {
      "candidates": 1,
      "threshold": 0.05,
      "turns": 34
    }
  ]
}

POST /v1/agents/{name}/intent-candidates/promote#

Promote an intent candidate. Adds a mined phrasing to the taxonomy and drops it from the candidate list. Naming an EXISTING intent adds the phrasing as one more example, which is the usual move; naming a new one creates it and needs an action. The phrasing added is the one that was recorded, taken from the stored candidate rather than from this request, an edited version would not match the traffic it was promoted to cover.

Parameters

Request body

application/json Schema: IntentPromoteRequest

Responses

Example request

curl -X POST "https://api.voiceland.ai/v1/agents/{name}/intent-candidates/promote" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "answer_from_kb",
  "hash": "9f2c1a7e4b3d4e219c0a5f6d7e8a9b0c",
  "intent": "opening_hours"
}'

DELETE /v1/agents/{name}/intent-candidates/{hash}#

Dismiss an intent candidate. Removes one mined phrasing from the candidate list without adding it to the taxonomy, "we are not going to cover this". Dismissing something callers keep saying only clears it until it is said again.

Parameters

Responses

Example request

curl -X DELETE "https://api.voiceland.ai/v1/agents/{name}/intent-candidates/{hash}" \
  -H "Authorization: Bearer VL_API_KEY"

GET /v1/agents/{name}/intents#

Get an agent's intent taxonomy. The list of things this agent recognises callers asking for, and what it does with each. Never configured reads as disabled with an empty list and the platform default threshold. threshold is always the number actually in force, and threshold_source says where it came from: agent when you set one, default when the platform value applies.

Parameters

Responses

Example request

curl "https://api.voiceland.ai/v1/agents/{name}/intents" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a IntentTaxonomyResponse.

Example response

{
  "agent": "front-desk",
  "enabled": true,
  "items": [
    {
      "action": "answer_from_kb",
      "examples": [
        "Why was I charged twice",
        "Θέλω να δω το τιμολόγιό μου"
      ],
      "name": "billing_invoice"
    }
  ],
  "threshold": 0.35,
  "threshold_source": "default",
  "unknown_action": "record"
}

PUT /v1/agents/{name}/intents#

Set an agent's intent taxonomy. Replaces the whole taxonomy. Every caller turn is then matched against it before the agent answers, and the match steers the answer according to that intent's action: answer_from_kb searches your knowledge base, flow runs a named procedure, tool calls a named tool, escalate_to_human offers a person, transfer hands the call on. **What matching is done on.** The examples are the evidence, write them in the words your callers actually use, in every language the agent answers in. description counts for less, and an intent with no examples matches poorly. **Turns that match nothing** are recorded as taxonomy candidates you can review and promote, and, only if unknown_action is fallback, answered with your agent's existing out-of-scope reply. Leave it on record until the taxonomy covers your traffic; fallback on a partial taxonomy makes the agent decline most of what it is asked. **threshold is per agent and worth tuning.** Omit it for the platform default of 0.35, which is deliberately conservative and is measurably strict on speech carrying a lot of filler: a clean in-scope ask scores 0.76 to 0.83 against a five-intent taxonomy, but the same asks spoken with ordinary greetings and thanks measure 0.19 to 0.30 and are recorded as unknown. Tune it from your own GET /agents/{name}/intent-candidates feed, whose tuning ladder says what each lower cut would have caught in your traffic; lowering it buys recall and costs precision, so move one rung at a time. Setting enabled: true requires the intent-recognition capability on your plan. A stored taxonomy with enabled: false costs nothing and is never matched.

Parameters

Request body

application/json Schema: IntentTaxonomyRequest

Responses

Example request

curl -X PUT "https://api.voiceland.ai/v1/agents/{name}/intents" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "items": [
    {
      "action": "answer_from_kb",
      "description": "Questions about an invoice or a charge.",
      "examples": [
        "Why was I charged twice",
        "Θέλω να δω το τιμολόγιό μου"
      ],
      "name": "billing_invoice"
    },
    {
      "action": "escalate_to_human",
      "examples": [
        "Let me speak to a person",
        "Θέλω να μιλήσω με εκπρόσωπο"
      ],
      "name": "speak_to_human"
    }
  ],
  "threshold": 0.35,
  "unknown_action": "record"
}'

A successful response returns a IntentTaxonomyResponse.

Example response

{
  "agent": "front-desk",
  "enabled": true,
  "items": [
    {
      "action": "answer_from_kb",
      "name": "billing_invoice"
    }
  ],
  "threshold": 0.35,
  "threshold_source": "agent",
  "unknown_action": "record"
}

Schemas#

Error#

Error envelope returned for non-2xx responses.

IntentCandidateWire#

IntentCandidatesResponse#

IntentPromoteRequest#

IntentTaxonomyRequest#

IntentTaxonomyResponse#

IntentThresholdRung#

IntentWire#