Skip to main content

Update data collection

Endpoint: PUT /data-collections/{data_collection_id}

Description Updates name, dataset_ids, custom_run_ids, org_id, and/or project_id. All body fields are optional.

Sharing & unsharing rules

Changing org_id:

  • Setting org_id to your organization's id shares the collection. When you newly share (org_id goes from null to your organization), include project_id in the same request (required — see Introduction — Project).
  • The collection receives the org_id and project_id you send. Every dataset and custom run currently in the collection adopts the same org_id and inherits that project (cascaded from the collection).
  • Setting org_id to null unshares the collection and removes project assignments for the collection and its org-shared children:
    • Datasets and runs that don't belong to the collection's owner are detached (data_collection_id cleared) and lose org visibility.
    • Datasets owned by the collection owner stay in the collection but become private (org_id = null).
    • The collection owner's runs on those remaining datasets / on the collection lose their org_id and project assignment.
  • Only the collection owner (or, for org-only collections, a member of that organization) can change org_id.
  • Org-only collections (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.

Changing dataset_ids (the field replaces the full set of attached datasets):

  • Datasets removed from the set get data_collection_id = null, and the owner's runs that referenced those datasets are detached from the collection.
  • Datasets newly added must be your non-proprietary datasets and must not already belong to another collection. With a project-scoped API key, each newly attached dataset must be unassigned or already belong to the key's project; a conflicting assignment returns 403.
  • If the collection is currently shared, every dataset in the new set is forced to the collection's org_id, and the owner's runs on those datasets are kept in sync. New members inherit the collection's project — they cannot be assigned a different project directly while they remain in the collection.
  • If the collection is currently private and you belong to an organization, adding any dataset already shared with your organization promotes the collection to that org_id. As part of the promotion, your own private datasets in the new set are auto-shared with your organization (and your runs on them follow). If any non-owner private dataset can't be promoted, the request fails with 400. This auto-promotion requires project_id in the same request (the collection and promoted members receive that project) unless you pass org_id: null to opt out.

Changing custom_run_ids (the field replaces the full set of attached custom runs):

  • Runs removed from the set are detached from the collection (data_collection_id = null); their org_id and project assignment are unchanged unless you also change org_id on the collection.
  • Runs newly added must be custom runs (no dataset) you can access and must not already belong to another collection. With a project-scoped API key, each newly attached run must be unassigned or already belong to the key's project; a conflicting assignment returns 403.
  • When the collection is org-shared, attached custom runs inherit the collection's org_id and project — not an independent project assignment.

Changing project_id:

  • On a private collection, sending project_id alone (without org_id) auto-shares the collection with your organization and assigns it (and current cascaded org-shared members) 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 collection, changes move the collection and all cascaded org-shared datasets and runs to another project in your organization.
  • You cannot set project_id to null while the collection remains org-shared.

Parameters

  • Path: data_collection_id — integer.
  • Body — application/json:
{
  "name": "string | null",
  "dataset_ids": "integer[] | null",
  "custom_run_ids": "integer[] | null",
  "org_id": "integer | null",
  "project_id": "integer | null"
}

Error responses

  • 401 — Authentication failed.
  • 403 — Not the owner of a user-owned collection trying to change org_id, or API key scoping violation (project_id in the body conflicts with a project-scoped key, attached resource already assigned to a different project).
  • 422 — Invalid body.
  • 404 — Collection not found or not accessible to your API key (including not assigned to the key's project).
  • 400 — Empty name; duplicate name; invalid dataset_ids or custom_run_ids (same rules as create); org_id doesn't match your organization; attempt to unshare or move an org-only collection; mixed dataset selection where non-owner private datasets cannot be auto-promoted; org share or auto-promotion without project_id; project_id: null while org-shared; invalid or inaccessible project_id.
  • 500 — Server error.

Responses

  • 200 — updated collection object with the same JSON shape as one element of items from Get data collections (paginated list).

Example response (200)

{
  "id": 14,
  "user": { "id": 7, "email": "analyst@acme.com" },
  "name": "Renamed bundle",
  "org_id": null,
  "project_id": null,
  "author_email": "analyst@acme.com",
  "datasets": [
    {
      "id": 1,
      "name": "Support QA - March",
      "description": "March support QA prompts",
      "user": { "id": 7, "email": "analyst@acme.com" },
      "org_id": null,
      "project_id": null,
      "author_email": "analyst@acme.com",
      "created_at": "2026-03-30T10:00:00Z",
      "updated_at": null
    },
    {
      "id": 2,
      "name": "Support QA - April",
      "description": "April support QA prompts",
      "user": { "id": 7, "email": "analyst@acme.com" },
      "org_id": null,
      "project_id": null,
      "author_email": "analyst@acme.com",
      "created_at": "2026-03-31T10:00:00Z",
      "updated_at": null
    },
    {
      "id": 3,
      "name": "Support QA - May",
      "description": "May support QA prompts",
      "user": { "id": 7, "email": "analyst@acme.com" },
      "org_id": null,
      "project_id": null,
      "author_email": "analyst@acme.com",
      "created_at": "2026-04-01T10:00:00Z",
      "updated_at": null
    }
  ],
  "runs": [],
  "created_at": "2026-04-01T09:20:00Z",
  "updated_at": "2026-04-01T09:30:00Z"
}

curl

curl -X PUT "https://api.aegisevals.ai/api/v1/data-collections/1" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"name":"Renamed bundle","dataset_ids":[1,2,3]}'

Share with your organization:

curl -X PUT "https://api.aegisevals.ai/api/v1/data-collections/1" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"org_id":3,"project_id":5}'