API reference / Self-service

Self-service

The Self-service endpoints of the Voiceland AI API, with parameters, schemas and curl examples.

Last updated:

GET /v1/me/agent-stats#

Per-agent call stats. Day-bucketed call counts per agent over a window (defaults to month-to-date).

Parameters

Name In Type Required Description
from query string Window start (RFC3339).
to query string Window end (RFC3339).

Responses

Code Description
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/agent-stats" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a AgentStatsResponse.

Example response

{
  "agents": [],
  "days": [],
  "total_calls": 1200
}

GET /v1/me/ai-reports#

List AI operations reports. One page of your generated reports, newest period keys first, WITHOUT the report bodies, fetch a period for the full metrics. **Paging.** Pass the next_cursor from the previous response back as ?cursor=. **An empty next_cursor is the only signal that you have seen everything.**

Parameters

Name In Type Required Description
limit query integer Rows per page, 1 to 60 (default 12).
cursor query string The next_cursor from the previous page. Omit for the first page.

Responses

Code Description
200 Success.
400 limit is not a positive whole number (bad_request), or the cursor was not issued by this listing (invalid_cursor).
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/ai-reports" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a AiReportsResponse.

Example response

{
  "items": [
    {
      "cadence": "monthly",
      "period": "2026-07",
      "status": "sent",
      "tenant": "acme",
      "truncated": false
    }
  ],
  "next_cursor": ""
}

GET /v1/me/ai-reports/config#

AI operations report settings. Your periodic AI operations report configuration: whether the scheduler is armed, the cadence (monthly or quarterly, Europe/Athens calendar periods), and the email recipients of the XLSX digest. Never configured reads as disabled with the monthly default.

Responses

Code Description
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/ai-reports/config" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a AiReportConfigResponse.

Example response

{
  "cadence": "monthly",
  "enabled": true,
  "recipients": [
    "quality@acme.example"
  ]
}

PUT /v1/me/ai-reports/config#

Set the AI operations report settings. Replaces the whole configuration block. An enabled config makes the scheduler generate each completed period once: per-agent quality metrics (graded volume, hallucination and grounded-answer rates, negative-feedback rate, chat takeover rate, the resolved-without-takeover ratio with its 40 percent target, containment, first-call resolution) plus the period's evaluation-run summary, delivered as an XLSX email to the recipients and as a report.ai_operations event through your subscriptions. An empty recipient list keeps the stored report and the event and skips the email. updated_at is read-only: it is accepted here and ignored, so you can read the block, change a field and send the same object straight back. Any other unrecognized field is refused (422).

Request body

application/json Schema: AiReportConfigRequest

Field Type Required Description
cadence string
enabled boolean Yes
recipients array of string
updated_at string

Responses

Code Description
200 Success.
400 Off-vocabulary cadence, too many recipients, or a recipient that is not an email address (invalid_ai_report_config).
401 Missing or invalid API key.
422 The body is not valid JSON for this shape (invalid_request).
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl -X PUT "https://api.voiceland.ai/v1/me/ai-reports/config" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "cadence": "monthly",
  "enabled": true,
  "recipients": [
    "quality@acme.example"
  ]
}'

A successful response returns a AiReportConfigResponse.

Example response

{
  "cadence": "monthly",
  "enabled": true,
  "recipients": [
    "quality@acme.example"
  ]
}

POST /v1/me/ai-reports/generate#

Generate an AI operations report now. Generates (or REGENERATES - the period row is replaced, never duplicated) one period on demand, without waiting for the scheduler. Delivery is included by default: the XLSX email to your configured recipients and the report.ai_operations event; pass "deliver": false to compute and store only. An empty body reports the last completed period of your configured cadence. **This call is rate limited per HOUR**, not per minute: it runs synchronously and reads the whole period (calls, graded turns, feedback and per-agent evaluation runs) before it answers, and it emails a workbook unless you pass "deliver": false. A refusal is 429 report_rate_limit with retry-after; your allowance is on every response as x-ratelimit-limit and comes from your plan. Scheduled reports do not consume it.

Request body

application/json Schema: AiReportGenerateRequest

Field Type Required Description
deliver boolean
period string

Responses

Code Description
200 Success.
400 The period is not YYYY-MM or YYYY-Qn (invalid_period).
401 Missing or invalid API key.
422 The body is not valid JSON for this shape (invalid_request).
429 Too many report generations for your plan's hourly allowance (report_rate_limit). Generation is synchronous and reads the whole period, so it is limited per hour rather than per minute. Wait retry-after seconds; the allowance itself is on every response as x-ratelimit-limit. Scheduled reports are unaffected - the limit is on on-demand generation only.
4XX Request error (validation, not-found, etc.).
503 No report generator is wired on this deployment (report_generator_unavailable).
5XX Server or upstream error.

