Datasets

Datasets allow you to upload data files (CSV, JSON) that the agent can reference when answering questions. Files can be scoped to individual users or shared across users matching a context value.

Scoping options

Datasets support two scoping methods:

Scope	Description	Use case
User-scoped	Files accessible only to a specific user	Personal uploads, user-specific data
Context-scoped	Files shared with all users matching a context value	Organization-wide reference data, team resources

For example:

• A user uploads their personal sales targets → User-scoped to userIdentifier: "user_123"
• An admin uploads company pricing → Context-scoped to orgId: "org_456" (all users in that org can access it)

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. Choose the scope type:
   • User: Enter a user identifier (e.g., user_123)
   • Context: Select a context key and enter a value (e.g., orgId: org_456)
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 context-scoped uploads for shared reference data like pricing sheets or company policies. Use user-scoped uploads for individual user data.

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.

User-scoped uploads

Upload files that only a specific user can access.

Request

Node.js

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

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

// Upload a file for a specific user
const result = await client.datasets.user.upload({
  userIdentifier: "user_123",
  file: fs.createReadStream("./sales_data.csv"),
  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/user/user_123" \
  -H "Authorization: Bearer $INCONVO_API_KEY" \
  -F "file=@./sales_data.csv" \
  -F "notes=Q4 2024 sales report"

Context-scoped uploads

Upload files shared with all users matching a context value.

Request

Node.js

// Upload a file shared with all users in an organization
const result = await client.datasets.context.upload({
  contextKey: "orgId",
  contextValue: "org_456",
  file: fs.createReadStream("./company_pricing.csv"),
  notes: "2024 pricing sheet"
});

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

curl -X POST "https://app.inconvo.ai/api/v1/datasets/context/orgId/org_456" \
  -H "Authorization: Bearer $INCONVO_API_KEY" \
  -F "file=@./company_pricing.csv" \
  -F "notes=2024 pricing sheet"

Parameters

User-scoped endpoint: POST /datasets/user/{userIdentifier}

Parameter	Required	Description
userIdentifier	Yes	Path parameter - unique identifier for the user (1-256 chars)
file	Yes	The file to upload (binary stream or File object)
notes	No	Description or notes about the file

Context-scoped endpoint: POST /datasets/context/{contextKey}/{contextValue}

Parameter	Required	Description
contextKey	Yes	Path parameter - the context key (e.g., orgId, teamId)
contextValue	Yes	Path parameter - the context value (e.g., org_456)
file	Yes	The file to upload (binary stream or File object)
notes	No	Description or notes about the file

List files

Retrieve all files for a specific user or context.

Request

Node.js

// List user-scoped files
const userFiles = await client.datasets.user.list({
  userIdentifier: "user_123"
});
console.log(userFiles);
// { files: ["sales_data.csv", "inventory.json"] }

// List context-scoped files
const contextFiles = await client.datasets.context.list({
  contextKey: "orgId",
  contextValue: "org_456"
});
console.log(contextFiles);
// { files: ["company_pricing.csv", "policies.json"] }

# List user-scoped files
curl -X GET "https://app.inconvo.ai/api/v1/datasets/user/user_123" \
  -H "Authorization: Bearer $INCONVO_API_KEY"

# List context-scoped files
curl -X GET "https://app.inconvo.ai/api/v1/datasets/context/orgId/org_456" \
  -H "Authorization: Bearer $INCONVO_API_KEY"

Delete a file

Remove a file by providing its filename and scope.

Request

Node.js

// Delete a user-scoped file
const result = await client.datasets.user.delete({
  userIdentifier: "user_123",
  filename: "sales_data.csv"
});
console.log(result);
// { file: "sales_data.csv", success: true }

// Delete a context-scoped file
const result2 = await client.datasets.context.delete({
  contextKey: "orgId",
  contextValue: "org_456",
  filename: "old_pricing.csv"
});

# Delete a user-scoped file
curl -X DELETE "https://app.inconvo.ai/api/v1/datasets/user/user_123/sales_data.csv" \
  -H "Authorization: Bearer $INCONVO_API_KEY"

# Delete a context-scoped file
curl -X DELETE "https://app.inconvo.ai/api/v1/datasets/context/orgId/org_456/old_pricing.csv" \
  -H "Authorization: Bearer $INCONVO_API_KEY"

How the agent uses datasets

When a user sends a message, the agent automatically has access to:

1. User-scoped files matching their userIdentifier
2. Context-scoped files matching any of their userContext values

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 as context-scoped for orgId: org_456, any user in that organization can ask:

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

Or if a user uploads their own targets.csv file, 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 files 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 userIdentifier from session
  const userIdentifier = req.session.userId;

  try {
    const result = await client.datasets.user.upload({
      userIdentifier,
      // Use toFile() to convert buffer to uploadable format
      file: await toFile(req.file.buffer, req.file.originalname),
      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
  });
};

File storage paths

Files are stored with the following path structure:

Scope	Path format
User-scoped	/{orgId}/agt_123/userIdentifier/{userIdentifier}/filename.csv
Context-scoped	/{orgId}/agt_123/userContext/{contextKey}:{contextValue}/filename.csv

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 fields.