Voiceland AI

API-Referenz / Data sources

Data sources

Die Endpoints der Gruppe Data sources der Voiceland AI API, mit Parametern, Schemata und Beispielen mit curl.

Zuletzt aktualisiert:

Die Beschreibungen der Endpoints und der Felder erscheinen auf Englisch, genau so, wie die API sie ausliefert. Das ist Absicht: Sie lesen hier, was Sie auch in den Antworten sehen.

GET /v1/connectors#

List connectors. Returns the connector presets a data source can use, in display order. Each carries a logo (GET /v1/connectors/{id}/logo.svg, served without a key so a console can show it), the header the provider expects the token in, and whether its mapping is locked (a branded connector whose shape is known) or yours to describe (generic-catalog). text-url takes any URL whose body is already text.

Antworten

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

Beispielanfrage

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

Beispielantwort

{
  "items": [
    {
      "auth_header": "access_token",
      "default_refresh_s": 3600,
      "description": "Menu and catalogue of an iotSoft kiosk.",
      "id": "iotsoft",
      "logo": "/v1/connectors/iotsoft/logo.svg",
      "mapping_locked": true,
      "name": "iotSoft",
      "order": 1,
      "transform": "catalog",
      "url_placeholder": "https://example.com/api/menu",
      "vendor": "iotSoft"
    }
  ]
}

GET /v1/data-sources#

List data sources. Returns your data sources with the metadata of their latest snapshot, status, size, when it was fetched. Never the token and never the text; the preview route returns the text.

Antworten

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

Beispielanfrage

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

Beispielantwort

{
  "items": [
    {
      "auth_header": "access_token",
      "connector_id": "iotsoft",
      "connector_name": "iotSoft",
      "created_at": "2026-09-13T12:00:00Z",
      "enabled": true,
      "has_secret": true,
      "id": "ds-3d60ba7619",
      "max_prompt_chars": 15000,
      "name": "Menu (iotSoft)",
      "next_due_at": "2026-09-13T13:00:00Z",
      "refresh_interval_s": 3600,
      "secret_name": "ds-3d60ba7619",
      "snapshot": {
        "categories": 14,
        "changed": true,
        "chars": 14792,
        "checked_at": "2026-09-13T13:00:00Z",
        "duration_ms": 1070,
        "fetched_at": "2026-09-13T12:00:00Z",
        "hash": "9f1c2e…",
        "items": 166,
        "status": "ok"
      },
      "transform": "catalog",
      "updated_at": "2026-09-13T12:00:00Z",
      "url": "https://example.com/api/menu"
    }
  ]
}

POST /v1/data-sources#

Create a data source. Creates a data source and fetches it once before answering (under the refresh lease, so a background node cannot fetch it a second time), so the response carries the first snapshot and you see at once whether the URL, token and mapping work. token is write-only: it is stored as a secret named after the source and no read ever returns it. refresh_interval_s is clamped to at least 300 (default 3600); max_prompt_chars defaults to 15000. A branded connector ignores mapping; generic-catalog requires one that validates. Attach the returned id to an agent through its data_sources list.

Anfragetext

application/json Schema: DataSourceRequest

Feld Typ Erforderlich Beschreibung
auth_header string
connector_id string Ja
enabled boolean
mapping CatalogMapping Dot-separated paths from the response root describing a JSON catalogue.
max_prompt_chars integer
name string Ja
refresh_interval_s integer
token string
url string Ja

Antworten

Code Beschreibung
201 Created, with the first snapshot.
400 unknown_connector, invalid_url (must start with http:// or https://), url_not_allowed (a loopback, private-network or cloud-metadata address, the message names the rule) or invalid_mapping (the message names the missing path).
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Beispielanfrage

curl -X POST "https://api.voiceland.ai/v1/data-sources" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "connector_id": "iotsoft",
  "name": "Menu (iotSoft)",
  "refresh_interval_s": 3600,
  "token": "kiosk_xxxxxxxxxxxxxxxx",
  "url": "https://example.com/api/menu"
}'

Eine erfolgreiche Antwort liefert ein DataSourceView.

Beispielantwort

{
  "auth_header": "access_token",
  "connector_id": "iotsoft",
  "connector_name": "iotSoft",
  "created_at": "2026-09-13T12:00:00Z",
  "enabled": true,
  "has_secret": true,
  "id": "ds-3d60ba7619",
  "max_prompt_chars": 15000,
  "name": "Menu (iotSoft)",
  "next_due_at": "2026-09-13T13:00:00Z",
  "refresh_interval_s": 3600,
  "secret_name": "ds-3d60ba7619",
  "snapshot": {
    "categories": 14,
    "changed": true,
    "chars": 14792,
    "checked_at": "2026-09-13T13:00:00Z",
    "duration_ms": 1070,
    "fetched_at": "2026-09-13T12:00:00Z",
    "hash": "9f1c2e…",
    "items": 166,
    "status": "ok"
  },
  "transform": "catalog",
  "updated_at": "2026-09-13T12:00:00Z",
  "url": "https://example.com/api/menu"
}

