Datasets

Datasets allow you to upload data files (CSV, JSON) that the agent can reference when answering questions. Files are scoped by user context, ensuring multi-tenant isolation.

When to use datasets

Use datasets when you want to:

• Provide reference data like pricing tables, product catalogs, or configuration files
• Upload spreadsheets or reports for analysis
• Add context beyond your connected databases
• Work with data that isn’t stored in a database

Uploading via the dashboard

The simplest way to upload datasets is through the Inconvo dashboard. This is ideal for static reference data that isn’t stored in your connected databases.

1. Go to your agent’s Configure page in the Inconvo dashboard
2. Select Datasets from the sidebar
3. Enter the user context values that should have access to these files (e.g., organisationId: 1)
4. Drag and drop your CSV or JSON files, or click to browse
5. Optionally add notes to describe each file
6. Click Upload to save the files

Tip

Use dashboard uploads for static reference data that you manage. Use the API for dynamic uploads where end-users provide their own files.

Uploading via the API

For programmatic uploads or allowing end-users to upload their own files, use the API. Files are uploaded using multipart/form-data. Supported formats are CSV and JSON, with a maximum size of 10MB per file.

Note

Before using the API, configure your user context fields in the Inconvo dashboard under your agent’s Configure page. This defines the fields used to scope and isolate files.

Upload a file

Request

Node.js

import Inconvo from "@inconvoai/node";
import fs from "fs";

const client = new Inconvo({
  apiKey: process.env.INCONVO_API_KEY
});

// Upload with user context (must be JSON stringified)
const result = await client.datasets.upload({
  file: fs.createReadStream("./sales_data.csv"),
  userContext: JSON.stringify({ userId: 123 }),
  notes: "Q4 2024 sales report"
});

console.log(result.file);
// { name: "sales_data.csv", path: "...", size: 2048576 }

curl -X POST "https://app.inconvo.ai/api/v1/datasets" \
  -H "Authorization: Bearer $INCONVO_API_KEY" \
  -F "file=@./sales_data.csv" \
  -F "userContext={\"userId\": 123}" \
  -F "notes=Q4 2024 sales report"

Parameters

Parameter	Required	Description
file	Yes	The file to upload (binary stream or File object)
userContext	Yes	Context values as a JSON string (e.g., JSON.stringify({ userId: 123 }))
notes	No	Description or notes about the file

List files

Retrieve all files for a specific user context.

Request

Node.js

const files = await client.datasets.list({
  userContext: {
    userId: 123
  }
});

console.log(files);
// { files: ["sales_data.csv", "inventory.json"] }

curl -X GET "https://app.inconvo.ai/api/v1/datasets?userContext[userId]=123" \
  -H "Authorization: Bearer $INCONVO_API_KEY"

Delete a file

Remove a file by providing its filename and the matching user context.

Request

Node.js

const result = await client.datasets.delete("sales_data.csv", {
  userContext: {
    userId: 123
  }
});

console.log(result);
// { file: "sales_data.csv", success: true }

curl -X DELETE "https://app.inconvo.ai/api/v1/datasets/sales_data.csv?userContext[userId]=123" \
  -H "Authorization: Bearer $INCONVO_API_KEY"

How the agent uses datasets

When a user sends a message, the agent automatically has access to any dataset files matching the user context. The agent can:

• Read and analyze CSV/JSON data
• Join dataset information with database queries
• Answer questions about the uploaded files

For example, if you upload a pricing.csv file with product pricing through the dashboard, users can ask:

“What’s the price for the Enterprise plan?”

Or if a user uploads their own targets.csv file with sales targets, they can ask:

“How do our actual sales compare to the targets in my uploaded file?”

The agent will read both the database and the uploaded CSV to provide a combined analysis.

Example: End-user file uploads

Here’s how to allow end-users to upload their own files through your application:

// Server endpoint for file uploads (using multer for multipart parsing)
import Inconvo, { toFile } from "@inconvoai/node";
import multer from "multer";

const client = new Inconvo({ apiKey: process.env.INCONVO_API_KEY });
const upload = multer({ storage: multer.memoryStorage() });

app.post("/upload-dataset", upload.single("file"), async (req, res, next) => {
  // Get user context from session
  const context = {
    userId: req.session.userId
  };

  try {
    const result = await client.datasets.upload({
      // Use toFile() to convert buffer to uploadable format
      file: await toFile(req.file.buffer, req.file.originalname),
      userContext: JSON.stringify(context),
      notes: req.body.notes
    });

    return res.json(result);
  } catch (error) {
    next(error);
  }
});

// Client-side file input handler
const handleFileUpload = async (event) => {
  const file = event.target.files[0];
  if (!file) return;

  // Upload directly using FormData
  const formData = new FormData();
  formData.append("file", file);

  await fetch("/upload-dataset", {
    method: "POST",
    body: formData
  });
};

Limits

Limit	Value
Max file size	10MB per file
Supported formats	CSV, JSON

Next steps

API Reference

See the complete Datasets API reference for all endpoints and options.

User Context

Learn more about configuring your agent and setting up user context.