Example request

curl -X POST "https://api.voiceland.ai/v1/me/ai-reports/generate" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "period": "2026-07"
}'

A successful response returns a AiReportWire.

Example response

{
  "cadence": "monthly",
  "period": "2026-07",
  "report": {
    "target": {
      "met": true,
      "threshold": 0.4,
      "value": 0.62
    }
  },
  "status": "sent",
  "tenant": "acme",
  "trigger": "manual",
  "truncated": false
}

GET /v1/me/ai-reports/{period}#

Get an AI operations report. One period's report in full: the account block and one block per agent (calls, containment, first-call resolution, graded volume with hallucination and grounded-answer rates, feedback negative rate, chat takeover rate and the resolved-without-takeover ratio against its 40 percent target, and the period's evaluation-run summary). truncated: true means some input hit its fetch budget and every number is a lower bound.

Parameters

Name In Type Required Description
period path string Yes YYYY-MM (month) or YYYY-Qn (quarter), Europe/Athens calendar.

Responses

Code Description
200 Success.
400 The period is not YYYY-MM or YYYY-Qn (invalid_period).
401 Missing or invalid API key.
404 No report was generated for that period (report_not_found).
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/ai-reports/{period}" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a AiReportWire.

Example response

{
  "cadence": "monthly",
  "period": "2026-07",
  "report": {
    "target": {
      "met": true,
      "threshold": 0.4,
      "value": 0.62
    }
  },
  "status": "sent",
  "tenant": "acme",
  "truncated": false
}

GET /v1/me/ai-reports/{period}/xlsx#

Download an AI operations report. The same two-sheet workbook the scheduler emails (Summary: the period, the account metrics and the metric definitions; Agents: one row per agent with every reported column), rendered on demand from the stored report. A period whose report has not finished generating has no body to render and answers 409.

Parameters

Name In Type Required Description
period path string Yes YYYY-MM (month) or YYYY-Qn (quarter), Europe/Athens calendar.

Responses

Code Description
200 The report as an XLSX workbook.
400 The period is not YYYY-MM or YYYY-Qn (invalid_period).
401 Missing or invalid API key.
404 No report was generated for that period (report_not_found).
409 The period's report has no stored body yet (report_body_unavailable).
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/ai-reports/{period}/xlsx" \
  -H "Authorization: Bearer VL_API_KEY"

GET /v1/me/api-keys#

List API keys. Your API keys (metadata only, never the secret).

Responses

Code Description
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/api-keys" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

{
  "items": [
    {
      "label": "production",
      "prefix": "vsk_live_"
    }
  ]
}

POST /v1/me/api-keys#

Mint an API key. Creates a full tenant API key. Plaintext is returned once, store it securely.

Request body

application/json

Responses

Code Description
201 Created.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl -X POST "https://api.voiceland.ai/v1/me/api-keys" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "production"
}'

Example response

{
  "plaintext": "vsk_live_…",
  "prefix": "vsk_live_"
}

DELETE /v1/me/api-keys/{hash}#

Revoke an API key. Revokes an API key by its hash. You cannot revoke the key you are authenticating with.

Parameters

Name In Type Required Description
hash path string Yes Key hash from the list.

Responses

Code Description
204 Revoked.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl -X DELETE "https://api.voiceland.ai/v1/me/api-keys/{hash}" \
  -H "Authorization: Bearer VL_API_KEY"

GET /v1/me/billing#

Billing usage. Talk-minutes for the current month against your plan's included minutes, plus up to 12 months of history.

Responses

Code Description
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/billing" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

{
  "current": {
    "extra_minutes": 572,
    "included_minutes": 2500,
    "minutes_used": 3072
  }
}

GET /v1/me/business-hours#

Opening hours. Your project's opening-hours calendar: the days and windows during which a visitor who asks to talk to a person can be put through to one. open_now is the calendar's verdict at the moment of the read and local_time is that moment in the calendar's own timezone. An unset or disabled calendar is always open.

Responses

Code Description
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/business-hours" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a BusinessHoursResponse.

Example response

{
  "days": [
    {
      "day": "mon",
      "ranges": [
        {
          "end": "17:00",
          "start": "09:00"
        }
      ]
    }
  ],
  "enabled": true,
  "holidays": [
    "2026-12-25"
  ],
  "local_time": "2026-08-07 11:20",
  "open_now": true,
  "timezone": "Europe/Athens"
}

PUT /v1/me/business-hours#

