Data sources

Les descriptions des endpoints et des champs restent en anglais, telles que l'API les publie. C'est un choix délibéré : vous lisez ici ce que vous verrez aussi dans les réponses.

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.

Réponses

Exemple de requête

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

Exemple de réponse

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

Réponses

Exemple de requête

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

Exemple de réponse

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

Corps de la requête

application/json Schéma : DataSourceRequest

Réponses

Exemple de requête

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

Une réponse réussie renvoie un DataSourceView.

Exemple de réponse

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

Paramètres

Réponses

Exemple de requête

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.

Paramètres

Réponses

Exemple de requête

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

Une réponse réussie renvoie un DataSourceView.

Exemple de réponse

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

Paramètres

Corps de la requête

application/json Schéma : DataSourceRequest

Réponses

Exemple de requête

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

Une réponse réussie renvoie un DataSourceView.

Exemple de réponse

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

Paramètres

Réponses

Exemple de requête

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

Exemple de réponse

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

Paramètres

Réponses

Exemple de requête

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

Une réponse réussie renvoie un DataSourceView.

Exemple de réponse

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

Schémas#

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.