Parann CMS

Overview

Roles

• Administrator — A single Substrate (SS58) address configured at setup. Can manage scribes, view config, and perform all CMS operations including deletion.
• Scribe — Addresses granted write access by the administrator. Can upload content and manage graph relationships.

Series

Content is organized into series — named collections identified by a slug. Series names must match the pattern ^[a-z0-9][a-z0-9_-]{0,62}[a-z0-9]$ (2–64 chars, lowercase alphanumeric, hyphens, and underscores).

Lookup Paths & Versioning

Each upload requires a lookup_path — a human-readable path within its series (e.g., images/logo.png). Lookup paths match ^(?:[A-Za-z0-9_-]+/)*[A-Za-z0-9_-]+\.[A-Za-z0-9]+$.

Uploading to the same lookup_path multiple times creates versioned entries. Each version gets an auto-incrementing version number (1, 2, 3, …). Path-based retrieval returns the latest version by default, while the /versions endpoint lists all versions.

UUIDs

Every upload receives a globally unique UUID (auto-generated or provided in extra_metadata.uuid). UUIDs enable cross-series references and are the primary identifiers used in graph relationships.

Graph Relationships

Uploads can be linked using semantic predicates (e.g., skos:broader, rel:derivedFrom). Relationships are directional (source → target) and support soft-deletion. This forms a knowledge graph across all CMS content.

Uploaded JSON/yObj content may also declare native edges in a top-level graph array. During upload materialization, CMS imports up to 100 valid entries into NDB for the uploaded lookup path and marks them native_cannot_delete: true. Native edges cannot be removed with the graph remove API; update the source yObj and upload a new version to change them. Omitting graph leaves existing native edges unchanged, while explicit "graph": [] prunes previously imported native edges for that source path.

Authentication

All API endpoints except public pages (/docs, /browse, /privacy, /terms), health checks (/_ah/health), and auth endpoints (/api/auth/challenge, /api/auth/verify, /api/auth/refresh) require a valid Bearer token in the Authorization header.

1. Request Challenge

Request

{
  "address": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"
}

Response (200)

{
  "challenge": {
    "address": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY",
    "timestamp": 1700000000,
    "nonce": "550e8400-e29b-41d4-a716-446655440000",
    "message": "Sign this message to authenticate with Parann CMS"
  }
}

2. Verify Signature

Signing Format

Request

{
  "address": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY",
  "message": "7b2261646472657373223a2235...hex_encoded_json...",
  "signature": "0xabc123...hex_encoded_signature..."
}

Response (200)

{
  "access_token": "a1b2c3d4...blake3_hex...",
  "refresh_token": "e5f6a7b8...blake3_hex...",
  "expires_in": 3600,
  "role": "admin",
  "address": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"
}

3. Refresh Token

Request

{
  "refresh_token": "e5f6a7b8...blake3_hex..."
}

Response (200)

{
  "access_token": "new_access_token...",
  "refresh_token": "new_refresh_token...",
  "expires_in": 3600,
  "role": "admin",
  "address": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"
}

4. Logout

Response (200)

{
  "message": "Logged out"
}

Organizations

Organizations group users and manage series. Roles: owner (full control), admin (manage series/members), member (read access). All org endpoints require JWT auth.

Create Organization

{"name": "My Org", "slug": "my-org", "description": "..."}

List My Organizations

Manage Members

{"role": "admin"}

Invite Member

{"email": "new@example.com", "role": "admin"}

{"token": "..."}

Organization Series

{"series_name": "main", "rpc_url": "wss://...", "chain_channel_id": 0}

Admin API

All admin endpoints require authentication and the caller must be the configured administrator.

Add Scribe

Request

{
  "address": "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty"
}

Response (201)

{
  "message": "Scribe added",
  "address": "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty"
}

Remove Scribe

Request

{
  "address": "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty"
}

Response (200)

{
  "message": "Scribe removed",
  "address": "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty"
}

List Scribes

Response (200)

{
  "scribes": [
    {
      "address": "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty",
      "granted_by": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY",
      "created_at": "2024-01-15T10:30:00"
    }
  ]
}