DELETE /v1/data-sources/{id}#

Delete a data source. Deletes the source and the secret holding its token. An agent that still lists the id skips it at call time.

Parameter

Name Ort Typ Erforderlich Beschreibung
id path string Ja Data source id (ds-…).

Antworten

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

Beispielanfrage

curl -X DELETE "https://api.voiceland.ai/v1/data-sources/{id}" \
  -H "Authorization: Bearer VL_API_KEY"

GET /v1/data-sources/{id}#

Get a data source. Returns one data source with its latest snapshot metadata.

Parameter

Name Ort Typ Erforderlich Beschreibung
id path string Ja Data source id (ds-…).

Antworten

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

Beispielanfrage

curl "https://api.voiceland.ai/v1/data-sources/{id}" \
  -H "Authorization: Bearer VL_API_KEY"

Eine erfolgreiche Antwort liefert ein DataSourceView.

Beispielantwort

{
  "auth_header": "access_token",
  "connector_id": "iotsoft",
  "connector_name": "iotSoft",
  "created_at": "2026-09-13T12:00:00Z",
  "enabled": true,
  "has_secret": true,
  "id": "ds-3d60ba7619",
  "max_prompt_chars": 15000,
  "name": "Menu (iotSoft)",
  "next_due_at": "2026-09-13T13:00:00Z",
  "refresh_interval_s": 3600,
  "secret_name": "ds-3d60ba7619",
  "snapshot": {
    "categories": 14,
    "changed": true,
    "chars": 14792,
    "checked_at": "2026-09-13T13:00:00Z",
    "duration_ms": 1070,
    "fetched_at": "2026-09-13T12:00:00Z",
    "hash": "9f1c2e…",
    "items": 166,
    "status": "ok"
  },
  "transform": "catalog",
  "updated_at": "2026-09-13T12:00:00Z",
  "url": "https://example.com/api/menu"
}

PUT /v1/data-sources/{id}#

Update a data source. Replaces the source's settings and fetches it again before answering. Omit token to keep the stored one; send enabled: false to stop refreshing and stop injecting without deleting.

Parameter

Name Ort Typ Erforderlich Beschreibung
id path string Ja Data source id (ds-…).

Anfragetext

application/json Schema: DataSourceRequest

Feld Typ Erforderlich Beschreibung
auth_header string
connector_id string Ja
enabled boolean
mapping CatalogMapping Dot-separated paths from the response root describing a JSON catalogue.
max_prompt_chars integer
name string Ja
refresh_interval_s integer
token string
url string Ja

Antworten

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

Beispielanfrage

curl -X PUT "https://api.voiceland.ai/v1/data-sources/{id}" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "connector_id": "iotsoft",
  "name": "Menu (iotSoft)",
  "refresh_interval_s": 3600,
  "token": "kiosk_xxxxxxxxxxxxxxxx",
  "url": "https://example.com/api/menu"
}'

Eine erfolgreiche Antwort liefert ein DataSourceView.

Beispielantwort

{
  "auth_header": "access_token",
  "connector_id": "iotsoft",
  "connector_name": "iotSoft",
  "created_at": "2026-09-13T12:00:00Z",
  "enabled": true,
  "has_secret": true,
  "id": "ds-3d60ba7619",
  "max_prompt_chars": 15000,
  "name": "Menu (iotSoft)",
  "next_due_at": "2026-09-13T13:00:00Z",
  "refresh_interval_s": 3600,
  "secret_name": "ds-3d60ba7619",
  "snapshot": {
    "categories": 14,
    "changed": true,
    "chars": 14792,
    "checked_at": "2026-09-13T13:00:00Z",
    "duration_ms": 1070,
    "fetched_at": "2026-09-13T12:00:00Z",
    "hash": "9f1c2e…",
    "items": 166,
    "status": "ok"
  },
  "transform": "catalog",
  "updated_at": "2026-09-13T12:00:00Z",
  "url": "https://example.com/api/menu"
}

GET /v1/data-sources/{id}/preview#

Preview the text. Returns the exact text the agent reads at call start, with the snapshot metadata. The only route that returns the text.

Parameter

Name Ort Typ Erforderlich Beschreibung
id path string Ja Data source id (ds-…).

Antworten

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

Beispielanfrage

curl "https://api.voiceland.ai/v1/data-sources/{id}/preview" \
  -H "Authorization: Bearer VL_API_KEY"

Beispielantwort

{
  "id": "ds-3d60ba7619",
  "snapshot": {
    "categories": 14,
    "changed": true,
    "chars": 14792,
    "checked_at": "2026-09-13T13:00:00Z",
    "duration_ms": 1070,
    "fetched_at": "2026-09-13T12:00:00Z",
    "hash": "9f1c2e…",
    "items": 166,
    "status": "ok"
  },
  "text": "## ΠΙΤΕΣ (όλα: πατάτες, ντομάτα, κρεμμύδι)\n- Πίτα γύρος χοιρινό, 4,50 €\n  σάλτσα (επιλογή 1): τζατζίκι, μουστάρδα …"
}

