Update data collection

Endpoint: PUT /data-collections/{data_collection_id}

Description Updates name, dataset_ids, custom_run_ids, trace_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, custom run, and trace currently in the collection adopts the same org_id and inherits that project (cascaded from the collection). Spans under those traces receive the same org_id.
• Setting org_id to null unshares the collection when this key may share it, and removes project assignments for the collection and its org-shared children. A private key can unshare a collection it owns. A project-scoped key cannot: once the collection is org-shared, can_share is false and the request returns 403. When unshare succeeds:
  • Datasets, runs, and traces that don't belong to the collection's owner are detached (data_collection_id cleared) and lose org visibility.
  • Datasets and traces owned by the collection owner stay in the collection but become private (org_id = null). Spans under those traces receive the same org_id.
  • The collection owner's runs on those remaining datasets / on the collection lose their org_id and project assignment.
• Only the collection owner can change org_id on a user-owned collection, and only when can_share is true for this key. Re-sending the current org_id on an org-only collection is allowed for a project-scoped key in that organization.
• 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 the key is project-scoped, 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 trace_ids (the field replaces the full set of attached traces):

• Omit the field to leave attached traces unchanged; send [] to detach all.
• Traces 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.
• Traces newly added must be traces you can access and must not already belong to another collection. With a project-scoped API key, each newly attached trace must be unassigned or already belong to the key's project; a conflicting assignment returns 403.
• When the collection is org-shared, attached traces inherit the collection's org_id and project — not an independent project assignment. Spans under those traces receive the same org_id.
• If the collection is currently private and the key is project-scoped, adding any trace already shared with your organization promotes the collection to that org_id. As part of the promotion, your own private traces in the new set are auto-shared with your organization (spans follow). If any non-owner private trace can't be promoted, the request fails with 400 ("This selection mixes organization-visible datasets, custom runs, or traces with private resources that are not yours or cannot be shared with your organization automatically."). This auto-promotion requires project_id in the same request unless you pass org_id: null to opt out.

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 its org-shared members) to that project when the key is project-scoped. The id must match the key's project. On a private key the field is ignored and the collection stays private.
• On an org-shared 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 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",
  "trace_ids": "integer[] | null",
  "org_id": "integer | null",
  "project_id": "integer | null"
}

name

• Optional. Surrounding whitespace is trimmed. Max 255 characters. A longer value returns 422. Omit the field to leave the name unchanged.

dataset_ids, custom_run_ids, trace_ids, 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.

Error responses

• 401 — Authentication failed.
• 403 — Not the owner of a user-owned collection trying to change org_id, an API key changing project_id on an already-shared collection (including an organization admin's key), moving another user's row into or out of the collection, 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, including a name longer than 255 characters. dataset_ids, custom_run_ids, trace_ids, 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"). For a list field, the error location includes the index (["body", "dataset_ids", 0]). JSON null and omitting a field are still accepted.
• 404 — Collection not found or not accessible to your API key (including not assigned to the key's project); referenced dataset, custom run, or trace ids not found or not accessible, including proprietary datasets and runs that are not custom ("Datasets with IDs: […] do not exist.", "Custom runs with IDs: […] do not exist.", "Traces with IDs: […] do not exist.").
• 400 — Empty name; duplicate name; datasets, custom runs, or traces already filed in another collection (same messages as Create data collection); org_id doesn't match your organization; attempt to unshare or move an org-only collection; mixed selection where non-owner private resources cannot be auto-promoted ("This selection mixes organization-visible datasets, custom runs, or traces with private resources that are not yours or cannot be shared with your organization automatically."); org share or auto-promotion without project_id; project_id: null while org-shared; invalid or inaccessible project_id; trace id collision when sharing or unsharing, including "A trace with this id is already shared with your organization." and "A trace with this id already exists for your account."
• 500 — Server error.

Responses

• 200 — updated collection object with the same JSON shape as one element of items from Get data collections (paginated list). Nested runs[].api_key_id may be null per that shape. Nested traces[] entries include identity and filing fields only (no observability rollups).

Example response (200)

{
  "id": 14,
  "user": { "id": 7, "email": "analyst@acme.com" },
  "name": "Renamed bundle",
  "org_id": null,
  "project_id": null,
  "permissions": {
    "can_edit": true,
    "can_delete": true,
    "can_share": false,
    "can_assign_project": false,
    "can_move_collection": true
  },
  "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,
      "data_collection_id": 14,
      "project_id": null,
      "permissions": {
        "can_edit": true,
        "can_delete": true,
        "can_share": false,
        "can_assign_project": false,
        "can_move_collection": true
      },
      "author_email": "analyst@acme.com",
      "created_at": "2026-03-30T10:00:00Z",
      "updated_at": "2026-03-30T10:00:00Z"
    },
    {
      "id": 2,
      "name": "Support QA - April",
      "description": "April support QA prompts",
      "user": { "id": 7, "email": "analyst@acme.com" },
      "org_id": null,
      "data_collection_id": 14,
      "project_id": null,
      "permissions": {
        "can_edit": true,
        "can_delete": true,
        "can_share": false,
        "can_assign_project": false,
        "can_move_collection": true
      },
      "author_email": "analyst@acme.com",
      "created_at": "2026-03-31T10:00:00Z",
      "updated_at": "2026-03-31T10:00:00Z"
    },
    {
      "id": 3,
      "name": "Support QA - May",
      "description": "May support QA prompts",
      "user": { "id": 7, "email": "analyst@acme.com" },
      "org_id": null,
      "data_collection_id": 14,
      "project_id": null,
      "permissions": {
        "can_edit": true,
        "can_delete": true,
        "can_share": false,
        "can_assign_project": false,
        "can_move_collection": true
      },
      "author_email": "analyst@acme.com",
      "created_at": "2026-04-01T10:00:00Z",
      "updated_at": "2026-04-01T10:00:00Z"
    }
  ],
  "runs": [],
  "traces": [],
  "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}'