Get Config

Response (200)

{
  "admin_address": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY",
  "created_at": "2024-01-15T09:00:00"
}

Create/Update Blockchain Settings

Request

{
  "series": "my-series",
  "rpc_url": "wss://your-node-url:9944",
  "chain_channel_id": 1
}

Response (201)

{
  "message": "Blockchain settings saved",
  "settings": {
    "series": "my-series",
    "rpc_url": "wss://your-node-url:9944",
    "chain_channel_id": 1,
    "blockchain_paused": false,
    "consecutive_failures": 0,
    "signing_address": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"
  }
}

List Blockchain Settings

Response (200)

{
  "settings": [
    {
      "series": "my-series",
      "rpc_url": "wss://your-node-url:9944",
      "chain_channel_id": 1,
      "blockchain_paused": false,
      "consecutive_failures": 0,
      "created_at": "2024-01-15T10:00:00",
      "updated_at": "2024-01-15T10:00:00"
    }
  ]
}

Get Blockchain Settings

Response (200)

{
  "settings": {
    "series": "my-series",
    "rpc_url": "wss://your-node-url:9944",
    "chain_channel_id": 1,
    "blockchain_paused": false,
    "consecutive_failures": 0,
    "created_at": "2024-01-15T10:00:00",
    "updated_at": "2024-01-15T10:00:00"
  }
}

Delete Blockchain Settings

Response (200)

{
  "message": "Blockchain settings removed",
  "series": "my-series"
}

Resume Paused Series

Response (200)

{
  "message": "Blockchain registration resumed",
  "series": "my-series",
  "settings": {
    "series": "my-series",
    "rpc_url": "wss://your-node-url:9944",
    "chain_channel_id": 1,
    "blockchain_paused": false,
    "consecutive_failures": 0
  }
}

Blockchain Health Check

Response (200 — healthy)

{
  "series": "my-series",
  "rpc_url": "wss://your-node-url:9944",
  "chain_channel_id": 1,
  "health": {
    "healthy": true,
    "rpc_reachable": true,
    "chain_name": "Metarium",
    "runtime_version": "100",
    "actant_registered": true,
    "errors": []
  }
}

Response (503 — unhealthy)

{
  "series": "my-series",
  "rpc_url": "wss://your-node-url:9944",
  "chain_channel_id": 1,
  "health": {
    "healthy": false,
    "rpc_reachable": true,
    "chain_name": "Metarium",
    "runtime_version": "100",
    "actant_registered": false,
    "errors": ["Signing address is not in the actant set for channel 1"]
  }
}

YTypes

YTypes define content type schemas that validate typed uploads. Uploads may omit ytype; when omitted, the CMS treats the upload as a raw/untyped file and skips ytype schema validation. YTypes can be global (no series) or series-specific. Series-specific definitions override global ones.

Create YType

Request

{
  "type_name": "conversation",
  "json_schema": {"type": "object"},
  "description": "JSON conversation format",
  "series": "my-series"
}

Response (201)

{
  "ytype": {
    "type_name": "conversation",
    "series": "my-series",
    "description": "JSON conversation format",
    "json_schema": {"type": "object"},
    "created_at": "2024-01-15T10:00:00",
    "updated_at": "2024-01-15T10:00:00"
  }
}

List YTypes

Get / Update / Delete YType

Scribe yType Registration

A yType (yettagam type) is a content type definition that follows the yettagam type system — a standard for typed, versioned, inheritable content schemas. Every piece of content stored in the CMS is an instance of a yType.

As an app builder, you design your own yTypes to match your content model, then register them with the CMS. The CMS validates every yType document against the yettagam meta-schema and enforces the inheritance rules described below.

Designing a yType

Before writing JSON, think about what your app needs:

1. Identify your content types — What kinds of objects does your app work with? Each distinct content shape should be its own yType (e.g. blog_post, product_listing, sensor_reading).
2. Choose a parent type — Every custom yType must inherit from at least one existing type, and the inheritance chain must ultimately trace back to base. If it doesn't, the CMS will reject it. Start with /types/base/ for general content, or use a more specific parent like /types/media/ or /types/image/ if your content specialises one of those.
3. Define your schema — Specify the fields your content instances must have, using JSON Schema. Your schema extends the fields inherited from the parent.
4. Register — Submit the yType document via the API. The CMS validates it against the yettagam meta-schema and checks the inheritance chain.
5. Upload content — Once registered, upload content instances (yObjs) that conform to your yType's schema. Each upload is automatically pinned to the current version of the yType.

