Dataset Knowledge

Endpoints for associating Datasets with an Assistant so it can draw on that data as domain knowledge.

Every knowledge route is gated by ai.verify (AI must be enabled on the tenant AND the caller must have AI access). The create and delete routes additionally require permission.assistant.write on the looked-up Assistant. There is no BYOK gate on these routes.

In the path, {datasetId} is always the Dataset's UUID, not its natural id (owner:slug). All five routes are deterministic database operations, so each one is captured below.

GET /api/assistants/{id}/datasets

List the Dataset knowledge associations for an Assistant.

Authentication: Required (AI access via ai.verify)

Response:

A HAL collection envelope ({ start, count, total }) embedding inf:assistant-dataset rows. Each row carries the association's filter and eager-loads the full inf:dataset (its fields, query, and the filters the caller may see).

List dataset knowledgeGET /api/assistants/00000000-0000-4000-8000-000000000001/datasets

GET /api/assistants/{id}/datasets is a HAL collection ({ start, count, total }) embedding inf:assistant-dataset rows. Each row eager-loads the full inf:dataset (its fields, query, and public-or-owned filters). Requires AI access (ai.verify).

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/assistants/00000000-0000-4000-8000-000000000001/datasets"
    }
  },
  "start": 0,
  "count": 1,
  "total": 1,
  "_embedded": {
    "inf:assistant-dataset": [
      {
        "_links": {
          "self": {
            "href": "https://informer.example.com/api/assistants/00000000-0000-4000-8000-000000000001/datasets/00000000-0000-4000-8000-000000000002"
          }
        },
        "id": "00000000-0000-4000-8000-000000000003",
        "assistantId": "00000000-0000-4000-8000-000000000001",
        "datasetId": "00000000-0000-4000-8000-000000000002",
        "filter": {
          "region": "North America"
        },
        "createdAt": "2026-01-15T16:20:00.000Z",
        "updatedAt": "2026-01-15T16:20:00.000Z",
        "tenant": "acme",
        "snapshots": null,
        "_embedded": {
          "inf:dataset": {
            "_links": {
              "self": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data"
              },
              "inf:draft": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/draft"
              },
              "inf:run": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/_run"
              },
              "inf:benchmark": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/_benchmark"
              },
              "inf:refresh": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/_refresh"
              },
              "inf:data": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/data{?start,limit,q,sort,show,report}",
                "templated": true
              },
              "inf:user-settings": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/settings"
              },
              "inf:query": {
                "href": "https://informer.example.com/api/queries/"
              },
              "inf:owner": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/owner"
              },
              "inf:search": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/_search{?query,_source,sort,from,size,searchType,aggs,report,aggregations,alias,snapshots}",
                "templated": true
              },
              "inf:mapping": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/mapping"
              },
              "inf:job-templates": {
                "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/job-templates"
              },
              "inf:fields": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/fields"
              },
              "inf:count": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/count"
              },
              "inf:comments": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/comments"
              },
              "inf:visuals": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/visuals"
              },
              "inf:visual-templates": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/visual-templates"
              },
              "inf:dataset-tags": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/tags"
              },
              "inf:dataset-tag": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/tags/{tagId}",
                "templated": true
              },
              "inf:discover": {
                "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/discover"
              },
              "inf:filters": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/filters"
              },
              "inf:dataset-shares": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/shares"
              },
              "inf:flow": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/flow"
              },
              "inf:group": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/group"
              },
              "inf:group-rows": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/group-rows"
              },
              "inf:dataset-share": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/shares/{principalId}",
                "templated": true
              },
              "inf:import": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/_import"
              },
              "inf:exceptions": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/_exceptions"
              },
              "inf:search-aggregates": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/_search-aggregates"
              },
              "inf:exporters": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/exporters"
              },
              "inf:favorite": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/favorite"
              },
              "inf:export-bundle": {
                "href": "https://informer.example.com/api/datasets/admin%3Asales-data/_export"
              },
              "edit": {
                "href": "https://informer.example.com/api/reports/admin%3Asales-data/_edit"
              }
            },
            "naturalId": "admin:sales-data",
            "permissions": {
              "edit": true,
              "share": true,
              "delete": true,
              "write": true,
              "addVisual": true,
              "deleteVisual": true,
              "changeOwner": true,
              "copy": true,
              "rename": true,
              "refresh": true,
              "modifyFlows": true,
              "replaceFile": true,
              "modifySettings": true,
              "createDataView": true,
              "assignTags": true,
              "createFilter": true,
              "scriptFields": true,
              "setIndex": false
            },
            "id": "00000000-0000-4000-8000-000000000002",
            "tenant": "acme",
            "ownerId": "admin",
            "slug": "sales-data",
            "name": "Sales Data",
            "description": "Historical sales records",
            "embedded": false,
            "esIndex": null,
            "esIndexName": "sales-data",
            "esType": "data",
            "records": null,
            "size": null,
            "source": null,
            "sourceId": null,
            "params": {},
            "dataUpdatedAt": null,
            "dataExpiresAt": null,
            "ttl": null,
            "append": false,
            "shared": false,
            "timestampField": null,
            "lastDurationMillis": "1500",
            "windowSize": 500,
            "settings": {},
            "flow": [],
            "esId": null,
            "lastQueriedAt": null,
            "esWorkers": 1,
            "datasetFieldReportAccess": false,
            "parentId": null,
            "templateProcessorId": null,
            "deleteDate": null,
            "createdAt": "2026-01-15T16:20:00.000Z",
            "updatedAt": "2026-01-15T16:20:00.000Z",
            "datasourceId": null,
            "reportId": null,
            "queryId": null,
            "editingId": null,
            "folderId": null,
            "query": null,
            "_embedded": {
              "inf:field": [],
              "inf:filter": []
            }
          }
        }
      }
    ]
  }
}