Set the opening hours. Replaces the whole calendar. While it is enabled, a request to talk to a person that arrives outside the listed windows is DECLINED rather than queued: the visitor is told straight away that the desk is shut and the assistant carries on with the conversation, instead of waiting in a line nobody is going to answer. A conversation a colleague has ALREADY taken over is never interrupted by closing time. A weekday you do not list is closed. holidays are whole closed days in the calendar's own timezone and beat the weekly pattern. Times are HH:MM on a 24 hour clock, the end is exclusive, and a window that would run past midnight is two windows, one on each day. Disable the calendar ("enabled": false) to go back to being reachable at any hour. open_now and local_time are read-only: they are accepted here and ignored, so you can read the calendar, change a window and send the same object straight back. Any other unrecognized field is refused (422).

Request body

application/json Schema: BusinessHoursRequest

Field Type Required Description
days array of BusinessHoursDayWire
enabled boolean Yes
holidays array of string
local_time string
open_now boolean
timezone string

Responses

Code Description
200 Success.
400 An unknown weekday, a malformed or overlapping window, a closed day that is not YYYY-MM-DD, an unknown timezone, or an enabled calendar with no open window at all (invalid_business_hours).
401 Missing or invalid API key.
422 The body is not valid JSON for this shape (invalid_request).
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl -X PUT "https://api.voiceland.ai/v1/me/business-hours" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "days": [
    {
      "day": "mon",
      "ranges": [
        {
          "end": "17:00",
          "start": "09:00"
        }
      ]
    },
    {
      "day": "tue",
      "ranges": [
        {
          "end": "17:00",
          "start": "09:00"
        }
      ]
    }
  ],
  "enabled": true,
  "holidays": [
    "2026-12-25"
  ],
  "timezone": "Europe/Athens"
}'

A successful response returns a BusinessHoursResponse.

Example response

{
  "days": [
    {
      "day": "mon",
      "ranges": [
        {
          "end": "17:00",
          "start": "09:00"
        }
      ]
    }
  ],
  "enabled": true,
  "holidays": [
    "2026-12-25"
  ],
  "local_time": "2026-08-07 11:20",
  "open_now": true,
  "timezone": "Europe/Athens"
}

GET /v1/me/conversations/emerging-topics#

Recurring themes your topic list does not cover. Discovery view: conversation topics that matched none of your configured topics, grouped by similarity, ranked by how many of them ended negatively. unassigned is how many analysed conversations produced only unmatched labels, the size of the gap. method says how the grouping was done (embeddings or lexical). This view NEVER changes your configuration. Adding a topic is your action, on the agent.

Parameters

Name In Type Required Description
from query string Window start (RFC3339). Defaults to 7 days before to.
to query string Window end (RFC3339). Defaults to now.
agent query string Restrict to one agent by name.

Responses

Code Description
200 Success.
400 from or to is not RFC3339, or from is not before to (invalid_from / invalid_to / invalid_window).
401 Missing or invalid API key.
402 Your plan does not include conversation analytics (feature_not_entitled).
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/conversations/emerging-topics" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a EmergingTopicsResponse.

Example response

{
  "analyzed": 412,
  "clusters": [
    {
      "calls": 21,
      "label": "delivery delay",
      "members": [
        "delivery delay",
        "late delivery"
      ],
      "negative_calls": 14
    }
  ],
  "method": "lexical",
  "tenant": "acme",
  "truncated": false,
  "unassigned": 63
}

GET /v1/me/conversations/negative-sentiment#

Conversations that ended badly and escalated. The quality-review queue: conversations whose caller sentiment was negative at the END and that escalated (a human takeover was requested, or the call was transferred), worst ending first. analyzed is how many conversations in the window carried a sentiment reading, so a small queue can be read against its denominator. Sentiment is produced by the post-call analysis and is absent on conversations analysed before you enabled it. Each item carries recording_purged_at (RFC3339) once your plan's recording retention has deleted the call's audio, recording_url is then absent for good and the recording stream answers 404 recording_purged, so do not offer playback on such a row.

Parameters

Name In Type Required Description
from query string Window start (RFC3339). Defaults to 7 days before to.
to query string Window end (RFC3339). Defaults to now.
agent query string Restrict to one agent by name.

Responses

Code Description
200 Success.
400 from or to is not RFC3339, or from is not before to (invalid_from / invalid_to / invalid_window).
401 Missing or invalid API key.
402 Your plan does not include conversation analytics (feature_not_entitled).
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/conversations/negative-sentiment" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a NegativeSentimentResponse.

Example response

{
  "analyzed": 412,
  "count": 9,
  "items": [
    {
      "agent": "front-desk",
      "call_id": "vl-acme-01H",
      "escalation": "takeover",
      "sentiment_end": "negative",
      "sentiment_end_score": -0.7,
      "sentiment_start": "neutral",
      "sentiment_trajectory": "declining",
      "topics": [
        "billing"
      ]
    },
    {
      "agent": "front-desk",
      "call_id": "vl-acme-01F",
      "escalation": "transfer",
      "recording_purged_at": "2026-08-01T03:00:00Z",
      "sentiment_end": "negative",
      "sentiment_end_score": -0.5,
      "sentiment_start": "negative",
      "sentiment_trajectory": "flat",
      "topics": [
        "billing"
      ]
    }
  ],
  "tenant": "acme",
  "truncated": false
}

