Projects, collections & assets

Dataerai organizes data as Projects → Collections → Assets. This tutorial walks that hierarchy and shows how to navigate, inspect, and act on items — first in the web workspace, then with the same calls from Python.

Overview

Use this tutorial to learn how to move around your workspace. What you’ll use:

Projects for the main work area.
Collections for grouping related records.
Assets for files, metadata, notes, and relationships.

How navigation works:

Single-click a row to inspect it in the sidebar.
Double-click a row to open it.
Use the path above the list to see where you are.
Select rows to show actions such as Copy, Cut, Paste, and Permissions.

Good to know:

You only see projects, collections, and assets you are allowed to access.
Browser examples show the normal workspace flow.
Code examples are included for users who want to inspect the same data from Python.

Technical details

The Python SDK covers transfers and metadata. The code examples for browsing use the public REST API because the SDK does not include list/retrieve methods for the full hierarchy.

Select and inspect

A single click selects an item and opens its detail sidebar — a quick way to inspect something without leaving the list. In the app

Sign in. The workspace opens at Home, listing your projects in a table with columns Name, Members, Updated and a <n> results count.
Single-click a project row (e.g. Synthetic PLD Experiments). The row highlights blue and the detail sidebar opens on the right, showing the name, Modified … ago, the description, a Members label with <n> people, and a settings gear.

A selected project with its detail sidebar

From code First authenticate with the public REST API. Set DATAERAI_SERVER to your Dataerai site and DATAERAI_TOKEN to an access token for your account.

import os, requests

API   = os.environ.get("DATAERAI_SERVER", "https://<your-server>")
TOKEN = os.environ["DATAERAI_TOKEN"]

api = requests.Session()
api.headers.update({"Authorization": f"Bearer {TOKEN}"})
me = api.get(f"{API}/api/me/").json()
print("signed in as", me["email"])

So the rest of the tutorial runs end-to-end on the tutorial account, we create a small hierarchy from code — in the web app you’d click New project, + New collection, and drag a file into Upload instead. (The screenshots use a different seed account, Synthetic PLD Experiments, so the on-screen names won’t match the ones we create; the calls are the same.)

import csv, pathlib, shutil
from dataerai import DataeraiClient

# 1. A project (top of the hierarchy). Creating returns its root collection id.
resp = api.post(f"{API}/api/projects/",
                json={"name": "Navigation tutorial project",
                      "description": "Created from code by tutorial 02."})
resp.raise_for_status()
project  = resp.json()
root_id  = project["root_collection_id"]

# 2. A collection inside the project's root collection.
resp = api.post(f"{API}/api/collections/",
                json={"title": "Run-001",
                      "owner_type": "project", "owner_id": project["id"],
                      "parent_id": root_id})
resp.raise_for_status()
collection    = resp.json()
collection_id = collection["id"]

# 3. An asset with file content, uploaded with the SDK. The asset is owned
#    by the project and placed in our collection via collection_id.
data_file = pathlib.Path.home() / "dataerai-tutorial" / "nav.csv"
data_file.parent.mkdir(parents=True, exist_ok=True)
with open(data_file, "w", newline="") as fh:
    w = csv.writer(fh); w.writerow(["id", "value"])
    for i in range(10): w.writerow([i, i * i])

client = DataeraiClient(binary_path=shutil.which("dataerai") or "dataerai")
client.connect()
uploaded = client.upload(str(data_file), title="Run-001 readings",
                         owner_type="project", owner_id=project["id"],
                         collection_id=collection_id)
client.close()
asset_id = uploaded.asset_id

Drill into a project

Double-click a project to open it and see its collections. In the app

Double-click the project row. The list opens that project.
The list now shows the project’s child collections with columns Name, Type, Creator, Updated, and the toolbar gains the Data / Readme tabs plus Upload, + New collection, and + New asset buttons.

A project opened, showing its collections

From code List your projects, then list a collection’s child collections. This is the same data the web app uses when you double-click into a project.

Technical details

Each project carries a root_collection_id: the hidden root that holds its top-level collections and assets. root_collection_id is null if you can’t see the root, and collections form a DAG, so parent_ids may list several parents.

# Top of the hierarchy: my projects.
projects = api.get(f"{API}/api/projects/").json()
for p in projects:
    print(p["name"], "-> root:", p["root_collection_id"])

# Retrieve one project (adds current_user_role on top of the list shape).
detail = api.get(f"{API}/api/projects/{project['id']}/").json()
print("role:", detail["current_user_role"], "| root:", detail["root_collection_id"])

