Self-service

Οι περιγραφές των endpoints και των πεδίων εμφανίζονται στα αγγλικά, όπως ακριβώς τις δημοσιεύει το API. Είναι επιλογή μας, ώστε να διαβάζετε εδώ ό,τι θα δείτε και στις αποκρίσεις.

GET /v1/me/agent-stats#

Per-agent call stats. Day-bucketed call counts per agent over a window (defaults to month-to-date). Days are UTC dates. Like /me/kpis, every call of the window counts: closed hours come from hourly summaries and only the rest is read call by call; truncated: true means that live part hit its read cap.

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

Η επιτυχής απόκριση επιστρέφει ένα AgentStatsResponse.

Παράδειγμα απόκρισης

{
  "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.**

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

Η επιτυχής απόκριση επιστρέφει ένα AiReportsResponse.

Παράδειγμα απόκρισης

{
  "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.

Αποκρίσεις

Παράδειγμα αιτήματος

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

Η επιτυχής απόκριση επιστρέφει ένα AiReportConfigResponse.

Παράδειγμα απόκρισης

{
  "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).

Σώμα αιτήματος

application/json Σχήμα: AiReportConfigRequest

Αποκρίσεις

Παράδειγμα αιτήματος

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"
  ]
}'

Η επιτυχής απόκριση επιστρέφει ένα AiReportConfigResponse.

Παράδειγμα απόκρισης

{
  "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.

Σώμα αιτήματος

application/json Σχήμα: AiReportGenerateRequest

Αποκρίσεις

Παράδειγμα αιτήματος

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"
}'

Η επιτυχής απόκριση επιστρέφει ένα AiReportWire.

Παράδειγμα απόκρισης

{
  "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 a part of the period not yet covered by the hourly summaries held more rows than one read takes, and every number is a lower bound; a period answered from summaries is complete.

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

Η επιτυχής απόκριση επιστρέφει ένα AiReportWire.

Παράδειγμα απόκρισης

{
  "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.

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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).

Αποκρίσεις

Παράδειγμα αιτήματος

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

Παράδειγμα απόκρισης

{
  "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.

Σώμα αιτήματος

application/json

Αποκρίσεις

Παράδειγμα αιτήματος

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"
}'

Παράδειγμα απόκρισης

{
  "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.

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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.

Αποκρίσεις

Παράδειγμα αιτήματος

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

Παράδειγμα απόκρισης

{
  "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.

Αποκρίσεις

Παράδειγμα αιτήματος

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

Η επιτυχής απόκριση επιστρέφει ένα BusinessHoursResponse.

Παράδειγμα απόκρισης

{
  "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).

Σώμα αιτήματος

application/json Σχήμα: BusinessHoursRequest

Αποκρίσεις

Παράδειγμα αιτήματος

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"
}'

Η επιτυχής απόκριση επιστρέφει ένα BusinessHoursResponse.

Παράδειγμα απόκρισης

{
  "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.

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

Η επιτυχής απόκριση επιστρέφει ένα EmergingTopicsResponse.

Παράδειγμα απόκρισης

{
  "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.

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

Η επιτυχής απόκριση επιστρέφει ένα NegativeSentimentResponse.

Παράδειγμα απόκρισης

{
  "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.

Αποκρίσεις

Παράδειγμα αιτήματος

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

Παράδειγμα απόκρισης

{
  "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.

Αποκρίσεις

Παράδειγμα αιτήματος

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

Η επιτυχής απόκριση επιστρέφει ένα EndUserPolicyResponse.

Παράδειγμα απόκρισης

{
  "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.

Σώμα αιτήματος

application/json Σχήμα: EndUserPolicyRequest

Αποκρίσεις

Παράδειγμα αιτήματος

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"
}'

Η επιτυχής απόκριση επιστρέφει ένα EndUserPolicyResponse.

Παράδειγμα απόκρισης

{
  "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.

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

Η επιτυχής απόκριση επιστρέφει ένα EndUserListResponse.

Παράδειγμα απόκρισης

{
  "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.

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

Η επιτυχής απόκριση επιστρέφει ένα EndUserEraseResponse.

Παράδειγμα απόκρισης

{
  "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.

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

Η επιτυχής απόκριση επιστρέφει ένα EndUserProfileWire.

Παράδειγμα απόκρισης

{
  "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. Every call of the window counts, however long the window: closed hours are answered from per-account hourly summaries, and only what no summary covers yet (the current hour, the partial hours at either edge of the window, an hour whose late updates have not been summarised again) is read call by call. truncated: true means that live part held more rows than one request reads (5,000 per source), so the numbers are a lower bound; it is not set by the window's length. The cost block (the provider cost of the window's calls) adds up only what ran on your own provider keys (BYOK), as each call record says, and only for a stage (stt, llm, tts) every call of the window recorded that for: a call recorded before Voiceland began recording which key served each stage leaves the stages it spent on out. With none of yours the response carries no cost.

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

Η επιτυχής απόκριση επιστρέφει ένα KpisResponse.

Παράδειγμα απόκρισης

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

GET /v1/me/metrics-keys#

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

Αποκρίσεις

Παράδειγμα αιτήματος

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

Παράδειγμα απόκρισης

{
  "items": []
}

POST /v1/me/metrics-keys#

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

Σώμα αιτήματος

application/json

Αποκρίσεις

Παράδειγμα αιτήματος

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"
}'

Παράδειγμα απόκρισης

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

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

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

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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.

Αποκρίσεις

Παράδειγμα αιτήματος

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

Η επιτυχής απόκριση επιστρέφει ένα PrivacyPolicyResponse.

Παράδειγμα απόκρισης

{
  "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).

Σώμα αιτήματος

application/json Σχήμα: PrivacyPolicyRequest

Αποκρίσεις

Παράδειγμα αιτήματος

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"
}'

Η επιτυχής απόκριση επιστρέφει ένα PrivacyPolicyResponse.

Παράδειγμα απόκρισης

{
  "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. The scrape carries usage, quality and latency series, with no provider or model label and no token, audio-second or character counts. The one cost series is voice_call_own_key_cost_usd_total (labels tenant, agent, stage): the provider cost of the call stages your own provider keys (BYOK) served, as each call record says; stages on Voiceland's keys never add to it. Provider cost per call is on the call records, /usage and /me/kpis.

Αποκρίσεις

Παράδειγμα αιτήματος

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

Παράδειγμα απόκρισης

{
  "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). blocked_reason says why (minutes_exhausted, package_past_due, package_suspended); low_minutes warns ahead of it (at most max(5 minutes, a fifth of the month's included minutes) left); refused counts this month's new calls and web-widget conversations that were not started. While blocked, inbound calls end at once with a busy tone, the web widget is not shown, and test calls, chat previews, test runs and new operations-agent runs are refused; calls already in progress are never cut. A voice call that runs on your own provider keys for all three AI stages is billed at your plan's BYOK call price out of purchased minutes only (never the included ones), so with no purchased minutes new voice calls are refused with 402 byok_balance_empty while chat carries on: byok_rate_cents_per_min is that price when it applies to the account, and byok_balance_empty is true when voice calls are refused for want of purchased minutes (blocked stays false for it, and the account administrator is emailed once when it happens). 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.

Αποκρίσεις

Παράδειγμα αιτήματος

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

Η επιτυχής απόκριση επιστρέφει ένα WalletStatus.

Παράδειγμα απόκρισης

{
  "blocked": true,
  "blocked_reason": "minutes_exhausted",
  "has_package": true,
  "included_seconds_remaining": 0,
  "pool_owner": "acme",
  "purchased_seconds": 0,
  "refused": {
    "calls": 3,
    "chats": 1,
    "since": "2026-09-27T08:12:40Z"
  },
  "remaining_seconds": 0,
  "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. A debit_call row with byok true is a call priced at the BYOK call price: seconds is the purchased seconds it took, byok_seconds the call's billed seconds and byok_rate_cents_per_min the price.

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

Παράδειγμα απόκρισης

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

GET /v1/me/whats-new#

What's new. The newest features this deployment carries, as the console's What's new popup shows them: the new entries of the public changelog from the last 120 days, newest first, at most 8, each with an emoji, an icon name and its title in English and Greek. known is true when seen (the newest entry id the signed-in user has dismissed) and muted (never notify again) were read from the user's own row; both are set through the user's self-preference update.

Αποκρίσεις

Παράδειγμα αιτήματος

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

Η επιτυχής απόκριση επιστρέφει ένα WhatsNewResponse.

Παράδειγμα απόκρισης

{
  "entries": [
    {
      "category": "new",
      "date": "2026-10-17",
      "emoji": "↔️",
      "icon": "mdi-arrow-expand-all",
      "id": "2026-10-17-website-chat-resize",
      "title": {
        "el": "Οι επισκέπτες μπορούν πλέον να μεγαλώσουν το chat του site.",
        "en": "Visitors can now make the website chat bigger."
      }
    }
  ],
  "known": true,
  "muted": false,
  "seen": "2026-10-10-kpis-whole-window"
}

GET /v1/usage#

Cost usage. Per-month cost aggregate. Pass ?month=YYYY-MM for a single month. The provider cost fields (stt_*, llm_*, tts_*) add up only what ran on your own provider keys (BYOK), as each call record says, and are shown for a stage only when some of that stage was yours. A month holding a call recorded before Voiceland began recording which key served each stage shows no cost. total_micros and total_usd add up the stages shown, and a month with none of yours carries call_count and talk_seconds alone. Your own charges are unaffected.

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

Παράδειγμα απόκρισης

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

Σχήματα#

AgentStat#

AgentStatsResponse#

AiReportConfigRequest#

AiReportConfigResponse#

AiReportGenerateRequest#

AiReportWire#

AiReportsResponse#

AssignedPlan#

BusinessHoursDayWire#

BusinessHoursRangeWire#

BusinessHoursRequest#

BusinessHoursResponse#

ChatKPI#

Cluster#

ContainmentKPI#

CostKPI#

DayCount#

EmergingTopicsResponse#

EndUserEraseResponse#

EndUserListResponse#

EndUserMemoryWire#

EndUserPolicyRequest#

EndUserPolicyResponse#

EndUserProfileWire#

Error#

Error envelope returned for non-2xx responses.

EscalationKPI#

EvalSummary#

FcrKPI#

FeedbackKPI#

GoalKPI#

IntentKPI#

IntentRateRow#

KpisResponse#

MetricsBlock#

NegativeConversation#

NegativeSentimentResponse#

PrivacyPolicyRequest#

PrivacyPolicyResponse#

QualityKPI#

RateCount#

RefusalSummary#

Refused new conversations this month.

ReportData#

SentimentKPI#

Target#

TopicCount#

TopicKPI#

WalletStatus#

WhatsNewEntry#

WhatsNewResponse#