GET /v1/me/dashboards#

Dashboard catalog. Pre-built Grafana dashboards you can import, with an import command per dashboard.

Responses

Code Description
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/dashboards" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

{
  "dashboards": []
}

GET /v1/me/end-user-policy#

Recognised-visitor policy. Whether visitors who are already signed in on your own site are recognised by the assistant, what it is allowed to remember about them between conversations, how long a profile is kept, and whether what somebody asked before is allowed to influence the order of their search results. All four are off until you turn them on. has_sso_signing_key stands in for the signing secret, which is never returned by any endpoint. memory_max_items is the platform's own bound on how much the assistant may recall about one person, a short, readable list, not a conversation archive.

Responses

Code Description
200 Success.
401 Missing or invalid API key.
402 Recognised visitors are not included in this plan (feature_not_entitled), or the account has no subscription (no_subscription).
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/end-user-policy" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a EndUserPolicyResponse.

Example response

{
  "enabled": true,
  "has_sso_signing_key": true,
  "memory_enabled": true,
  "memory_max_items": 12,
  "personalized_ranking": true,
  "retention_days": 90,
  "sso_issuer": "https://example.com",
  "sso_max_age_seconds": 60
}

PUT /v1/me/end-user-policy#

Set the recognised-visitor policy. Replaces the whole policy. To recognise a visitor, your own site signs a short-lived token for the person who is already logged in there and hands it to the widget; we verify it against sso_signing_key, check that it names you as its audience and that it has not been presented before, and derive an opaque per-person key from the subject id inside it. We never take an email address or a phone number as the identity, and the key we store cannot be turned back into your user id by anyone who reads the row. memory_enabled is a SEPARATE decision from enabled: recognising somebody and carrying what they said last time into this conversation are different promises to make to them. personalized_ranking is a third, and it only ever changes the ORDER of search results, never which results a visitor can see. retention_days is how long a profile survives its last sighting; there is no keep-forever option. sso_signing_key is write-only, send it to set or rotate it, leave it out to keep the one you have, so you can read this policy, change one switch and send the whole object straight back.

Request body

application/json Schema: EndUserPolicyRequest

Field Type Required Description
enabled boolean Yes
has_sso_signing_key boolean
memory_enabled boolean Yes
memory_max_items integer
personalized_ranking boolean Yes
retention_days integer
sso_issuer string
sso_max_age_seconds integer
sso_signing_key string

Responses

Code Description
200 Success.
400 Enabled without an issuer or a signing key, or a retention outside 1-730 days (invalid_end_user_policy).
401 Missing or invalid API key.
402 Recognised visitors are not included in this plan (feature_not_entitled), or the account has no subscription (no_subscription).
422 The body is not valid JSON for this shape (invalid_request).
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl -X PUT "https://api.voiceland.ai/v1/me/end-user-policy" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "memory_enabled": true,
  "personalized_ranking": false,
  "retention_days": 90,
  "sso_issuer": "https://example.com",
  "sso_signing_key": "the shared secret your site signs with"
}'

A successful response returns a EndUserPolicyResponse.

Example response

{
  "enabled": true,
  "has_sso_signing_key": true,
  "memory_enabled": true,
  "memory_max_items": 12,
  "personalized_ranking": false,
  "retention_days": 90,
  "sso_issuer": "https://example.com",
  "sso_max_age_seconds": 60
}

GET /v1/me/end-users#

Recognised visitors. One page of the people your assistant currently recognises, in key order. Each entry carries the whole of what the assistant may recall about that person, if the memory list is empty, it knows nothing beyond the name and language their sign-in supplied.

Parameters

Name In Type Required Description
limit query integer Rows per page, 1-100 (default 25).

Responses

Code Description
200 Success.
400 limit is not a non-negative integer (invalid_limit).
401 Missing or invalid API key.
402 Recognised visitors are not included in this plan (feature_not_entitled), or the account has no subscription (no_subscription).
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/end-users" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a EndUserListResponse.

Example response

{
  "count": 1,
  "items": [
    {
      "display_name": "Maria",
      "locale": "el",
      "memory": [
        {
          "key": "asked about",
          "kind": "topic",
          "recorded_at": "2026-08-01T10:00:00Z",
          "value": "warranty"
        }
      ],
      "profile_key": "9f2c…",
      "sessions": 3
    }
  ]
}

DELETE /v1/me/end-users/{key}#

