Skip to main content

Create dataset

Endpoint: POST /datasets

Description Creates a custom dataset from a CSV file. The server parses the file, stores records, and attaches selected metrics (metric id → { threshold, metric_args }). You can optionally set name, description, and data_collection_id — the collection id must be one you can access (same rules as listing collections: yours or shared with your organization).

Sharing rules

The new dataset is always owned by you (your account is the individual owner). Sharing isn't accepted directly on this endpoint — visibility is derived from the data collection (if any), from an optional project_id, or from a project-scoped API key. Datasets created here are never org-only (org-only resources have no individual owner and can only be produced through admin flows).

  • Without data_collection_id:
    • Private (org_id = null, no project) when you use a private API key and omit project_id.
    • Org-shared and assigned to a project when you use a project-scoped API key (the key's project is applied and the dataset is org-shared automatically). A private key cannot org-share via project_id alone. See Introduction — API key scoping.
  • With data_collection_id:
    • The collection is loaded via claim semantics. When claimable, the dataset is created shared or private according to the collection's org_id and inherits the collection's project (not a separate project assignment). You must still be a member of that organization when the collection is org-shared. Unassigned collections can be claimed into the key's project; a collection already assigned to a different project returns 403.
    • The linked collection is private → the dataset is created private (no project until the collection or dataset is shared later).

Parameters

  • Body — multipart/form-data:
{
  "file": "binary (.csv file)",
  "selected_metrics": "string (JSON: see shape below)",
  "column_mappings": "string | null (JSON: Aegis field → CSV column name)",
  "name": "string | null",
  "description": "string | null",
  "data_collection_id": "integer | null",
  "project_id": "integer | null"
}
  • description is optional. Max 255 characters. Surrounding whitespace is trimmed; blank or whitespace-only values are stored as null.

project_id

  • Optional. On a private key, sending project_id alone does not org-share the dataset (private keys have personal visibility only). Use a project-scoped key to create org-shared datasets.
  • On a project-scoped key, must match the key's project when provided; omit to use the key's project (standalone creates are org-shared automatically).
  • Cannot be set on a dataset that will live inside a data collection — assign the collection instead.

selected_metrics is a JSON-encoded string. Decoded, it is a map keyed by metric id (as a string, e.g. "1"), where each value is an object:

{
  "<metric_id>": {
    "threshold": "integer (0–100)",
    "metric_args": "object | null"
  }
}
  • threshold is required and must be between 0 and 100.
  • metric_args is optional (null or omitted means "use the metric's defaults"). Keys are argument names declared by the metric and values must match the argument's declared type. Unknown argument names are rejected; required args with no default must be supplied.
  • Metric id keys. Non-integer keys return 400.
  • Per-run overrides can later be supplied via POST /runs/dataset's metric_args.

column_mappings is an optional JSON-encoded string. Decoded, it maps each Aegis field to the matching CSV column header:

{
  "prompt": "question",
  "input": "user_input",
  "context": "background",
  "output": "model_answer",
  "golden_answer": "expected_answer",
  "external_id": "upstream_row_id"
}
  • Keys must be Aegis field names: external_id, prompt, input, context, output, golden_answer. Include only the fields you want to import.
  • Values are the exact CSV column names (case-insensitive match against the file header).
  • Omit column_mappings (or pass null) to auto-detect columns whose headers already match Aegis field names (including external_id).
  • The CSV must still include at least one of prompt, input, context, output, or golden_answer. An external_id column alone is not enough to create a dataset.

Error responses

  • 401 — Authentication failed.
  • 403 — API key scoping violation (project_id conflicts with a project-scoped key, collection/dataset project mismatch, scoped key on a personal resource).
  • 422 — Missing required form parts or invalid multipart fields.
  • 400 — Invalid CSV, empty file, bad encoding, invalid selected_metrics / column_mappings, unknown or inactive metrics, duplicate dataset name for your account or organization, proprietary dataset org-share attempt, etc.
  • 404 — Dataset type not found; or data collection not found or not claimable for data_collection_id.
  • 500 — Server error.

Responses

  • 201 — dataset object with the same JSON shape as Get dataset by id. On create, runs and evaluations are usually empty arrays until you start a dataset run.

Example response (201)

{
  "id": 42,
  "user": { "id": 7, "email": "analyst@acme.com" },
  "dataset_type_id": 1,
  "author_email": "analyst@acme.com",
  "name": "My evaluation set",
  "description": "Evaluation prompts for support QA",
  "selected_metrics": {
    "1": { "threshold": 70, "metric_args": null },
    "2": { "threshold": 80, "metric_args": { "ignore_extra_keys": true } }
  },
  "structure": ["external_id", "prompt", "output", "golden_answer"],
  "column_mappings": {
    "external_id": "row_id",
    "prompt": "question",
    "output": "model_answer",
    "golden_answer": "expected_answer"
  },
  "data_collection_id": null,
  "org_id": null,
  "project_id": null,
  "created_at": "2026-04-02T12:00:00Z",
  "updated_at": null,
  "dataset_type": {
    "id": 1,
    "name": "CUSTOM",
    "label": "Custom",
    "description": null
  },
  "records": [
    {
      "id": 1001,
      "user_id": 7,
      "dataset_id": 42,
      "external_id": "row-42",
      "prompt": "What is the refund policy?",
      "input": null,
      "context": null,
      "output": "Refunds are available within 30 days.",
      "golden_answer": "30-day refund window.",
      "created_at": "2026-04-02T12:00:00Z",
      "updated_at": null
    }
  ],
  "runs": [],
  "evaluations": [],
  "last_run_id": null
}

curl

curl -X POST "https://api.aegisevals.ai/api/v1/datasets" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000" \
  -F "file=@/path/to/data.csv" \
  -F 'selected_metrics={"1":{"threshold":70,"metric_args":null},"2":{"threshold":80,"metric_args":{"ignore_extra_keys":true}}}' \
  -F 'column_mappings={"external_id":"row_id","prompt":"question","output":"model_answer","golden_answer":"expected_answer"}' \
  -F 'name=My evaluation set' \
  -F 'description=Evaluation prompts for support QA'