Inheritance

The built-in type hierarchy:

base (abstract) — root of all types
├── media (abstract)
│   ├── audio (concrete)
│   ├── document (concrete)
│   └── video (concrete)
├── ibase (abstract)
│   └── imedia (abstract)
│       └── image (concrete)
├── platform_specific (abstract)
│   ├── x_tweet (concrete)
│   └── youtube_video (concrete)
├── commit (concrete)
├── exhibition (concrete)
├── list (concrete)
├── url (concrete)
├── venue (concrete)
├── vr_device (concrete)
└── cms_event (concrete)

Inheritance constraints:

• Your schema must include all fields from the parent type plus your additional fields
• abstract types cannot be instantiated — they exist only as parents for other types to inherit from
• concrete types can be instantiated (used for uploads) and inherited from
• You cannot inherit from a type marked final
• You cannot inherit from a type marked singleton
• A singleton type allows only one instance per series
• Maximum inheritance depth: 10 levels
• No circular inheritance
• Multiple inheritance is allowed

Common patterns

Defining the Schema

A yType document is a JSON object with 12 required top-level fields. Omitting any one will fail validation.

{
  "$schema": "https://yettagam.net/ytype/1.0.0/schema.json",
  "$version": "1.0.0",
  "$role": "type-definition",
  "name": "my_custom_type",
  "label": "My Custom Type",
  "description": "A custom content type for my application",
  "kind": "concrete",
  "final": false,
  "singleton": false,
  "inherits_from": ["/types/base/"],
  "definition": {},
  "schema": {
    "type": "object",
    "properties": {
      "name":        { "type": "string" },
      "label":       { "type": "string" },
      "description": { "type": "string" },
      "uuid":        { "type": "string", "format": "uuid" },
      "ytype":       { "type": "string", "readOnly": true },
      "ytype_label": { "type": "string", "readOnly": true },
      "my_field":    { "type": "string", "description": "Your custom field" }
    },
    "required": ["name", "label", "description", "uuid", "ytype", "ytype_label"]
  }
}

Field reference

Schema: base fields

Since your yType inherits from base, include the base fields in your schema so validation works correctly:

"schema": {
  "type": "object",
  "properties": {
    "name":        { "type": "string", "description": "Name of the object" },
    "label":       { "type": "string", "description": "Human-readable display name" },
    "description": { "type": "string", "description": "Description of the object" },
    "uuid":        { "type": "string", "format": "uuid" },
    "ytype":       { "type": "string", "readOnly": true },
    "ytype_label": { "type": "string", "readOnly": true },

    "your_custom_field": { "type": "string" }
  },
  "required": ["name", "label", "description", "uuid", "ytype", "ytype_label"]
}

Schema: supported property types

{
  "text_field":     { "type": "string" },
  "with_pattern":   { "type": "string", "pattern": "^[A-Z]{3}$" },
  "with_format":    { "type": "string", "format": "uri" },
  "a_number":       { "type": "number", "minimum": 0, "maximum": 100 },
  "an_integer":     { "type": "integer", "minimum": 1 },
  "a_flag":         { "type": "boolean" },
  "a_list":         { "type": "array", "items": { "type": "string" } },
  "nested_object":  { "type": "object", "properties": { "sub": { "type": "string" } } },
  "with_enum":      { "type": "string", "enum": ["draft", "published", "archived"] },
  "read_only":      { "type": "string", "readOnly": true },
  "with_default":   { "type": "string", "default": "untitled" }
}

Register a yType

Request

Send the full yType document as the JSON body:

curl -X POST https://cms.parann.com/api/cms/v2/my-series/ytypes \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d @my_type.ytype.json

Complete example: Blog Post yType

