Data sources

Описания endpoints и полей показаны на английском языке, ровно так, как их публикует API. Это наш выбор: здесь вы читаете то же, что увидите в ответах.

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.

Ответы

Пример запроса

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

Пример ответа

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

Ответы

Пример запроса

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

Пример ответа

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

Тело запроса

application/json Схема: DataSourceRequest

Ответы

Пример запроса

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

Успешный ответ возвращает DataSourceView.

Пример ответа

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

Параметры

Ответы

Пример запроса

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.

Параметры

Ответы

Пример запроса

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

Успешный ответ возвращает DataSourceView.

Пример ответа

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

Параметры

Тело запроса

application/json Схема: DataSourceRequest

Ответы

Пример запроса

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

Успешный ответ возвращает DataSourceView.

Пример ответа

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

Параметры

Ответы

Пример запроса

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

Пример ответа

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

Параметры

Ответы

Пример запроса

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

Успешный ответ возвращает DataSourceView.

Пример ответа

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

Схемы#

CatalogMapping#

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

DataSourceRequest#

DataSourceSnapshot#

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

DataSourceView#

Error#

Error envelope returned for non-2xx responses.