Data items

Where this lives

In the product the surface is called Data items, under Data. In the API the entity is still a data item — every endpoint below says /data items — and the two words mean the same thing.

How data moves across Haiyz

One hosted item, every service. The diagram shows what reads it and what shares it; nothing copies it.

The model

An item is a name plus an ordered list of versions. Each version is one file of up to 50 MB, stored as uploaded.

• Uploading to an existing item adds a version; the previous ones stay downloadable and a map or a room can pin any of them. A snapshot of an editable layer is a version too, marked as such.
• A version never changes after upload. Correct a file by uploading the corrected one as the next version — or, on an editable layer, by editing its features; the upload then stays as history.
• Any file is accepted. Spatial formats get validation and a preview; anything else is stored, scanned and served as-is.
• Every version carries its size and checksum, which is what the desktop and the version-check endpoint use to tell whether a copy is current. A checked-out editable layer is current by its sync version instead.
• A ready Hyz Layer can be switched to editable. Its rows then become the item's current data, a new file version is refused while editing is on, and the item wears an Editable chip.

Validation is enrichment, not a gate

When a version is a recognised spatial format, the engine reads it and records what it found — the coordinate system, the geometry type, the feature count, the bounding box, warnings. The record is attached to the version and shown on the page:

"validation": {
  "valid": true,
  "crs": "EPSG:4326",
  "geometryType": "Point",
  "featureCount": 1,
  "bbox": [46.6753, 24.7136, 46.6753, 24.7136],
  "layers": [],
  "warnings": []
}

Scanning gates delivery, not upload

Every version is scanned for malware after upload. The scan has four states, and the state decides who may download the file — never whether it was accepted:

• An upload is never blocked by the scanner. The version exists the moment the upload finishes.
• The owner can see and download a version while its scan is pending.
• Everyone else — viewers, share links, data rooms, the desktop — receives clean versions only.
• A deployment without a scanner marks versions unsupported; delivery then follows the owner's visibility settings alone.

Who sees what

An item has one visibility. Private is yours alone; unlisted opens by link to anyone signed in; public is listed in the catalog; org is visible to your organization's members according to their role:

Inside an organization the role decides what a member may do with the organization's items:

The visibility values and the role names are the API's own enumerations; they are printed here exactly as the API expects them.

Share links

A share link hands one version to people without an account. It carries a scope, an expiry (7 days by default, 90 at most), an optional use cap, and whether a sign-in is required.

scope

What the link opens: a single version, or the item's latest clean version at the time of the visit.

expiresInDays

Lifetime in days. Defaults to 7; the maximum is 90. An expired link answers 410.

maxUses

Optional. After this many downloads the link stops working and answers 429.

requireLogin

Optional. When set, the visitor must be signed in — the link then works like an unlisted item.

• The link's token is shown once, when the link is created. It is not stored in a readable form afterwards.
• Opening a link resolves to a download URL that is valid for 120 seconds and bound to that file; the link itself can be shared, the resolved URL should not be.
• A link never serves a version whose scan is pending or failed.
• Revoking a link takes effect immediately; the item and its versions are untouched.

Data rooms

A data room bundles up to 50 pinned versions for a group of people — a delivery, a review set, a tender package — with roles and an activity log.

• A room holds versions, not items: what a recipient sees does not change when a new version is uploaded unless you pin it.
• Every open, download and change is recorded in the room's log, visible to its managers.
• Three roles: viewers open and download, collaborators add and pin versions, managers change membership and settings.
• A group can be added to a room as one member; its people inherit the room role together.

Groups

A group is a named list of members. It is a way to grant access to several people at once; it is not a seat and it holds nothing of its own.

• A group has an owner and members; the owner is not automatically a member.
• Members join by invitation, from the group page or by e-mail.
• When a group is added to a data room, a dashboard or a map, every member receives that object's role through the group.
• Group membership changes are recorded, and removing a member removes every access they held through the group.

Live sources

An item can point at an external service — an Esri REST layer, a portal — instead of holding a file. The platform then reads rows from the source when the item is opened.

• A live item is read through the platform, never directly from the browser, so the source's credentials stay on the server.
• A hard copy can be taken at any time: the current rows become a stored version like any upload. (This is not the Snapshot version kind, which belongs to editable layers.)
• Maps built on a live item show its rows at the time the map was published; a refresh pulls the source again.

Hard copies

A hard copy freezes a live source, a tool result or another item's version into a stored version of your own. It is the way to keep a dated snapshot of data you do not control.

Editing in place

A ready Hyz Layer can be switched to editable by a manager of the item. From then on its rows are the live copy: editors change features in the browser, offline in Hyz Desktop with sync, and from Hyz Field through a campaign target. Every change passes two checks on the server — the person's permission for the operation, and the feature's lock plus the layer's rules — and is logged. Snapshots store the live rows as versions of kind snapshot and can be restored.

• While any layer of the item is editable, POST /data items/:id/versions answers 409 EDITING_BLOCKS_UPLOAD; take a snapshot or switch editing off first.
• Two plan limits apply: editableLayers (layers with editing on, per owner) and editsPerMonth (applied edits per calendar month). Both answer 409 PLAN_LIMIT_REACHED.
• The full model is in the Data guides: Editable layers, Who may edit, the rules, editing in the browser and in Hyz Desktop, the Field bridge, history and snapshots, and every refusal reason. The endpoints are in the API reference under /data items/:id/editing.

Read the editing guides

Save from a tool run

The result of any tool that produces a file can be saved as a data item, or as a new version of one, from the run's result panel — without downloading and re-uploading it.

Quotas

Uploads are metered as runs on the tool ledger, under the data item-upload tool key, with the same windows as any metered tool.

Storage is a cumulative ceiling per owner across every version of every item:

• Deleting an item releases the bytes of all its versions at once.
• A new version adds its size to the total; older versions keep counting until the item is deleted.
• Editable layers and edits per month are two further plan limits, separate from storage and from tool runs; see Plans and limits.

Error codes

The codes the data surface answers with, bound to their HTTP status. Meanings mirror the bilingual message the API returns.

Open data, and where to next

A public item can be promoted to the open-data catalog, where it is listed for everyone with its licence and its versions. Promotion is reviewed; a promoted item cannot be deleted while it is listed.

Data rooms and groups have guides of their own under Data and Sharing; the tool ledger and its windows are on the quotas page.