{
  "$schema": "https://yettagam.net/ytype/1.0.0/schema.json",
  "$version": "1.0.0",
  "$role": "type-definition",
  "name": "blog_post",
  "label": "Blog Post",
  "description": "A blog post with title, body, author, tags, and publication status",
  "kind": "concrete",
  "final": false,
  "singleton": false,
  "inherits_from": ["/types/base/"],
  "definition": {},
  "schema": {
    "type": "object",
    "properties": {
      "name":        { "type": "string", "description": "URL slug" },
      "label":       { "type": "string", "description": "Display title" },
      "description": { "type": "string", "description": "Short excerpt" },
      "uuid":        { "type": "string", "format": "uuid" },
      "ytype":       { "type": "string", "readOnly": true },
      "ytype_label": { "type": "string", "readOnly": true },
      "title":       { "type": "string" },
      "body":        { "type": "string", "description": "Markdown or HTML" },
      "author":      { "type": "string" },
      "tags":        { "type": "array", "items": { "type": "string" } },
      "status":      { "type": "string", "enum": ["draft", "published", "archived"] },
      "published_at": { "type": "string", "format": "date-time" },
      "word_count":  { "type": "integer", "minimum": 0 },
      "cover_image": {
        "type": "object",
        "properties": {
          "ypath":     { "type": "string" },
          "mime_type": { "type": "string" },
          "alt_text":  { "type": "string" }
        }
      }
    },
    "required": ["name", "label", "description", "uuid", "ytype", "ytype_label", "title", "body", "status"]
  }
}

Response (201)

{
  "ytype": {
    "type_name": "blog_post",
    "series": "my-series",
    "ytype_version": "1.0.0",
    "kind": "concrete",
    "inherits_from": ["/types/base/"],
    "registered_by": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"
  }
}

Error responses

List yTypes

curl https://cms.parann.com/api/cms/v2/my-series/ytypes \
  -H "Authorization: Bearer TOKEN"

Get a yType

# Latest version
curl https://cms.parann.com/api/cms/v2/my-series/ytypes/blog_post \
  -H "Authorization: Bearer TOKEN"

# Specific version
curl "https://cms.parann.com/api/cms/v2/my-series/ytypes/blog_post?version=1.0.0" \
  -H "Authorization: Bearer TOKEN"

Versioning

yTypes use semver (X.Y.Z). To evolve a yType, re-register it with a strictly higher version number. The CMS enforces this — you cannot overwrite an existing version.

• Old versions remain immutable — existing content pinned to an older version continues to validate against its original schema
• New uploads automatically use the latest version
• Content is pinned as type_name@version (e.g. blog_post@1.0.0) at upload time — the schema never shifts under existing content

# Register version 1.1.0 (adds a new field)
curl -X POST https://cms.parann.com/api/cms/v2/my-series/ytypes \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "$schema": "https://yettagam.net/ytype/1.0.0/schema.json",
    "$version": "1.1.0",
    "$role": "type-definition",
    "name": "blog_post",
    ...
  }'

Validation checklist

Before submitting a yType document, verify:

• All 12 required fields are present
• $version is valid semver (X.Y.Z — digits only, no v prefix)
• $role is exactly "type-definition"
• name is lowercase alphanumeric with hyphens/underscores only
• name is not a reserved default type name
• inherits_from is a non-empty array — the chain must trace back to base
• schema.type is "object" with a "properties" object
• Every property has a "type" field
• Schema includes the base fields (name, label, description, uuid, ytype, ytype_label)
• If re-registering, $version is strictly higher than the current latest

For the full yettagam type specification, see yettagam.net.

Contributing yTypes to yettagam

yettagam is an open schema ecosystem — anyone can contribute new types. When you create a yType that could be useful to others, we strongly encourage you to submit it to the public yettagam repository so it becomes part of the shared type registry at yettagam.net.

Steps to contribute:

1. Create a .ytype file — Author your type definition following the meta-schema at yettagam.net/ytype/1.0.0/schema.json. Include all required fields: $schema, $version, $role, name, label, description, kind, final, singleton, inherits_from, definition, and schema.
2. Add files to the directory structure — Place your type in the correct layout:

   ytypes/
     my_type/
       1.0.0/my_type.ytype    # versioned permalink
       latest.ytype            # identical copy

   Update ytypes/index.json with your type entry (keep alphabetical order).