Erase a recognised visitor. Removes the profile and everything the assistant remembered about that person, immediately. Wire this to your own "forget me" button. When there was nothing to erase it still answers 200 with zero counts: the counts tell you what actually went, and asking twice is not an error, because the point of the endpoint is the guarantee that nothing is held afterwards. **A legal hold is the one thing that refuses it (409 legal_hold), and a refusal erases nothing at all.** A hold preserves evidence for a legal process, so it outranks an erasure request. It can cover the whole project, or only the individual calls this person took part in; either way the profile, its memory items and its call links are left exactly as they were, so there is no partial erase to reconcile afterwards. The message says which of the two refused and names the held calls. Release the hold and the identical request succeeds. The operator's subject-rights route refuses the same person with the same status, the same code and the same wording, so there is no second door that erases what this one preserved.

Parameters

Name In Type Required Description
key path string Yes The opaque profile key, 64 lowercase hex characters.

Responses

Code Description
200 Success.
400 The key is not 64 lowercase hex characters (invalid_profile_key).
401 Missing or invalid API key.
402 Recognised visitors are not included in this plan (feature_not_entitled), or the account has no subscription (no_subscription).
409 A legal hold covers this person's data (legal_hold). **Nothing was deleted**: not the profile, not its memory, not its call links. Either the whole project is held, or specific calls this person took part in are; the message says which and names the held calls. Release the hold, or handle the request outside the API. The same request succeeds once the hold is gone.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl -X DELETE "https://api.voiceland.ai/v1/me/end-users/{key}" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a EndUserEraseResponse.

Example response

{
  "call_links_deleted": 2,
  "memory_items_deleted": 4,
  "profile_key": "9f2c…",
  "profiles_deleted": 1
}

GET /v1/me/end-users/{key}#

One recognised visitor. Everything held about one person: what their sign-in told us, and the complete list of things the assistant may recall about them. This is the answer to "what does your assistant remember about me", there is nothing else, and each remembered item names the conversation it was learned in.

Parameters

Name In Type Required Description
key path string Yes The opaque profile key, 64 lowercase hex characters.

Responses

Code Description
200 Success.
400 The key is not 64 lowercase hex characters (invalid_profile_key).
401 Missing or invalid API key.
402 Recognised visitors are not included in this plan (feature_not_entitled), or the account has no subscription (no_subscription).
404 No profile with that key (profile_not_found).
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/end-users/{key}" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a EndUserProfileWire.

Example response

{
  "display_name": "Maria",
  "locale": "el",
  "memory": [
    {
      "key": "contact",
      "kind": "preference",
      "recorded_at": "2026-08-01T10:00:00Z",
      "source_call_id": "widget-…",
      "value": "prefers email"
    }
  ],
  "profile_key": "9f2c…",
  "sessions": 3
}

GET /v1/me/kpis#

KPIs. Containment, escalation, first-call resolution, cost percentiles, and goal completion over a window.

Parameters

Name In Type Required Description
from query string Window start (RFC3339); default trailing 24h.
to query string Window end (RFC3339).
agent query string Optional single agent.

Responses

Code Description
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/kpis" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a KpisResponse.

Example response

{
  "containment": {
    "rate": 0.82
  },
  "cost": {
    "per_call_avg_usd": 0.06
  }
}

GET /v1/me/metrics-keys#

List metrics keys. Your scrape tokens (metadata only).

Responses

Code Description
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/metrics-keys" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

{
  "items": []
}

POST /v1/me/metrics-keys#

Mint a metrics key. Creates a scrape-only token (vsk_metrics_…) for your observability stack. Plaintext returned once.

Request body

application/json

Responses

Code Description
201 Created.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl -X POST "https://api.voiceland.ai/v1/me/metrics-keys" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "prod-prometheus"
}'

Example response

{
  "plaintext": "vsk_metrics_…",
  "prefix": "vsk_metrics_"
}

DELETE /v1/me/metrics-keys/{hash}#

Revoke a metrics key. Revokes a scrape token by its hash.

Parameters

Name In Type Required Description
hash path string Yes Key hash from the list.

Responses

Code Description
204 Revoked.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl -X DELETE "https://api.voiceland.ai/v1/me/metrics-keys/{hash}" \
  -H "Authorization: Bearer VL_API_KEY"

GET /v1/me/privacy#

Transcript privacy. Whether what a caller said is kept word for word, or replaced with placeholders, and at which point. store_verbatim keeps the conversation exactly as it happened. pseudonymize_at_rest replaces names, numbers and other personal details with placeholders on the way into the record, so the stored conversation never contains them. pseudonymize_for_analytics keeps the record word for word and replaces those details only where conversations feed quality tooling. applies_to_stored_calls and reversible describe the policy that is currently set, so you never have to guess how far a change reaches. Read them before you change anything: a policy that rewrites on the way in cannot reach back over conversations you already have, and cannot be undone for the ones it wrote.

