Skip to main content

Dataset Knowledge

Endpoints for associating datasets with assistants to provide domain knowledge.

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

List dataset knowledge associations for an assistant.

Authentication: Required (AI seat)

Response:

{
  "_links": {
    "self": { "href": "/api/assistants/{id}/datasets" }
  },
  "_embedded": {
    "inf:dataset-knowledge": [
      {
        "assistantId": "team:sales-assistant",
        "datasetId": "sales-data",
        "filter": {
          "region": "North America"
        },
        "dataset": {
          "id": "sales-data",
          "name": "Sales Data",
          "description": "Historical sales records",
          "fields": [
            {
              "name": "order_id",
              "label": "Order ID",
              "dataType": "string"
            },
            {
              "name": "amount",
              "label": "Amount",
              "dataType": "number"
            }
          ],
          "filters": [...],
          "query": {...},
          "_links": {
            "self": { "href": "/api/datasets/sales-data" }
          }
        }
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 1
}

Includes:

  • Full dataset details
  • Field definitions
  • Available filters
  • Query configuration (if applicable)

POST /api/assistants/{id}/datasets​

Associate a dataset with an assistant.

Permission: assistant:write

Request Body:

FieldTypeRequiredDescription
datasetIdstringYesDataset ID to associate
filterobjectNoOptional filter criteria to restrict data

Example Request:

{
  "datasetId": "customer-data",
  "filter": {
    "status": "active",
    "region": { "$in": ["US", "CA"] }
  }
}

Response: 201 Created

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

Get details for a specific dataset association.

Response: AssistantDataset object with full dataset details

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

Update dataset association (e.g., change filter).

Permission: assistant:write

Request Body:

FieldTypeDescription
filterobjectUpdate filter criteria

Response: Updated AssistantDataset object

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

Remove dataset association from assistant.

Permission: assistant:write

Response: 204 No Content

Dataset Filtering​

When associating a dataset with an assistant, you can optionally specify a filter to restrict which records the assistant can access:

Full Access​

{
  "datasetId": "sales-data"
}

Filtered Access​

{
  "datasetId": "sales-data",
  "filter": {
    "region": "North America",
    "year": 2024
  }
}

Advanced Filters​

{
  "datasetId": "sales-data",
  "filter": {
    "amount": { "$gte": 1000 },
    "status": { "$in": ["closed", "won"] },
    "created_at": { "$gte": "2024-01-01" }
  }
}

Filter criteria uses the same syntax as dataset query filters.