Skip to main content

Update dataset

Endpoint: PUT /datasets/{dataset_id}

Description

Updates a custom dataset you own, or that is shared with your organization and you are a member of that organization. All body fields are optional; only provided fields are applied. Content you may edit is the name, description, default_selected_metrics, and column_mappings. Sharing (org_id), project assignment (project_id), and collection membership (data_collection_id) are separate placement actions (see below). On a user-owned row, another org member cannot change org_id or data_collection_id (share, unshare, attach, or detach) — only the owner may (org-only datasets follow the rules below). A member may still update other fields (for example name or default_selected_metrics) and may send the current data_collection_id unchanged in the same request.

Sharing & unsharing rules

Changing org_id:

  • Setting org_id to your organization's id shares the dataset. When you newly share (org_id goes from null to your organization), include project_id in the same request (required — see Introduction — Project).
  • If the dataset is not in a data collection, it receives the org_id and project_id you send.
  • If the dataset is in a private data collection that you own, sharing cascades to the whole collection: the collection, every dataset in it, and your runs tied to the collection or its datasets adopt the same org_id. project_id is applied to the collection and cascades to those org-shared members (sibling datasets and runs), not assigned to this dataset alone.
  • If the dataset is already in an org-shared data collection, its org_id and project follow the collection — you cannot independently share, unshare, or re-project it here. Detach it (data_collection_id: null) or change the collection instead.
  • Setting org_id to null unshares the dataset and removes project assignment for this dataset and its runs when this key may share it. A private key can unshare a dataset it owns. A project-scoped key cannot: once the dataset is org-shared, can_share is false and the request returns 403. If the dataset is still inside an org-shared data collection, unshare is rejected — also pass data_collection_id: null in the same call (or unshare the collection first).
  • Org-only datasets (no individual owner) cannot be unshared and cannot be moved to a different organization — org_id must equal the current value, and you must belong to that organization.
  • Proprietary datasets cannot be shared with an organization.
  • Only the dataset owner can change org_id on a user-owned dataset, and only when can_share is true for this key. Re-sending the current org_id on an org-only dataset is allowed for a project-scoped key in that organization.

Changing data_collection_id:

  • Linking the dataset to an org-shared collection forces the dataset's org_id to match the collection's org_id (auto-share) and inherits the collection's project when one is set.
  • Linking to a private collection leaves the dataset's org_id unchanged (but see the cascade described above if you later share it).
  • Setting data_collection_id to null detaches the dataset; the dataset's org_id is unchanged unless org_id is also provided in the same request.
  • Proprietary datasets cannot be attached to a data collection.
  • Only the dataset owner (or, for org-only datasets, a member of that organization) can change data_collection_id — attach, detach, or move to another collection. Sending the dataset's current data_collection_id without changing it is allowed for any member who may update the dataset.

Changing project_id:

  • On a private dataset with no data_collection_id, sending project_id alone (without org_id) auto-shares the dataset with your organization and assigns it to that project when your key has organization authorization (a project-scoped key). A private API key cannot org-share this way.
  • On an org-shared dataset not in a data collection, an API key cannot change project_id to a different project, including when the key's owner is an organization admin. That request returns 403. Sending the current project_id again succeeds.
  • You cannot set project_id to null while the dataset remains org-shared.
  • A dataset inside a data collection cannot be assigned to a project directly — assign the collection instead (or remove the dataset from the collection first). The API returns 400 if you try.

Run synchronization

Whenever org_id or data_collection_id change as a result of this request, your own runs on this dataset are updated to match both fields, so they keep the same visibility as the dataset.

Parameters

  • Path: dataset_id — integer.
  • Body — application/json:
{
  "name": "string | null",
  "description": "string | null",
  "default_selected_metrics": {
    "ans_corr": { "threshold": 70, "metric_args": null },
    "faith": { "threshold": 80, "metric_args": { "ignore_extra_keys": true } }
  },
  "column_mappings": { "external_id": "row_id", "prompt": "col_a", "output": "col_b" },
  "data_collection_id": 14,
  "org_id": "integer | null",
  "project_id": "integer | null"
}