3. Submit a pull request — Fork github.com/MetariumProject/yettagam-net-website, create a branch, and open a PR. See the full contributing guide for naming conventions, predicate groups, and the review process.

CMS v2 API

All content endpoints require authentication. The base path is /api/cms/v2.

Upload

Request — Direct (text, < 900 KB)

{
  "content_text": "{\"title\": \"Example\"}",
  "content_type": "application/json",
  "lookup_path": "data/example.json",
  "ytype": "conversation",
  "extra_metadata": {"tags": ["demo"]}
}

Request — Direct (binary, < 900 KB)

{
  "content": "iVBORw0KGgo...base64...",
  "content_type": "image/png",
  "lookup_path": "images/icon.png",
  "ytype": "image"
}

Response — Direct (201)

{
  "message": "Upload successful",
  "event_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "event_key_urlsafe": "ahNkZXZ-...",
  "upload_status": "uploaded",
  "storage_type": "direct"
}

Request — Staged (≥ 900 KB)

{
  "file_size": 5242880,
  "filename": "photo.jpg",
  "content_type": "image/jpeg",
  "lookup_path": "images/photo.jpg",
  "ytype": "image"
}

Response — Staged (201)

{
  "message": "Upload initiated",
  "event_uuid": "660f9500-f39c-51e5-b827-557766551111",
  "event_key_urlsafe": "ahNkZXZ-...",
  "upload_status": "pending_upload",
  "upload_url": "https://storage.googleapis.com/...",
  "upload_url_expires_in": 3600,
  "gcs_upload_path": "staged/my-series/images/photo.jpg/photo.jpg",
  "storage_type": "staged"
}

Request — Chunked (parallel upload for large files)

{
  "file_size": 524288000,
  "filename": "large-video.mp4",
  "content_type": "video/mp4",
  "lookup_path": "media/large-video.mp4",
  "ytype": "video",
  "chunk_size": 10485760
}

Response — Chunked (201)

{
  "message": "Chunked upload initiated",
  "event_uuid": "880b1700-g50e-72g7-d049-779988773333",
  "event_key_urlsafe": "ahNkZXZ-...",
  "upload_status": "pending_chunk_upload",
  "storage_type": "chunked",
  "chunk_count": 50,
  "chunk_size": 10485760,
  "chunk_urls": [
    {"upload_url": "https://storage.googleapis.com/...", "gcs_path": "staged/.../chunk_000000", "chunk_index": 0},
    {"upload_url": "https://storage.googleapis.com/...", "gcs_path": "staged/.../chunk_000001", "chunk_index": 1},
    ...
  ]
}

Request Fields

Confirm (Staged / Chunked)

Response (200)

{
  "message": "Upload confirmed",
  "event_uuid": "660f9500-f39c-51e5-b827-557766551111",
  "event_key_urlsafe": "ahNkZXZ-...",
  "upload_status": "uploaded"
}

Error Responses

List Paths

Response (200)

{
  "series": "my-series",
  "lookup_path": "data",
  "children": [
    {
      "segment": "example.json",
      "full_path": "data/example.json",
      "parent_path": "data",
      "depth": 2,
      "ytype": "conversation",
      "child_count": 0,
      "upload_event_count": 2,
      "latest_upload_event_uuid": "770a0600-...",
      "latest_event_at": "2024-01-16T14:00:00",
      "has_content": true,
      "extra_metadata": {"tags": ["demo"]}
    }
  ]
}

Metadata

Response (200)

{
  "data": {
    "full_path": "data/example.json",
    "series": "my-series",
    "ytype": "conversation",
    "versions": [
      {
        "version_number": 2,
        "event_uuid": "770a0600-...",
        "upload_status": "uploaded",
        "content_hash": "a1b2c3d4..."
      },
      {
        "version_number": 1,
        "event_uuid": "550e8400-...",
        "upload_status": "uploaded",
        "content_hash": "e5f6a7b8..."
      }
    ],
    "extra_metadata": {"tags": ["demo"]}
  }
}

