Skip to main content

Create data collection

Endpoint: POST /data-collections

Description Creates a data collection. Optional dataset_ids attaches your non-proprietary datasets that are not already in another collection; linked runs for those datasets move to this collection too. Optional custom_run_ids attaches custom runs (runs without a dataset) you can access that are not already in another collection.

Sharing rules

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

  • A project-scoped API key always org-shares the collection and assigns it to the key's project. Any project_id in the body must match the key's project (or be omitted). Attached datasets and runs must be unassigned or already belong to the key's project; a resource assigned to a different project returns 403. See Introduction — API key scoping.
  • No dataset_ids or custom_run_ids (or all selected resources are private and none are visible to your organization) → the collection is created private (org_id = null, no project), unless a project-scoped key applies (above).
  • Every selected dataset and custom run is already shared with your organization (org_id == your org) → the collection is created shared with that same org_id. You must also supply project_id; the collection and attached members inherit that project (cascaded from the collection).
  • Mixed selection (private + org-shared resources) and you belong to an organization → your own private datasets and runs in the selection are auto-promoted to your org_id, so the whole selection becomes org-visible and the collection is created shared. If any selected resources you don't own can't be promoted (they stay private), the request fails with 400. This path also requires project_id; the project is assigned to the collection and cascades to promoted members.
  • You're not in an organization and any selected resource is org-visible → 400.

Sending project_id alone on an otherwise private collection (no org-visible attached resources) auto-shares the collection 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.

Parameters

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

custom_run_ids

  • Optional list of custom run ids (runs with no dataset_id) you can access.
  • Each run must not already belong to another data collection.
  • Dataset runs cannot be attached here — they follow their dataset’s collection membership.

project_id

  • Required when the collection ends up org-shared after create (see sharing rules above), including auto-promotion from a mixed resource selection. Pass a project id your organization owns; GET /organizations/me exposes default_project_id as a convenient starting point.
  • On an otherwise private collection, may be sent alone to auto-share with your organization and assign the collection to that project.
  • Omit or pass null when the collection stays private.

Error responses

  • 401 — Authentication failed.
  • 403 — 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.
  • 400 — Empty name; duplicate name for your account or organization; dataset_ids or custom_run_ids invalid, proprietary, or already assigned elsewhere; org-visible resources selected without an organization; mixed selection where non-owner private resources cannot be auto-promoted; org-shared create without project_id.
  • 404 — Referenced dataset ids not found (or treated as invalid for this operation).
  • 500 — Server error creating the collection.

Responses

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

Example response (201)

{
  "id": 14,
  "user": { "id": 7, "email": "analyst@acme.com" },
  "name": "My 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
    }
  ],
  "runs": [],
  "created_at": "2026-04-01T09:20:00Z",
  "updated_at": "2026-04-01T09:20:00Z"
}

curl

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

Attach org-shared datasets (requires project_id):

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