Data sources

The Data sources endpoints of the Voiceland AI API, with parameters, schemas and curl examples.

Last updated: 2026-09-23

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.

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/connectors" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

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

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/data-sources" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

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

Request body

application/json Schema: DataSourceRequest

Field	Type	Required	Description
`auth_header`	string
`connector_id`	string	Yes
`enabled`	boolean
`mapping`	`CatalogMapping`		Dot-separated paths from the response root describing a JSON catalogue.
`max_prompt_chars`	integer
`name`	string	Yes
`refresh_interval_s`	integer
`token`	string
`url`	string	Yes

Responses

Code	Description
`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.

Example request

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

A successful response returns a DataSourceView.

Example response

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

Parameters

Name	In	Type	Required	Description
`id`	`path`	string	Yes	Data source id (`ds-…`).

Responses

Code	Description
`204`	Deleted.
`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/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.

Parameters

Name	In	Type	Required	Description
`id`	`path`	string	Yes	Data source id (`ds-…`).

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/data-sources/{id}" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a DataSourceView.

Example response

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

Parameters

Name	In	Type	Required	Description
`id`	`path`	string	Yes	Data source id (`ds-…`).

Request body

application/json Schema: DataSourceRequest

Field	Type	Required	Description
`auth_header`	string
`connector_id`	string	Yes
`enabled`	boolean
`mapping`	`CatalogMapping`		Dot-separated paths from the response root describing a JSON catalogue.
`max_prompt_chars`	integer
`name`	string	Yes
`refresh_interval_s`	integer
`token`	string
`url`	string	Yes

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

A successful response returns a DataSourceView.

Example response

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

Parameters

Name	In	Type	Required	Description
`id`	`path`	string	Yes	Data source id (`ds-…`).

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/data-sources/{id}/preview" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

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

Parameters

Name	In	Type	Required	Description
`id`	`path`	string	Yes	Data source id (`ds-…`).

Responses

Code	Description
`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.

Example request

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

A successful response returns a DataSourceView.

Example response

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

Schemas#

CatalogMapping#

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

Field	Type	Required	Description
`category_name`	string	Yes
`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	Yes
`item_price`	array of string	Yes	One or more fields; the first present wins.
`items_path`	string	Yes
`list_path`	string	Yes
`skip_categories`	array of string		Category names to drop (fees, staff-only, raw materials).

DataSourceRequest#

Field	Type	Required	Description
`auth_header`	string
`connector_id`	string	Yes
`enabled`	boolean
`mapping`	`CatalogMapping`		Dot-separated paths from the response root describing a JSON catalogue.
`max_prompt_chars`	integer
`name`	string	Yes
`refresh_interval_s`	integer
`token`	string
`url`	string	Yes

DataSourceSnapshot#

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

Field	Type	Required	Description
`categories`	integer
`changed`	boolean	Yes	Whether the last fetch produced different text from the one before. An unchanged fetch writes only the schedule and `checked_at`.
`chars`	integer	Yes	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)	Yes	When the current text was captured, i.e. the last fetch that changed it.
`hash`	string
`items`	integer
`status`	string	Yes	`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#

Field	Type	Required	Description
`auth_header`	string
`connector_id`	string	Yes
`connector_name`	string
`created_at`	string (date-time)	Yes
`enabled`	boolean	Yes
`has_secret`	boolean	Yes
`id`	string	Yes
`mapping`	`CatalogMapping`		Dot-separated paths from the response root describing a JSON catalogue.
`max_prompt_chars`	integer
`name`	string	Yes
`next_due_at`	string (date-time)	Yes	When the next background fetch is due.
`refresh_interval_s`	integer	Yes
`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	Yes	`catalog` (categories, items, prices, option groups) or `passthrough` (the body as text).
`updated_at`	string (date-time)	Yes
`url`	string	Yes

Error#

Error envelope returned for non-2xx responses.

Field	Type	Required	Description
`error`	object	Yes

GET /v1/connectors#

Responses

Example request

Example response

GET /v1/data-sources#

Responses

Example request

Example response

POST /v1/data-sources#

Request body

Responses

Example request

Example response

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

Parameters

Responses

Example request

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

Parameters

Responses

Example request

Example response

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

Parameters

Request body

Responses

Example request

Example response

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

Parameters

Responses

Example request

Example response

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

Parameters

Responses

Example request

Example response

Schemas#

CatalogMapping#

DataSourceRequest#

DataSourceSnapshot#

DataSourceView#

Error#

The console

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`#