Content

Response (200)

{
  "data": {
    "uuid": "770a0600-a40d-62f6-c938-668877662222",
    "event_type": "upload",
    "version_number": 2,
    "upload_status": "uploaded",
    "storage_type": "direct",
    "ytype": "conversation",
    "content_type": "application/json",
    "content_hash": "a1b2c3d4...",
    "file_size": 28,
    "content_text": "{\"title\": \"Updated Example\"}",
    "download": {
      "content_storage_path": "content/a1/b2/a1b2c3d4...",
      "download_url": "https://storage.googleapis.com/..."
    }
  }
}

Response — Chunked Download (200)

{
  "data": {
    "event_uuid": "770a0600-a40d-62f6-c938-668877662222",
    "content_type": "video/mp4",
    "file_size": 52428800,
    "filename": "video.mp4",
    "chunk_size": 10485760,
    "chunk_count": 5,
    "chunks": [
      {"download_url": "https://storage.googleapis.com/...", "chunk_index": 0, "start": 0, "end": 10485759, "size": 10485760, "headers": {"Range": "bytes=0-10485759"}},
      {"download_url": "https://storage.googleapis.com/...", "chunk_index": 1, "start": 10485760, "end": 20971519, "size": 10485760, "headers": {"Range": "bytes=10485760-20971519"}},
      ...
    ]
  }
}

Get Specific Version

Status

Response (200)

{
  "data": {
    "event_uuid": "660f9500-f39c-51e5-b827-557766551111",
    "event_key_urlsafe": "ahNkZXZ-...",
    "version": 1,
    "upload_status": "uploaded",
    "blockchain_status": "pending",
    "content_metadata": { ... },
    "download": {
      "content_storage_path": "content/a1/b2/a1b2c3d4...",
      "download_url": "https://storage.googleapis.com/..."
    }
  }
}

Upload Status Values

Graph v2 API

Graph endpoints manage semantic relationships (edges) between lookup paths. All are under /api/cms/v2 and require authentication. Edges are identified by a deterministic edge_id derived from the source path, predicate, and target path.

Add Edge

Request — single target (backward-compatible)

{
  "source_path": "data/example.json",
  "predicate": "skos:broader",
  "target_path": "data/parent.json",
  "target_series": "other-series"
}

Request — multiple targets (batch)

{
  "source_path": "data/example.json",
  "predicate": "skos:broader",
  "target_paths": [
    "data/parent.json",
    "data/grandparent.json",
    "data/uncle.json"
  ],
  "target_series": "other-series"
}

Request Fields

Response — single target via target_path (201)

{
  "message": "Graph edge created",
  "edge": {
    "edge_id": "my-series:data/example.json::skos:broader::other-series:data/parent.json",
    "source_series": "my-series",
    "source_path": "data/example.json",
    "predicate": "skos:broader",
    "target_series": "other-series",
    "target_path": "data/parent.json",
    "status": "active",
    "created_event_uuid": "880b1700-...",
    "removed_event_uuid": null,
    "created_at": "2024-01-15T11:00:00",
    "last_updated": "2024-01-15T11:00:00",
    "updated_at": "2024-01-15T11:00:00"
  },
  "created_event_uuid": "880b1700-..."
}

Response — batch via target_paths (201)

{
  "message": "3 edge(s) created, 0 already existed",
  "edges": [
    {
      "edge_id": "...",
      "source_series": "my-series",
      "source_path": "data/example.json",
      "predicate": "skos:broader",
      "target_series": "other-series",
      "target_path": "data/parent.json",
      "status": "active",
      ...
    },
    { "..." : "..." },
    { "..." : "..." }
  ],
  "created_event_uuids": ["880b1700-...", "991c2800-...", "aa2d3900-..."],
  "count": 3
}

Response — partial failure (207 Multi-Status)

{
  "message": "1 edge(s) created, 0 already existed",
  "edges": [ { "..." : "..." } ],
  "created_event_uuids": ["880b1700-..."],
  "count": 1,
  "errors": [
    {
      "index": 1,
      "target_path": "docs/target-fail",
      "error": "Source path not found"
    }
  ]
}