data_collection_id, org_id, and project_id must be JSON integers. A digit string ("74"), a whole-number float (1.0), or a boolean (true / false) returns 422 before lookup. JSON null and omitting a field stay valid.

default_selected_metrics is a map keyed by metric shortname, with { threshold?: 0–100 | null, metric_args?: object | null } per entry. See Create dataset for the full shape and validation rules (including optional per-metric threshold with catalog fallback). Sending a non-empty default_selected_metrics replaces the whole map. Omit the field, or send null, to leave stored defaults unchanged. Send {} to clear stored defaults (default_selected_metrics is null in the response).

description is optional. Max 255 characters. Surrounding whitespace is trimmed; null or a blank string clears the stored description. Omit the field to leave it unchanged.

column_mappings replaces the stored map. Each CSV column can be mapped to only one field (case-insensitive). A shared column returns 400 (Each CSV column can be mapped to only one field. 'question' is mapped to input, output.).

Error responses

  • 401 — Authentication failed.
  • 403 — Not allowed to update this dataset, another member attempting to change org_id or data_collection_id on a user-owned dataset, an API key changing project_id on an already-shared dataset (including an organization admin's key), or API key scoping violation (project_id in the body conflicts with a project-scoped key, claim/attach conflict when the target collection is assigned to a different project).
  • 422 — Invalid body. data_collection_id, org_id, and project_id must be JSON integers. A digit string ("74"), a whole-number float (1.0), or a boolean (true / false) is rejected before lookup ("Input should be a valid integer"). JSON null and omitting a field are still accepted.
  • 404 — Dataset not found or not accessible to your API key (including not assigned to the key's project); data collection not found or not claimable.
  • 400 — Invalid metrics (including metric id used as a map key — Invalid metric key '<id>'. Use a metric shortname, not a metric id.; unknown or inactive shortnames (The following metrics do not exist: …, The following metrics are not active: …); invalid thresholds or metric_args; agentic metrics that score a trace or span — These metrics score a trace or a span and cannot be used on a dataset or custom run: <shortnames>.); invalid column_mappings (including two fields mapped to the same CSV column — Each CSV column can be mapped to only one field. '<column>' is mapped to <fields>.); duplicate name for your account or organization, org_id doesn't match your organization, attempt to unshare an org-only dataset, attempt to unshare while still inside an org-shared data collection, org share without project_id, project_id: null while org-shared, direct project_id on a dataset inside a collection, invalid or inaccessible project_id. This endpoint updates custom datasets only. A proprietary dataset id is 404.
  • 500 — Server error.

Responses

  • 200 — Updated dataset object with the same JSON shape as one element of items from Get all datasets (paginated). The example is a project-scoped key that just shared a dataset it owns: can_share is false once the dataset is org-shared. Flag meanings: Introduction — Permissions.

Example response (200)

{
  "id": 3,
  "user": { "id": 7, "email": "analyst@acme.com" },
  "dataset_type_id": 2,
  "name": "Renamed dataset",
  "description": "Updated context for this dataset",
  "default_selected_metrics": {
    "ans_corr": { "threshold": 75, "metric_args": null },
    "faith": { "threshold": 85, "metric_args": null }
  },
  "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": 3,
  "project_id": 5,
  "permissions": {
    "can_edit": true,
    "can_delete": true,
    "can_share": false,
    "can_assign_project": false,
    "can_move_collection": true
  },
  "author_email": "analyst@acme.com",
  "extra_columns": [],
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": "2026-04-02T15:00:00Z"
}

curl

curl -X PUT "https://api.aegisevals.ai/api/v1/datasets/3" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"name":"Renamed dataset","description":"Updated context for this dataset","org_id":3,"project_id":5,"default_selected_metrics":{"ans_corr":{"threshold":75,"metric_args":null},"faith":{"threshold":85,"metric_args":null}}}'