Responses

Code Description
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/privacy" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a PrivacyPolicyResponse.

Example response

{
  "applies_to_stored_calls": false,
  "policies": [
    "store_verbatim",
    "pseudonymize_at_rest",
    "pseudonymize_for_analytics"
  ],
  "reversible": true,
  "transcript_policy": "store_verbatim"
}

PUT /v1/me/privacy#

Set the transcript privacy policy. Sets the policy. Send transcript_policy as one of the three values policies lists; an empty value means store_verbatim, which is the default and what every project does until it says otherwise. WHAT THE CHANGE REACHES, which is the part worth reading twice. pseudonymize_at_rest applies to conversations that happen AFTER you set it: it rewrites the text on the way into the record, so it cannot go back over conversations you already have, and there is no key that turns a placeholder back into what the person actually said - for those conversations the change is permanent. pseudonymize_for_analytics works the other way round: the record keeps the real words and the placeholders are applied each time a conversation is read for quality work, so it covers your whole history the moment you set it and switching it off brings the original view straight back. policies, applies_to_stored_calls and reversible are read-only: they are accepted here and ignored, so you can read the policy and send the same object back. Any other unrecognized field is refused (422).

Request body

application/json Schema: PrivacyPolicyRequest

Field Type Required Description
applies_to_stored_calls boolean
policies array of string
reversible boolean
transcript_policy string Yes

Responses

Code Description
200 Success.
400 transcript_policy is not one of the three accepted values (invalid_privacy).
401 Missing or invalid API key.
422 The body is not valid JSON for this shape (invalid_request).
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl -X PUT "https://api.voiceland.ai/v1/me/privacy" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "transcript_policy": "pseudonymize_at_rest"
}'

A successful response returns a PrivacyPolicyResponse.

Example response

{
  "applies_to_stored_calls": false,
  "policies": [
    "store_verbatim",
    "pseudonymize_at_rest",
    "pseudonymize_for_analytics"
  ],
  "reversible": false,
  "transcript_policy": "pseudonymize_at_rest"
}

GET /v1/me/prometheus#

Prometheus discovery. Returns your metrics scrape URL + a ready-to-paste scrape config and example queries.

Responses

Code Description
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/prometheus" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

{
  "auth_scheme": "bearer",
  "url": "https://api.voiceland.ai/v1/metrics"
}

GET /v1/me/wallet#

Minutes wallet. Prepaid minutes pool, shared by voice calls and web-widget chat sessions: included seconds remaining this month, purchased seconds, total remaining, and blocked (true when new calls and chat sessions are refused with 402 minutes_exhausted). Voice bills a 30-second minimum then per second; a chat session bills the same rounding of its connect-to-last-message span, scaled by the plan's chat rate. A sub-tenant sees its parent account's pool.

Responses

Code Description
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/wallet" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a WalletStatus.

Example response

{
  "blocked": false,
  "has_package": true,
  "included_seconds_remaining": 24600,
  "pool_owner": "acme",
  "purchased_seconds": 1800,
  "remaining_seconds": 26400,
  "tenant": "acme",
  "tier": "root"
}

GET /v1/me/wallet/ledger#

Minutes ledger. Append-only minutes ledger, newest first. Each row snapshots the package id and per-minute rate in force at the time of the transaction; debit_call rows are voice calls, debit_chat rows are web-widget chat sessions and also carry the chat rate applied.

Parameters

Name In Type Required Description
limit query integer Max rows (1-500, default 100).

Responses

Code Description
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/me/wallet/ledger" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

{
  "items": [
    {
      "amount_cents": 0,
      "kind": "debit_call",
      "package_id": "starter",
      "rate_cents_per_min": 22,
      "seconds": -95
    }
  ]
}

GET /v1/usage#

Cost usage. Per-month cost aggregate. Pass ?month=YYYY-MM for a single month.

Parameters

Name In Type Required Description
month query string YYYY-MM; omit for the full series.

Responses

Code Description
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/usage" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

{
  "call_count": 2211,
  "total_usd": 431.77,
  "year_month": "2026-07"
}

Schemas#

AgentStat#

Field Type Required Description
agent string Yes
calls integer Yes
chat ChatKPI
days array of DayCount Yes
feedback FeedbackKPI
inbound integer Yes
intents IntentKPI
outbound integer Yes
quality QualityKPI
sentiment SentimentKPI
talk_seconds number Yes
topics TopicKPI

AgentStatsResponse#

Field Type Required Description
agents array of AgentStat Yes
chat ChatKPI
days array of DayCount Yes
feedback FeedbackKPI
from string (date-time) Yes
intents IntentKPI
quality QualityKPI
sentiment SentimentKPI
tenant string Yes
to string (date-time) Yes
topics TopicKPI
total_calls integer Yes
truncated boolean Yes