Error Responses

List Outgoing Edges

Response (200)

{
  "name": "example.json",
  "label": "example.json",
  "description": "Outgoing edges for data/example.json",
  "ytype": "/types/graph/",
  "ytype_label": "Graph",
  "series": "my-series",
  "lookup_path": "data/example.json",
  "source_path": "data/example.json",
  "direction": "outgoing",
  "edges": [
    {
      "edge_id": "my-series:data/example.json::skos:broader::other-series:data/parent.json",
      "source_series": "my-series",
      "source_path": "data/example.json",
      "predicate": "skos:broader",
      "target_series": "other-series",
      "target_path": "data/parent.json",
      "status": "active",
      "created_event_uuid": "880b1700-...",
      "removed_event_uuid": null,
      "created_at": "2024-01-15T11:00:00",
      "last_updated": "2024-01-15T11:00:00",
      "updated_at": "2024-01-15T11:00:00"
    }
  ]
}

Remove Edge

Request

{
  "source_path": "data/example.json",
  "edge_id": "my-series:data/example.json::skos:broader::other-series:data/parent.json"
}

Response (200)

{
  "message": "Graph edge removed",
  "edge": { ... },
  "removed_event_uuid": "990c2800-..."
}

Incoming Edges

Response (200)

{
  "name": "parent.json",
  "label": "parent.json",
  "description": "Incoming edges for data/parent.json",
  "ytype": "/types/graph/",
  "ytype_label": "Graph",
  "series": "my-series",
  "lookup_path": "data/parent.json",
  "target_path": "data/parent.json",
  "direction": "incoming",
  "edges": [ ... ]
}

Predicates

Response (200)

{
  "predicates": {
    "owl": ["owl:differentFrom", "owl:equivalentTo", "owl:sameAs"],
    "rdfs": ["rdfs:isDefinedBy", "rdfs:seeAlso", "rdfs:subClassOf"],
    "skos": ["skos:broadMatch", "skos:broader", "skos:closeMatch", ...],
    ...
  }
}

Predicate Reference

Event Manifest & Replay

Every mutation in the CMS — uploads, metadata updates, content removals, and graph edge changes — is recorded as an immutable CMSEvent with a deterministic event yobj artifact. This enables independent replay and auditing without relying on the Datastore.

Storage Layout

Each event produces storage artifacts in the GCS bucket:

The event yobj contains the full event state at creation time: event type, lookup path, content hash, metadata patch, graph edges, and a monotonic series_event_sequence number.

Independent Replay Algorithm

To reconstruct the complete state of a series from storage alone:

1. List all events/W*/<event_uuid>.yobj blobs in the bucket
2. Parse each .yobj file as JSON
3. Filter by series field to isolate one series
4. Sort by (series_event_sequence, event_uuid) for deterministic ordering
5. Fetch content blobs for upload events using the content_hash field
6. Apply transitions in order: uploads set content, metadata events patch fields, remove events tombstone content, relationship events modify the graph

Registration Semantics

Blockchain registration is two-phase for upload events and single-phase for non-upload events:

