Skip to main content

Ownership & Favorites

Manage dataset ownership and user favorites.

GET /api/datasets/{id}/owner​

Get the dataset owner principal (user, team, or avatar).

Authentication: Required

Path Parameters:

ParameterTypeDescription
idstringDataset ID or slug

Response (user owner):

{
  "id": "user:admin",
  "type": "user",
  "name": "Admin User",
  "email": "admin@example.com"
}

Response (team owner):

{
  "id": "team:analytics",
  "type": "team",
  "name": "Analytics Team",
  "description": "Data analytics team"
}

PUT /api/datasets/{id}/owner​

Change the dataset owner.

Authentication: Required

Permission: dataset:changeOwner

Path Parameters:

ParameterTypeDescription
idstringDataset ID or slug

Request Body:

FieldTypeRequiredDescription
ownerIdstringYesNew owner ID (user, team, or avatar)

Example Request:

{
  "ownerId": "team:analytics"
}

Response:

{
  "id": "team:analytics",
  "type": "team",
  "name": "Analytics Team"
}

Cascading Behavior:

When ownership changes, the following related entities are also updated:

  • Jobs - Associated jobs transfer to new owner
  • Visuals - Dataset visuals transfer to new owner
  • Child Datasets - Snapshots and drafts transfer to new owner
Permission Impact

Changing ownership may affect user permissions. The previous owner loses owner-level permissions unless granted via shares.

GET /api/datasets/{id}/favorite​

Check if the dataset is favorited by the current user.

Authentication: Required

Path Parameters:

ParameterTypeDescription
idstringDataset ID or slug

Response:

{
  "datasetId": "sales-2024",
  "userId": "user:admin",
  "favorited": true,
  "favoritedAt": "2024-01-15T10:00:00Z"
}

Or if not favorited:

{
  "datasetId": "sales-2024",
  "userId": "user:admin",
  "favorited": false
}

PUT /api/datasets/{id}/favorite​

Mark the dataset as a favorite.

Authentication: Required

Path Parameters:

ParameterTypeDescription
idstringDataset ID or slug

Response:

{
  "datasetId": "sales-2024",
  "userId": "user:admin",
  "favorited": true,
  "favoritedAt": "2024-02-08T16:00:00Z"
}

DELETE /api/datasets/{id}/favorite​

Remove the dataset from favorites.

Authentication: Required

Path Parameters:

ParameterTypeDescription
idstringDataset ID or slug

Response:

204 No Content

Ownership Examples​

Transfer to Team​

// Transfer ownership to analytics team
await PUT('/api/datasets/sales-2024/owner', {
  ownerId: 'team:analytics'
});

Transfer to User​

// Transfer ownership to specific user
await PUT('/api/datasets/customer-data/owner', {
  ownerId: 'user:datamanager'
});

Verify Ownership Before Transfer​

// Check current owner
const owner = await GET('/api/datasets/sales-2024/owner');

if (owner.type === 'user') {
  // Transfer to team if currently user-owned
  await PUT('/api/datasets/sales-2024/owner', {
    ownerId: 'team:analytics'
  });
}

Favorites Examples​

Add to Favorites​

await PUT('/api/datasets/sales-2024/favorite');

Remove from Favorites​

await DELETE('/api/datasets/sales-2024/favorite');

Toggle Favorite​

const fav = await GET('/api/datasets/sales-2024/favorite');

if (fav.favorited) {
  await DELETE('/api/datasets/sales-2024/favorite');
} else {
  await PUT('/api/datasets/sales-2024/favorite');
}

Get All User Favorites​

// Get all datasets
const datasets = await GET('/api/datasets-list');

// Filter to favorites
const favorites = datasets.items.filter(ds => ds.favorited);

Best Practices​

Ownership​

  • Team ownership - Prefer team ownership for shared datasets
  • User ownership - Use for personal/experimental datasets
  • Document transfers - Log ownership changes for audit
  • Verify permissions - Ensure new owner has appropriate access
  • Cascade awareness - Understand that related entities transfer

Favorites​

  • Personal organization - Use favorites for frequently accessed datasets
  • Quick access - Build favorite-based navigation
  • Limit favorites - Too many defeats the purpose
  • Team recommendations - Share favorite lists with team
  • Clean up - Remove obsolete favorites regularly