Key Concepts

Entities

Everything in Arke is an entity. Files, folders, users, collections, agents—they all share the same base structure called Eidos. An entity is a versioned JSON manifest stored in content-addressed storage.

This unified model means there's one API for everything: POST /entities creates any type, GET /entities/{id} retrieves any type, and PUT /entities/{id} updates any type. The type field determines what validation rules apply.

Each entity has:

• A persistent ID (ULID) that never changes
• A type (file, folder, collection, user, etc.)
• Properties (type-specific metadata)
• Relationships (connections to other entities)
• Content (optional binary files attached to the entity)
• A version chain linking back to all previous versions

Content-Addressed Versioning

Every version of an entity is stored as an immutable manifest, keyed by its content hash (CID). The entity's ID resolves to its latest version via a tip pointer.

Entity ID → Tip → CID → Manifest (immutable)

When you update an entity, a new manifest is created with a prev link pointing to the previous version's CID. The tip pointer is atomically swapped to the new CID. The old version is never modified or deleted.

This gives you:

• Immutable history—every version is permanent
• Conflict detection—updates require Compare-And-Swap (CAS) against the current tip
• Integrity—content hashes guarantee data hasn't been tampered with

Compare-And-Swap (CAS)

To update an entity, you must provide the CID you expect to be the current tip. If someone else updated the entity since you last read it, the CIDs won't match and you'll get a 409 Conflict error. This prevents lost updates in concurrent environments.

Relationships

Entities connect to each other through relationships. A relationship has:

• A predicate (the type of connection, e.g. contains, references, in)
• A peer (the target entity ID)
• Optional metadata (key-value properties on the relationship itself)

For example, the novel entity "Moby Dick; Or, The Whale" (01KFNR81RMVAX2BBMMBW51V97D) might have a contains relationship pointing to "Chapter 1. Loomings" (01KFNR849AZNBWE9DYJRZR7PSA), while the chapter has a in relationship pointing back to the novel.

Relationships are stored inside the entity manifest, so they're versioned along with everything else.

Collections

A collection is a permission boundary. It is best practice to place your entity into one of your collections, as the collection determines who can view, edit, or manage its contents. If you do not assign a collection to your entity anybody can edit it!

For instance, you might create a "Moby Dick" collection (01KFNR0H0Q791Y1SMZWEQ09FGV) to hold the original text file, the novel entity, all chapter entities, and character analysis documents.

By default anyone has view rights to any collection.

Collections have roles (owner, admin, editor, viewer) assigned to users. A user's role in a collection determines what actions they can take on entities within it.

Content Attachment

Any entity can have binary content attached—not just file entities. Content is stored in the properties.content map as named entries:

{
  "properties": {
    "content": {
      "v1": { "cid": "bafkrei...", "size": 1048576, "content_type": "application/pdf" },
      "thumbnail": { "cid": "bafkrei...", "size": 10240, "content_type": "image/png" }
    }
  }
}

This flexibility means:

• A folder can have a cover image
• A user can have a profile photo
• Any custom entity type can store files

Content is uploaded via POST /entities/{id}/content and downloaded via GET /entities/{id}/content. See Files & Content for details.

Entity Types

Networks

Arke has two networks:

• Main network—Production data. Standard 26-character ULIDs.
• Test network—Isolated test data. IDs are prefixed with II (impossible in real ULIDs), routing to separate storage buckets. Test network entities are not attested for on Arweave and will be deleted from cloud storage after 30 days.

Both networks run on the same infrastructure, but test data is fully isolated.