• Upload events: Phase 1 registers the content KURI (blake3://<content_hash>), then automatically chains to Phase 2 which registers the event KURI (blake3://<event_yobj_hash>).
• Non-upload events (metadata, remove, relationship): Single-phase registration of the event KURI only.

Mutation Endpoints

Blockchain Registration

When content is uploaded and the series has blockchain settings configured, the CMS automatically registers a BLAKE3 content hash on the Metarium blockchain. Each series has its own RPC URL and channel ID, configured via the admin API. A global mnemonic is used for signing.

Registration Flow

1. Hash content — Compute a BLAKE3 hash of the uploaded content.
2. Format as KURI — Construct a content-addressable identifier: blake3://<64-char-hex-hash>.
3. Enqueue async task — A deferred task is created for blockchain registration.
4. Check on-chain — The worker verifies whether the KURI is already registered on the blockchain.
5. Submit extrinsic — Call arikuri_added on the Metarium chain to register the hash.
6. Store provenance — Save the transaction hash, block height, and other metadata alongside the upload.

Retry & Circuit Breaker

• Registration tasks retry automatically on transient failures (3 retries with exponential backoff: 30s, 60s, 120s).
• After 5 final failures for a series, the circuit breaker pauses blockchain registration for that series.
• An admin can resume a paused series via POST /api/admin/blockchain-settings/<series>/resume.

Signing Address

KURI Format

A KURI (from the Tamil word kuri, meaning mark) is a content-addressable identifier using the format:

blake3://<64-character-hex-hash>

Example: blake3://a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2

Provenance Fields

When blockchain registration succeeds, the following provenance fields are stored with the upload:

Status Values

Prerequisites

Registration Reliability

The CMS ensures every event is eventually registered on the blockchain, even in the face of transient failures, node downtime, or dropped tasks.

Retry Policy

Every registration attempt is retried up to 6 total attempts (initial + 5 retries) with exponential backoff: 30s → 60s → 2 min → 5 min → 10 min. All errors are treated as retryable — there are no permanent failures. After exhausting retries, the event is marked failed_retryable for the cron sweep to pick up.

Automatic Sweep

A cron job runs every 5 minutes, scanning all blockchain-configured series for unregistered events. Candidates are re-enqueued oldest-first with staggered delays (5 s apart), processing a batch of 5 events per sweep. This prevents thundering-herd overload while steadily clearing any backlog.

Auto-Resume

When the circuit breaker pauses a series, the sweep automatically checks blockchain health every 30 minutes. If the health check passes (RPC reachable and actant registered), the series is automatically resumed and backfill begins — no manual intervention required.

Dropped Task Protection

Even if App Engine's deferred task queue silently drops a task, the cron sweep catches the unregistered event within 5 minutes and re-enqueues it.

Deferred Registration

Uploads during a blockchain pause succeed normally — content is stored and the upload response includes "blockchain_registration": "deferred". The event is automatically registered once the series resumes.

Monitoring

Admin Dashboard

A visual admin dashboard is available at /dashboard for admin users.

Claim Protection

Transactional per-phase claims prevent duplicate blockchain calls from concurrent workers. Each registration phase (content and event) is claimed atomically before execution — if another worker recently claimed the same phase, the duplicate is skipped.

Substrate Signing

Generate a Keypair

from substrateinterface import Keypair

# Generate new mnemonic and keypair
mnemonic = Keypair.generate_mnemonic()
keypair = Keypair.create_from_mnemonic(mnemonic)

print("Mnemonic:", mnemonic)
print("Address: ", keypair.ss58_address)

Full Authentication Example

import json
import requests
from substrateinterface import Keypair

BASE_URL = "https://your-cms-instance.appspot.com"
keypair = Keypair.create_from_mnemonic("your twelve word mnemonic ...")

# Step 1: Request challenge
resp = requests.post(f"{BASE_URL}/api/auth/challenge", json={
    "address": keypair.ss58_address
})
challenge = resp.json()["challenge"]

# Step 2: Sign the challenge
message_str = json.dumps(challenge, separators=(',', ':'))
message_bytes = message_str.encode('utf-8')
message_hex = message_bytes.hex()
signature = keypair.sign(message_bytes)
signature_hex = signature.hex()

# Step 3: Verify and get tokens
resp = requests.post(f"{BASE_URL}/api/auth/verify", json={
    "address": keypair.ss58_address,
    "message": message_hex,
    "signature": signature_hex
})
tokens = resp.json()
access_token = tokens["access_token"]

# Step 4: Use the token
headers = {"Authorization": f"Bearer {access_token}"}
resp = requests.get(f"{BASE_URL}/api/cms/my-series/list", headers=headers)
print(resp.json())

Refresh Tokens

# When access token expires (after 1 hour), use the refresh token:
resp = requests.post(f"{BASE_URL}/api/auth/refresh", json={
    "refresh_token": tokens["refresh_token"]
})
new_tokens = resp.json()
# Refresh tokens last 30 days

About & Credits

Parann CMS is part of the Metarium modular software ecosystem.

Parann CMS

Metarium AI (metarium.ai)

Mummai Chain

Infrastructure Choices