# Drill in: list the root collection's child collections (the project's top level).
children = api.get(f"{API}/api/collections/{root_id}/edges/").json()
for c in children:
    print(c["title"], "| is_root:", c["is_root"], "| parents:", c["parent_ids"])

Into a collection — the assets

Double-click a collection to see its assets (the leaf of the hierarchy). In the app

Double-click a collection row. The path above the list updates to show the project and collection you opened.
The list now shows that collection’s assets with columns Name, Type, Creator, Updated.

From code List a collection’s assets.

Technical details

The page of assets is in the JSON body, but the cursor/has-more metadata lives in the response headers: X-Page-Limit, X-Has-More, and X-Next-Cursor. Pass X-Next-Cursor back as the cursor param for the next page. Default limit is 100, max 1000. current_content is null if you lack read-content access.

r = api.get(f"{API}/api/collections/{collection_id}/assets/", params={"limit": 100})
assets = r.json()
print("page size:", r.headers["X-Page-Limit"], "| more:", r.headers["X-Has-More"])
for a in assets:
    content = a["current_content"]
    print(a["title"], "|", content["size_bytes"] if content else "no content", "bytes")
next_cursor = r.headers.get("X-Next-Cursor")  # pass as cursor= to fetch the next page

# Equivalent global listing filtered to this collection (same body + same headers):
same = api.get(f"{API}/api/assets/", params={"collection_id": collection_id, "limit": 50})
print("via /api/assets/?collection_id=:", [a["title"] for a in same.json()])

Select an asset to open its full detail panel, and use the floating toolbar to act on a selection. In the app

Single-click an asset row. The detail sidebar shows the record with four tabs: General, Metadata, Notes, Comments. The General tab lists Title, Type, Size, Alias, DID (the asset’s auto-minted persistent identifier, with a View DID document button), Tags (with an Add tag… input), Locked, Owner Type, Owner, Creator, Created, Updated, an Allocation dropdown, a Relationships card (add and browse provenance links — see Provenance & relationships), and a Citation panel (copy or download a citation in BibTeX, RIS, APA, MLA, or Chicago).
With one or more rows selected, a floating toolbar appears centered at the bottom reading <n> selected with Copy, Cut, Paste, Permissions, and a ⋮ (More actions) menu (Download, Copy Link, Edit, Delete, Provenance, Annotate, Unlink).

An asset's detail panel with the selection toolbar

Click the Metadata tab to see the asset’s metadata tree (the user metadata plus any current_content.extracted_metadata).

The asset detail sidebar on the Metadata tab

From code Retrieve one asset — its fields map 1:1 to the sidebar’s General tab (Title, Alias, ID, Tags, Locked, Owner Type, Owner, Creator, Created, Updated; Type/Size come from current_content.files, and the Metadata tab is metadata + current_content.extracted_metadata).

asset = api.get(f"{API}/api/assets/{asset_id}/").json()
print("title :", asset["title"])
print("owner :", asset["owner_type"], "->", asset["owner_name"])
print("locked:", asset["is_locked"], "| tags:", asset["tags"])
print("metadata:", asset["metadata"])
content = asset["current_content"]
if content:
    files = content["files"]
    print("size  :", content["size_bytes"], "bytes |", [f["filename"] for f in files])

Every view can be shared or bookmarked from the browser. Use the path above the list to jump back up to a project or parent collection. In the app

The path above the list shows where you are, such as Home, then the project, then the collection. Click any part of the path to jump straight to that level.
Copy the browser URL to share or bookmark the exact view you’re looking at.

The navigation path at a nested collection

From code The API can return an asset’s location, including its project and collection path, which is useful when you need to build links or move between related views.

# Resolve an asset's location.
loc = api.get(f"{API}/api/assets/{asset_id}/location/").json()
print("project :", loc["project"]["name"] if loc["project"] else None)
print("path    :", [c["title"] for c in loc["collection_path"]])

Get started

Get data in

Organize & describe

Verifiable identity

Datasets & analysis

Discover

AI & LLM search

Sharing & access

Account & organization

Attribution

Help & reference

Projects, collections & assets

Overview

Select and inspect

Drill into a project

Into a collection — the assets

Navigation paths & shareable links

Next steps

​Overview

​Select and inspect

​Drill into a project

​Into a collection — the assets

​Asset detail & the selection toolbar

​Navigation paths & shareable links

​Next steps

Overview

Select and inspect

Drill into a project

Into a collection — the assets

Asset detail & the selection toolbar

Navigation paths & shareable links

Next steps