AiReportConfigRequest#

Field Type Required Description
cadence string
enabled boolean Yes
recipients array of string
updated_at string

AiReportConfigResponse#

Field Type Required Description
cadence string Yes
enabled boolean Yes
recipients array of string Yes
updated_at string (date-time)

AiReportGenerateRequest#

Field Type Required Description
deliver boolean
period string

AiReportWire#

Field Type Required Description
cadence string Yes
created_at string (date-time) Yes
email_status_code integer
error string
from string (date-time) Yes
period string Yes
recipients array of string
report ReportData
status string Yes
tenant string Yes
to string (date-time) Yes
trigger string
truncated boolean Yes
updated_at string (date-time)

AiReportsResponse#

Field Type Required Description
items array of AiReportWire Yes
next_cursor string Yes

BusinessHoursDayWire#

Field Type Required Description
day string Yes
ranges array of BusinessHoursRangeWire

BusinessHoursRangeWire#

Field Type Required Description
end string Yes
start string Yes

BusinessHoursRequest#

Field Type Required Description
days array of BusinessHoursDayWire
enabled boolean Yes
holidays array of string
local_time string
open_now boolean
timezone string

BusinessHoursResponse#

Field Type Required Description
days array of BusinessHoursDayWire Yes
enabled boolean Yes
holidays array of string Yes
local_time string Yes
open_now boolean Yes
timezone string Yes

ChatKPI#

Field Type Required Description
definition string Yes
human_takeover_rate number Yes
resolved_without_takeover integer Yes
resolved_without_takeover_ratio number Yes
sessions integer Yes
takeover_requested integer Yes

Cluster#

Field Type Required Description
calls integer Yes
label string Yes
members array of string Yes
negative_calls integer Yes
sample_call_ids array of string

ContainmentKPI#

Field Type Required Description
contained integer Yes
rate number Yes
total integer Yes

CostKPI#

Field Type Required Description
per_call_avg_usd number Yes
per_call_p50_usd number Yes
per_call_p95_usd number Yes
total_usd number Yes

DayCount#

Field Type Required Description
calls integer Yes
date string Yes

EmergingTopicsResponse#

Field Type Required Description
agent string
analyzed integer Yes
clusters array of Cluster Yes
definition string Yes
from string (date-time) Yes
method string Yes
tenant string Yes
to string (date-time) Yes
truncated boolean Yes
unassigned integer Yes

EndUserEraseResponse#

Field Type Required Description
call_links_deleted integer Yes
memory_items_deleted integer Yes
profile_key string Yes
profiles_deleted integer Yes

EndUserListResponse#

Field Type Required Description
count integer Yes
items array of EndUserProfileWire Yes

EndUserMemoryWire#

Field Type Required Description
key string
kind string Yes
recorded_at string Yes
source_call_id string
value string Yes

EndUserPolicyRequest#

Field Type Required Description
enabled boolean Yes
has_sso_signing_key boolean
memory_enabled boolean Yes
memory_max_items integer
personalized_ranking boolean Yes
retention_days integer
sso_issuer string
sso_max_age_seconds integer
sso_signing_key string

EndUserPolicyResponse#

Field Type Required Description
enabled boolean Yes
has_sso_signing_key boolean Yes
memory_enabled boolean Yes
memory_max_items integer Yes
personalized_ranking boolean Yes
retention_days integer Yes
sso_issuer string Yes
sso_max_age_seconds integer Yes

EndUserProfileWire#

Field Type Required Description
attributes map of string
display_name string
expires_at string
first_seen_at string
issuer string
last_seen_at string
locale string
memory array of EndUserMemoryWire Yes
profile_key string Yes
sessions integer Yes

Error#

Error envelope returned for non-2xx responses.

Field Type Required Description
error object Yes

EscalationKPI#

Field Type Required Description
by_cause map of integer Yes
count integer Yes
definition string Yes
rate number Yes

EvalSummary#

Field Type Required Description
errored_runs integer Yes
failed_runs integer Yes
last_run_id string
last_run_pass_rate number
last_run_status string
passed_runs integer Yes
runs integer Yes
truncated boolean

FcrKPI#

Field Type Required Description
callers_with_repeat_in_7d integer Yes
rate number Yes
unique_callers integer Yes
window_days integer Yes

FeedbackKPI#

Field Type Required Description
definition string Yes
negative integer Yes
negative_rate number Yes
rated integer Yes

GoalKPI#

Field Type Required Description
completed integer Yes
definition string Yes
rate number Yes
total integer Yes

IntentKPI#