Captured from the API examples test suite; ids and timestamps are normalized.

Association properties:

Field	Type	Description
id	string (UUID)	Association id
assistantId	string	Owning Assistant id
datasetId	string (UUID)	Associated Dataset's UUID
filter	object | null	Optional filter criteria restricting the data
snapshots	object | null	Snapshot settings, when configured
createdAt / updatedAt	date	Timestamps

---

POST /api/assistants/{id}/datasets

Associate a Dataset with an Assistant.

Authentication: Required (AI access)

Pre-blocks: ai.verify, assistant.lookup, permission.assistant.write, dataset.lookup(payload.datasetId)

Request Body:

The payload is stripUnknown, so unrecognized fields are dropped.

Field	Type	Required	Description
datasetId	string (UUID)	Yes	Dataset UUID to associate; resolved via dataset.lookup (an unknown id answers 404)
filter	object	No	Optional filter criteria to restrict the data the Assistant can access

Example Request:

{
  "datasetId": "00000000-0000-4000-8000-000000000002",
  "filter": {
    "status": "active"
  }
}

Response:

Responds 201 Created with the new association and a Location header pointing at it.

Associate a dataset with an assistantPOST /api/assistants/00000000-0000-4000-8000-000000000001/datasets

POST /api/assistants/{id}/datasets associates a dataset. Payload is { datasetId (required), filter? } and is stripUnknown. `datasetId` is the Dataset UUID, resolved via dataset.lookup (unknown -> 404). Requires assistant:write. Responds 201 with a Location header pointing at the new association.

Request body

{
  "datasetId": "00000000-0000-4000-8000-000000000002",
  "filter": {
    "status": "active"
  }
}

Response · 201

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/assistants/00000000-0000-4000-8000-000000000001/datasets/00000000-0000-4000-8000-000000000002"
    }
  },
  "id": "00000000-0000-4000-8000-000000000003",
  "tenant": "acme",
  "assistantId": "00000000-0000-4000-8000-000000000001",
  "datasetId": "00000000-0000-4000-8000-000000000002",
  "filter": {
    "status": "active"
  },
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "createdAt": "2026-01-15T16:20:00.000Z"
}

Captured from the API examples test suite; ids and timestamps are normalized.

Use the UUID

datasetId must be the Dataset's UUID, not its natural id (owner:slug). An id the caller cannot see answers 404 from dataset.lookup before the association is created.

---

GET /api/assistants/{id}/datasets/{datasetId}

Retrieve a single Dataset association.

Authentication: Required (AI access)

Pre-blocks: ai.verify, then the assistant-dataset lookup

Path Parameters:

Parameter	Type	Description
id	string	Assistant id
datasetId	string (UUID)	Associated Dataset's UUID

Response:

The single AssistantDataset (its filter) with the embedded inf:dataset (fields, query, filters).

Get a dataset associationGET /api/assistants/00000000-0000-4000-8000-000000000001/datasets/00000000-0000-4000-8000-000000000002

