Data sources

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

Zuletzt aktualisiert: 2026-10-20

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. The kb-document connector reads a written or uploaded document of your own knowledge base instead of a URL: give kb_collection_id and kb_document_id (no url, no token). It always uses the published version, so an edit reaches calls when it is published, and it is read again at once on every publish, archive or delete of that document. Its text is used as written and is refused, not cut, when it is longer than max_prompt_chars. role is data (default: your own feed, which the agent may quote) or guidance (internal instructions the agent follows and never discloses, such as a sales playbook). An agent cannot have guidance from a collection it can search: saving that combination answers 409 guidance_searchable. 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
`kb_collection_id`	string
`kb_document_id`	string
`mapping`	`CatalogMapping`		Dot-separated paths from the response root describing a JSON catalogue.
`max_prompt_chars`	integer
`name`	string	Ja
`refresh_interval_s`	integer
`role`	string
`token`	string
`url`	string

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
`kb_collection_id`	string
`kb_document_id`	string
`mapping`	`CatalogMapping`		Dot-separated paths from the response root describing a JSON catalogue.
`max_prompt_chars`	integer
`name`	string	Ja
`refresh_interval_s`	integer
`role`	string
`token`	string
`url`	string

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
`kb_collection_id`	string
`kb_document_id`	string
`mapping`	`CatalogMapping`		Dot-separated paths from the response root describing a JSON catalogue.
`max_prompt_chars`	integer
`name`	string	Ja
`refresh_interval_s`	integer
`role`	string
`token`	string
`url`	string

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
`source_version`	string
`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
`kb_collection_id`	string
`kb_document_id`	string
`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
`role`	string
`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

GET /v1/connectors#

Antworten

Beispielanfrage

Beispielantwort

GET /v1/data-sources#

Antworten

Beispielanfrage

Beispielantwort

POST /v1/data-sources#

Anfragetext

Antworten

Beispielanfrage

Beispielantwort

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

Parameter

Antworten

Beispielanfrage

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

Parameter

Antworten

Beispielanfrage

Beispielantwort

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

Parameter

Anfragetext

Antworten

Beispielanfrage

Beispielantwort

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

Parameter

Antworten

Beispielanfrage

Beispielantwort

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

Parameter

Antworten

Beispielanfrage

Beispielantwort

Schemata#

CatalogMapping#

DataSourceRequest#

DataSourceSnapshot#

DataSourceView#

Error#

Die Konsole

GET `/v1/connectors`#

GET `/v1/data-sources`#

POST `/v1/data-sources`#

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

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

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

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

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