Field Type Required Description
calls_with_intents integer Yes
classified_turns integer Yes
coverage_rate number Yes
definition string Yes
items array of IntentRateRow Yes
unknown_turns integer Yes

IntentRateRow#

Field Type Required Description
calls integer Yes
contained integer Yes
containment_rate number Yes
intent string Yes
negative integer Yes
negative_rate number Yes
rated integer Yes
turns integer Yes

KpisResponse#

Field Type Required Description
agent string
chat ChatKPI Yes
containment ContainmentKPI Yes
cost CostKPI Yes
escalation EscalationKPI Yes
feedback FeedbackKPI Yes
first_call_resolution FcrKPI Yes
from string (date-time) Yes
goal_completion GoalKPI Yes
hangup_causes map of integer Yes
intents IntentKPI Yes
quality QualityKPI Yes
sentiment SentimentKPI
tenant string Yes
to string (date-time) Yes
topics TopicKPI
truncated boolean Yes
window_calls integer Yes

MetricsBlock#

Field Type Required Description
agent string
calls integer Yes
chat ChatKPI Yes
containment RateCount Yes
eval EvalSummary Yes
feedback FeedbackKPI Yes
first_call_resolution_rate number Yes
intents IntentKPI Yes
quality QualityKPI Yes
sentiment SentimentKPI Yes
topics TopicKPI Yes

NegativeConversation#

Field Type Required Description
agent string Yes
call_id string Yes
ended_at string (date-time)
escalation string Yes
hangup_cause string
recording_purged_at string
recording_url string
sentiment_end string Yes
sentiment_end_score number Yes
sentiment_start string Yes
sentiment_trajectory string Yes
started_at string (date-time) Yes
talk_seconds number
topics array of string

NegativeSentimentResponse#

Field Type Required Description
agent string
analyzed integer Yes
count integer Yes
definition string Yes
from string (date-time) Yes
items array of NegativeConversation Yes
tenant string Yes
to string (date-time) Yes
truncated boolean Yes

PrivacyPolicyRequest#

Field Type Required Description
applies_to_stored_calls boolean
policies array of string
reversible boolean
transcript_policy string Yes

PrivacyPolicyResponse#

Field Type Required Description
applies_to_stored_calls boolean Yes
policies array of string Yes
reversible boolean Yes
transcript_policy string Yes

QualityKPI#

Field Type Required Description
definition string Yes
graded_turns integer Yes
grounded integer Yes
grounded_answer_rate number Yes
hallucinated integer Yes
hallucination_rate number Yes

RateCount#

Field Type Required Description
count integer Yes
rate number Yes
total integer Yes

ReportData#

Field Type Required Description
account MetricsBlock Yes
agents array of MetricsBlock Yes
cadence string Yes
from string (date-time) Yes
generated_at string (date-time) Yes
period string Yes
target Target Yes
tenant string Yes
timezone string Yes
to string (date-time) Yes
truncated boolean Yes

SentimentKPI#

Field Type Required Description
analyzed integer Yes
declining integer Yes
declining_rate number Yes
definition string Yes
escalated_negative integer Yes
escalated_negative_rate number Yes
improving integer Yes
improving_rate number Yes
negative integer Yes
negative_rate number Yes
neutral integer Yes
positive integer Yes
start_negative integer Yes
steady integer Yes

Target#

Field Type Required Description
chat_sessions integer Yes
definition string Yes
met boolean Yes
name string Yes
threshold number Yes
value number Yes

TopicCount#

Field Type Required Description
analyzed integer Yes
calls integer Yes
negative integer Yes
negative_rate number Yes
share number Yes
topic string Yes

TopicKPI#

Field Type Required Description
assigned integer Yes
definition string Yes
topics array of TopicCount Yes
unassigned integer Yes

WalletStatus#

Field Type Required Description
blocked boolean Yes
currency string Yes
cycle_renews_at string (date-time)
cycle_seconds_remaining integer Yes
fee_interval string
fee_status string
fee_suspended boolean
has_package boolean Yes
included_minutes integer Yes
included_seconds_remaining integer Yes
included_seconds_total integer Yes
included_seconds_used integer Yes
is_project boolean Yes
next_fee_at string (date-time)
overage_rate_cents_per_min integer Yes
package_id string
package_name string
parent_pool_available boolean Yes
pending_interval string
pending_package_id string
pending_package_name string
plan_id string
plan_minutes_per_month integer
plan_overage_allowed boolean Yes
plan_status string
pool_owner string Yes
prepaid_credit_cents integer
prepaid_run boolean
prepaid_until string (date-time)
project_seconds integer Yes
purchased_seconds integer Yes
remaining_seconds integer Yes
tenant string Yes
tier string Yes
use_parent_pool boolean Yes

The console

These pages are read only. The test call, the API keys and the live API reference are in the console, where your account is signed in.

Open the console