POST /v1/data-sources/{id}/refresh#

Refresh now. Fetches the source outside its schedule and returns it with the result. A fetch that finds the same text advances snapshot.checked_at and the schedule and rewrites nothing; a failed fetch keeps the previous text in use and notes the reason in snapshot.error.

Parameter

Name Ort Typ Erforderlich Beschreibung
id path string Ja Data source id (ds-…).

Antworten

Code Beschreibung
200 Success.
401 Missing or invalid API key.
409 refresh_in_progress, another node is fetching this source right now; try again in a moment.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Beispielanfrage

curl -X POST "https://api.voiceland.ai/v1/data-sources/{id}/refresh" \
  -H "Authorization: Bearer VL_API_KEY"

Eine erfolgreiche Antwort liefert ein DataSourceView.

Beispielantwort

{
  "auth_header": "access_token",
  "connector_id": "iotsoft",
  "connector_name": "iotSoft",
  "created_at": "2026-09-13T12:00:00Z",
  "enabled": true,
  "has_secret": true,
  "id": "ds-3d60ba7619",
  "max_prompt_chars": 15000,
  "name": "Menu (iotSoft)",
  "next_due_at": "2026-09-13T13:00:00Z",
  "refresh_interval_s": 3600,
  "secret_name": "ds-3d60ba7619",
  "snapshot": {
    "categories": 14,
    "changed": true,
    "chars": 14792,
    "checked_at": "2026-09-13T13:00:00Z",
    "duration_ms": 1070,
    "fetched_at": "2026-09-13T12:00:00Z",
    "hash": "9f1c2e…",
    "items": 166,
    "status": "ok"
  },
  "transform": "catalog",
  "updated_at": "2026-09-13T12:00:00Z",
  "url": "https://example.com/api/menu"
}

Schemata#

CatalogMapping#

Dot-separated paths from the response root describing a JSON catalogue.

Feld Typ Erforderlich Beschreibung
category_name string Ja
choice_group_hints array of string Substrings that mark a group as a choice regardless of its size.
currency string
drop_gibberish boolean Drop option entries that are not words.
group_item_name string
group_item_price array of string
group_items string
group_max string Field carrying how many options may be chosen. A free group allowing more than two is read as the item's contents; at most two, as a choice.
group_name string
group_required string
groups_path string
ingredient_name string
ingredients_path string
item_description string
item_name string Ja
item_price array of string Ja One or more fields; the first present wins.
items_path string Ja
list_path string Ja
skip_categories array of string Category names to drop (fees, staff-only, raw materials).

DataSourceRequest#

Feld Typ Erforderlich Beschreibung
auth_header string
connector_id string Ja
enabled boolean
mapping CatalogMapping Dot-separated paths from the response root describing a JSON catalogue.
max_prompt_chars integer
name string Ja
refresh_interval_s integer
token string
url string Ja

DataSourceSnapshot#

Metadata of the latest fetch. The text itself is only on the preview route.

Feld Typ Erforderlich Beschreibung
categories integer
changed boolean Ja Whether the last fetch produced different text from the one before. An unchanged fetch writes only the schedule and checked_at.
chars integer Ja Size of the text the agent reads, after the cap.
checked_at string (date-time) The last successful fetch. A fetch that finds the same text advances only this (and the schedule); nothing else is rewritten.
duration_ms integer
error string Why the last fetch failed: the reason when status is error, or last refresh failed: … on a source still serving its previous good text.
fetched_at string (date-time) Ja When the current text was captured, i.e. the last fetch that changed it.
hash string
items integer
status string Ja ok or error. A fetch that fails after a good one keeps ok, keeps the text, and notes the failure in error; only a source that never succeeded is error.

DataSourceView#

Feld Typ Erforderlich Beschreibung
auth_header string
connector_id string Ja
connector_name string
created_at string (date-time) Ja
enabled boolean Ja
has_secret boolean Ja
id string Ja
mapping CatalogMapping Dot-separated paths from the response root describing a JSON catalogue.
max_prompt_chars integer
name string Ja
next_due_at string (date-time) Ja When the next background fetch is due.
refresh_interval_s integer Ja
secret_name string Name of the secret holding the token (ds-<id>). Absent when no token was given.
snapshot DataSourceSnapshot Metadata of the latest fetch. The text itself is only on the preview route.
transform string Ja catalog (categories, items, prices, option groups) or passthrough (the body as text).
updated_at string (date-time) Ja
url string Ja

Error#

Error envelope returned for non-2xx responses.

Feld Typ Erforderlich Beschreibung
error object Ja

Die Konsole

Diese Seiten sind schreibgeschützt. Der Testanruf, die API-Schlüssel und die aktuelle API-Referenz finden Sie in der Konsole, in der Ihr Konto angemeldet ist.

Konsole öffnen