GET /api/assistants/{id}/datasets/{datasetId} returns the single AssistantDataset (its filter) with the embedded inf:dataset (fields, query, filters). `{datasetId}` is the Dataset UUID. Requires AI access.

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/assistants/00000000-0000-4000-8000-000000000001/datasets/00000000-0000-4000-8000-000000000002"
    }
  },
  "id": "00000000-0000-4000-8000-000000000003",
  "assistantId": "00000000-0000-4000-8000-000000000001",
  "datasetId": "00000000-0000-4000-8000-000000000002",
  "filter": {
    "region": "North America"
  },
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "tenant": "acme",
  "snapshots": null,
  "_embedded": {
    "inf:dataset": {
      "_links": {
        "self": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data"
        },
        "inf:draft": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/draft"
        },
        "inf:run": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/_run"
        },
        "inf:benchmark": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/_benchmark"
        },
        "inf:refresh": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/_refresh"
        },
        "inf:data": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/data{?start,limit,q,sort,show,report}",
          "templated": true
        },
        "inf:user-settings": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/settings"
        },
        "inf:query": {
          "href": "https://informer.example.com/api/queries/"
        },
        "inf:owner": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/owner"
        },
        "inf:search": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/_search{?query,_source,sort,from,size,searchType,aggs,report,aggregations,alias,snapshots}",
          "templated": true
        },
        "inf:mapping": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/mapping"
        },
        "inf:job-templates": {
          "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/job-templates"
        },
        "inf:fields": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/fields"
        },
        "inf:count": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/count"
        },
        "inf:comments": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/comments"
        },
        "inf:visuals": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/visuals"
        },
        "inf:visual-templates": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/visual-templates"
        },
        "inf:dataset-tags": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/tags"
        },
        "inf:dataset-tag": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/tags/{tagId}",
          "templated": true
        },
        "inf:discover": {
          "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/discover"
        },
        "inf:filters": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/filters"
        },
        "inf:dataset-shares": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/shares"
        },
        "inf:flow": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/flow"
        },
        "inf:group": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/group"
        },
        "inf:group-rows": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/group-rows"
        },
        "inf:dataset-share": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/shares/{principalId}",
          "templated": true
        },
        "inf:import": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/_import"
        },
        "inf:exceptions": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/_exceptions"
        },
        "inf:search-aggregates": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/_search-aggregates"
        },
        "inf:exporters": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/exporters"
        },
        "inf:favorite": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/favorite"
        },
        "inf:export-bundle": {
          "href": "https://informer.example.com/api/datasets/admin%3Asales-data/_export"
        },
        "edit": {
          "href": "https://informer.example.com/api/reports/admin%3Asales-data/_edit"
        }
      },
      "naturalId": "admin:sales-data",
      "permissions": {
        "edit": true,
        "share": true,
        "delete": true,
        "write": true,
        "addVisual": true,
        "deleteVisual": true,
        "changeOwner": true,
        "copy": true,
        "rename": true,
        "refresh": true,
        "modifyFlows": true,
        "replaceFile": true,
        "modifySettings": true,
        "createDataView": true,
        "assignTags": true,
        "createFilter": true,
        "scriptFields": true,
        "setIndex": false
      },
      "id": "00000000-0000-4000-8000-000000000002",
      "tenant": "acme",
      "ownerId": "admin",
      "slug": "sales-data",
      "name": "Sales Data",
      "description": "Historical sales records",
      "embedded": false,
      "esIndex": null,
      "esIndexName": "sales-data",
      "esType": "data",
      "records": null,
      "size": null,
      "source": null,
      "sourceId": null,
      "params": {},
      "dataUpdatedAt": null,
      "dataExpiresAt": null,
      "ttl": null,
      "append": false,
      "shared": false,
      "timestampField": null,
      "lastDurationMillis": "1500",
      "windowSize": 500,
      "settings": {},
      "flow": [],
      "esId": null,
      "lastQueriedAt": null,
      "esWorkers": 1,
      "datasetFieldReportAccess": false,
      "parentId": null,
      "templateProcessorId": null,
      "deleteDate": null,
      "createdAt": "2026-01-15T16:20:00.000Z",
      "updatedAt": "2026-01-15T16:20:00.000Z",
      "datasourceId": null,
      "reportId": null,
      "queryId": null,
      "editingId": null,
      "folderId": null,
      "_embedded": {
        "inf:field": [],
        "inf:filter": []
      }
    }
  }
}

Captured from the API examples test suite; ids and timestamps are normalized.

---

PUT /api/assistants/{id}/datasets/{datasetId}

Create or update a Dataset association. This route is an upsert: it creates the association when it is absent, otherwise it updates the existing row. It runs in a database transaction.

Authentication: Required (AI access)

Pre-blocks: ai.verify, then the assistant-dataset lookup

The Assistant write permission is not re-checked on PUT (only ai.verify and the association lookup run). The read_access scope on the upsert still constrains which row the caller can touch.

Request Body:

The payload is allowUnknown.

Field	Type	Description
datasetId	string (UUID)	Optional Dataset UUID for the upsert
filter	object	Filter criteria to set on the association
snapshots	object	Snapshot settings; drives a SnapshotSettings upsert

