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. You can rename the dataset, update its description, change selected_metrics, adjust column_mappings, set data_collection_id, share or unshare via org_id, or assign project_id when org-sharing. Changing org_id is restricted: another member cannot re-share or unshare your dataset — only the owner may change org_id for user-owned rows (org-only datasets follow the rules below).

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. If the dataset is still inside an org-shared data collection, the request 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 (or, for org-only datasets, a member of that organization) can change org_id.

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.

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, changes move it to another project in your organization.
  • 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",
  "selected_metrics": {
    "1": { "threshold": 70, "metric_args": null },
    "2": { "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"
}

selected_metrics is a map keyed by metric id (as a string), with { threshold: 0–100, metric_args: object | null } per entry. See Create dataset for the full shape and validation rules. Sending selected_metrics replaces the whole map; omit the field (or pass null) to leave it unchanged. Sending an empty object returns 400.

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.

Error responses

  • 401 — Authentication failed.
  • 403 — Not allowed to update this dataset (not the owner / not in the dataset's organization / non-admin acting on a proprietary dataset), 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.
  • 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, empty selected_metrics, invalid column_mappings, duplicate name for your account or organization, org_id doesn't match your organization, attempt to unshare an org-only dataset, attempt to share a proprietary dataset, attempt to unshare while still inside an org-shared data collection, attempt to attach a proprietary dataset to a 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, etc.
  • 500 — Server error.

Responses

Example response (200)

{
  "id": 3,
  "user": { "id": 7, "email": "analyst@acme.com" },
  "dataset_type_id": 1,
  "name": "Renamed dataset",
  "description": "Updated context for this dataset",
  "selected_metrics": {
    "1": { "threshold": 75, "metric_args": null },
    "2": { "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,
  "author_email": "analyst@acme.com",
  "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,"selected_metrics":{"1":{"threshold":75,"metric_args":null},"2":{"threshold":85,"metric_args":null}}}'