Example Request:

{
  "filter": {
    "region": "North America",
    "year": 2024
  }
}

Response:

Responds 200 with the AssistantDataset.

Update a dataset associationPUT /api/assistants/00000000-0000-4000-8000-000000000001/datasets/00000000-0000-4000-8000-000000000002

PUT /api/assistants/{id}/datasets/{datasetId} is an upsert (creates if absent, else updates) and returns 200 with the AssistantDataset. Payload accepts { datasetId?, filter?, snapshots? } (allowUnknown); `snapshots` drives SnapshotSettings upsert. Runs in a DB transaction.

Request body

{
  "filter": {
    "region": "North America",
    "year": 2024
  }
}

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/assistants/00000000-0000-4000-8000-000000000001/datasets/00000000-0000-4000-8000-000000000002"
    }
  },
  "id": "00000000-0000-4000-8000-000000000003",
  "assistantId": "00000000-0000-4000-8000-000000000001",
  "datasetId": "00000000-0000-4000-8000-000000000002",
  "filter": {
    "year": 2024,
    "region": "North America"
  },
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "tenant": "acme",
  "snapshots": null,
  "dataset": {
    "naturalId": "admin:sales-data",
    "permissions": {
      "edit": true,
      "share": true,
      "delete": true,
      "write": true,
      "addVisual": true,
      "deleteVisual": true,
      "changeOwner": true,
      "copy": true,
      "rename": true,
      "refresh": true,
      "modifyFlows": true,
      "replaceFile": true,
      "modifySettings": true,
      "createDataView": true,
      "assignTags": true,
      "createFilter": true,
      "scriptFields": true,
      "setIndex": false
    },
    "id": "00000000-0000-4000-8000-000000000002",
    "tenant": "acme",
    "ownerId": "admin",
    "slug": "sales-data",
    "name": "Sales Data",
    "description": "Historical sales records",
    "embedded": false,
    "esIndex": null,
    "esIndexName": "sales-data",
    "esType": "data",
    "records": null,
    "size": null,
    "source": null,
    "sourceId": null,
    "params": {},
    "dataUpdatedAt": null,
    "dataExpiresAt": null,
    "ttl": null,
    "append": false,
    "shared": false,
    "timestampField": null,
    "lastDurationMillis": "1500",
    "windowSize": 500,
    "settings": {},
    "flow": [],
    "esId": null,
    "lastQueriedAt": null,
    "esWorkers": 1,
    "datasetFieldReportAccess": false,
    "parentId": null,
    "templateProcessorId": null,
    "deleteDate": null,
    "createdAt": "2026-01-15T16:20:00.000Z",
    "updatedAt": "2026-01-15T16:20:00.000Z",
    "datasourceId": null,
    "reportId": null,
    "queryId": null,
    "editingId": null,
    "folderId": null
  }
}

Captured from the API examples test suite; ids and timestamps are normalized.

---

DELETE /api/assistants/{id}/datasets/{datasetId}

Remove a Dataset association from an Assistant.

Authentication: Required (AI access)

Pre-blocks: ai.verify, assistant.lookup, permission.assistant.write, dataset.lookup(params.datasetId)

Path Parameters:

Parameter	Type	Description
id	string	Assistant id
datasetId	string (UUID)	Associated Dataset's UUID

Response:

Responds 200 with an empty body (Informer convention), not 204.

Remove a dataset associationDELETE /api/assistants/00000000-0000-4000-8000-000000000001/datasets/00000000-0000-4000-8000-000000000002

DELETE /api/assistants/{id}/datasets/{datasetId} removes the association (db.remove) and returns 200 with an EMPTY body (Informer convention), NOT 204 as some docs claim. `{datasetId}` is the Dataset UUID; requires assistant:write.

Response · 200 · no body

Captured from the API examples test suite; ids and timestamps are normalized.

---

Dataset Filtering

When associating a Dataset with an Assistant, you can optionally specify a filter to restrict which records the Assistant can access. The same syntax applies on POST and PUT.

Full Access

{
  "datasetId": "00000000-0000-4000-8000-000000000002"
}

Filtered Access

{
  "datasetId": "00000000-0000-4000-8000-000000000002",
  "filter": {
    "region": "North America",
    "year": 2024
  }
}

Advanced Filters

{
  "datasetId": "00000000-0000-4000-8000-000000000002",
  "filter": {
    "amount": { "$gte": 1000 },
    "status": { "$in": ["closed", "won"] },
    "created_at": { "$gte": "2024-01-01" }
  }
}

Filter criteria uses the same syntax as Dataset query filters.