Schemas

ApiEnvelope

Standard response envelope wrapping all API responses. Every response includes a trace ID for debugging, a machine-readable status, and a human-readable message.

status

string · enum · required

Machine-readable status code

Enum values:

CREATED

ACCEPTED

NO_CONTENT

BAD_REQUEST

UNAUTHORIZED

FORBIDDEN

NOT_FOUND

message

string · required

Human-readable status message

traceId

string

Unique request trace ID for debugging and log correlation

Error

Standard error response envelope. All API errors follow this shape. The status field maps to AppError codes in the Lambda layer.

status

string · enum · required

Machine-readable error code

Enum values:

BAD_REQUEST

UNAUTHORIZED

FORBIDDEN

NOT_FOUND

CONFLICT

UNPROCESSABLE_ENTITY

ERROR

message

string · required

Human-readable error description

traceId

string

Request trace ID for debugging and log correlation

UserSummary

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

userId

string · uuid · required

Unique identifier of the user

username

string · required

Display username

photoUrl

string | null

URL to the user's avatar image

BreadcrumbItem

A single breadcrumb navigation entry with label and link.

label

string · required

Display text for the breadcrumb link

href

string · required

Relative URL path for the breadcrumb

CollectionItemDef

Definition for a single item within a collections-type template slot. Specifies the item key, display label, and optional defaults.

itemKey

string · minLength: 1 · required

Unique key identifying this item within the collection

label

string · minLength: 1 · required

Human-readable label for this collection item

object

Default field values pre-populated for new suggestions

lockedFields

string[]

Field keys that cannot be modified by suggestions

EntityLayoutTemplate

Defines a content slot in an entity's layout. Templates are inherited from the parent node and determine what topics appear on the entity page.

topicKey

string · minLength: 1 · required

Unique key identifying this topic slot

component

string · minLength: 1 · required

React component key used to render this template section

title

string · minLength: 1 · required

Display title for this template section

kind

string · enum · required

Whether this slot holds a single value or a collection of items

Enum values:

single

collections

order

integer · min: 0 · required

Display order (lower numbers appear first)

object

Optional hero image for this template section

collectionMode

string · enum

Display mode for collections-type templates

Enum values:

expandable

closed

rule

string · minLength: 1

JSON Schema rule key for validating suggestion values

object[]

Pre-defined items within a collections-type template

ComputeConsensusResult

Summary of a consensus computation run.

entityId

string · uuid · required

Entity that was recomputed

targetsProcessed

integer · required

Number of topic targets evaluated

winnersUpdated

integer · required

Number of winners that changed during this computation

computedAt

string · date-time · required

Timestamp of the computation

ConsensusItem

A single consensus record representing the winning suggestion for a specific topic target within an entity.

entityId

string · uuid · required

Entity this consensus belongs to

topicKey

string · required

Topic key this consensus covers

value

required

The winning suggestion's value payload

confidence

number · required

Confidence score (0-1) based on vote distribution

upvotes

integer · required

Total upvotes for the winning suggestion

downvotes

integer · required

Total downvotes for the winning suggestion

totalVotes

integer · required

Total number of votes cast

computedAt

string · date-time · readOnly · required

When this consensus was last computed

createdAt

string · date-time · readOnly · required

When this consensus record was first created

updatedAt

string · date-time · readOnly · required

When this consensus record was last updated

itemKey

string | null

Item key for collection-type topics, null for single topics

winningSuggestionId

string | null · uuid

ID of the suggestion that won consensus, null if no winner

authorId

string

User ID of the winning suggestion's author

authorUsername

string

Username of the winning suggestion's author

authorPhotoUrl

string

Avatar URL of the winning suggestion's author

ConsensusPageEntity

Lightweight entity metadata included in consensus page responses.

entityId

string · uuid · required

Unique identifier of the entity

nodeId

string · uuid · required

Parent node identifier

title

string · required

Display title

slug

string · required

URL-safe slug

slugPath

string · required

Full hierarchical slug path

ConsensusPageData

Full consensus page payload for SSR rendering. Contains entity metadata, layout configuration, and all computed consensus values.

object · required

Lightweight entity metadata included in consensus page responses.

object[] · required

Layout template configuration for this entity

object · required

Map of topic keys to their consensus values

computedAt

string · date-time · required

When the consensus was last computed

ModerateSuggestionInput

Request body for moderating a suggestion.

action

string · enum · required

Moderation action to take

Enum values:

approve

reject

reason

string

Optional reason for the moderation decision

ModerateSuggestionResult

Result of a moderation action on a suggestion.

suggestionId

string · uuid · required

ID of the moderated suggestion

action

string · enum · required

The moderation action that was taken

Enum values:

approve

reject

status

string · enum · required

Resulting status of the suggestion

Enum values:

merged

rejected

ModerationQueueItem

A single entry in the moderation queue.

object · required

A single consensus record representing the winning suggestion for a specific topic target within an entity.

alternativesCount

integer · required

Number of pending alternative suggestions

ModerationQueueResult

Paginated moderation queue response.

object[] · required

List of items pending moderation

nextToken

string

Opaque cursor for fetching the next page

ResolvePageData

Extended consensus page data returned by the slug resolver. Includes breadcrumb navigation in addition to entity, layout, and consensus data.

object · required

Lightweight entity metadata included in consensus page responses.

object[] · required

Layout template configuration for this entity

object · required

Map of topic keys to their consensus values

object[] · required

Breadcrumb navigation from root to this entity

computedAt

string · date-time · required

When the consensus was last computed

Entity

A content entry within a node. Entities hold structured content defined by their layout templates and populated by suggestions.

entityId

string · uuid · readOnly · required

Unique identifier, server-generated

nodeId

string · uuid · required

Parent node this entity belongs to

slug

string · pattern: ^[a-z0-9]+(?:-[a-z0-… · required

URL-safe identifier, unique within the parent node

slugPath

string · readOnly · required

Full hierarchical slug path from root

title

string · minLength: 1 · required

Human-readable display title

status

string · enum · required

Publication status of the entity

Enum values:

draft

published

archived

object[] · required

Content layout inherited from parent node templates

configVersion

integer · readOnly · required

Layout configuration version, incremented on refresh

createdAt

string · date-time · readOnly · required

ISO 8601 timestamp of creation

updatedAt

string · date-time · readOnly · required

ISO 8601 timestamp of last modification

object · required

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

object · required

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

EntityPage

Paginated list of entities.

object[] · required

Entities in this page

cursor

string | null

Opaque cursor for fetching the next page, null if last page

CreateEntityInput

Request body for creating a new entity. Validated against createEntitySchema in contracts.

nodeId

string · uuid · required

Parent node ID to create the entity under

slug

string · minLength: 1 · pattern: ^[a-z0-9]+(?:-[a-z0-… · required

URL-safe identifier, must be unique within the node

title

string · minLength: 1 · required

Human-readable display title

status

string · enum

Initial publication status

Enum values:

draft

published

archived

Default: draft

UpdateEntityInput

Request body for updating an entity. The entityId is taken from the URL path, not the request body.

title

string · minLength: 1 · required

New display title

status

string · enum · required

New publication status

Enum values:

draft

published

archived

RefreshLayoutResult

Result of refreshing an entity's layout from its parent node.

entityId

string · uuid · required

Entity that was refreshed

refreshed

boolean · required

Whether the layout actually changed

configVersion

integer · required

New configuration version after refresh

PresignRequest

Request body for generating an S3 presigned upload URL.

entityId

string · minLength: 1 · required

Entity the image is associated with

topicKey

string · minLength: 1 · required

Topic key the image belongs to

contentType

string · enum · required

MIME type of the image to upload

Enum values:

image/jpeg

image/png

image/webp

itemKey

string | null · minLength: 1

Optional item key for collection-type topics

PresignResponse

Presigned URL details for uploading an image to S3.

uploadUrl

string · uri · required

S3 presigned URL for PUT upload

imageUrl

string · uri · required

Final public URL where the image will be accessible

uploadId

string · required

Unique identifier for this upload operation

Node

A node in the taxonomy tree. Nodes form a hierarchical structure of categories and subcategories. Leaf nodes of kind "entity" hold content entries.

id

string · uuid · readOnly · required

Unique identifier, server-generated

treeId

string · readOnly · required

Tree partition identifier

slug

string · minLength: 1 · required

URL-safe identifier, unique among siblings

slugPath

string · readOnly · required

Full hierarchical slug path from root

path

string · readOnly · required

Materialized path from root hierarchy

title

string · minLength: 1 · required

Human-readable display title

nodeKind

string · enum · required

Whether this node is a category folder or an entity leaf

Enum values:

folder

entity

status

string · enum · required

Publication status of the node

Enum values:

draft

published

archived

depth

integer · min: 0 · readOnly · required

Depth in the tree (0 = root)

childCount

integer · min: 0 · readOnly · required

Number of direct children

createdAt

string · date-time · readOnly · required

ISO 8601 timestamp of creation

updatedAt

string · date-time · readOnly · required

ISO 8601 timestamp of last modification

object · required

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

object · required

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

parentId

string | null · uuid · readOnly

Parent node ID, null for root nodes

object | null

Optional structured content associated with the node

object[]

Layout templates that child entities inherit

configVersion

integer · readOnly

Template configuration version

NodePage

Paginated list of nodes.

object[] · required

Nodes in this page

cursor

string | null

Opaque cursor for fetching the next page, null if last page

CreateNodeInput

Request body for creating a new node. Provide either parentId or parentSlugPath to specify the parent. Omit both for root nodes.

slug

string · minLength: 1 · required

URL-safe identifier, must be unique among siblings

title

string · minLength: 1 · required

Human-readable display title

nodeKind

string · enum · required

Whether this node is a category folder or entity leaf

Enum values:

folder

entity

parentSlugPath

string

Slug path of the parent node (alternative to parentId)

parentId

string · uuid

UUID of the parent node (alternative to parentSlugPath)

object | null

Optional structured content

status

string · enum

Initial publication status

Enum values:

draft

published

archived

sortOrder

integer

Optional sort order among siblings

UpdateNodeTemplatesInput

Request body for updating a node's layout templates. The nodeId must match the URL path parameter.

nodeId

string · uuid · required

Node ID (must match the URL path parameter)

object[] · required

Array of template definitions to set on the node

RuleEntity

A full rule definition including its JSON Schema body and metadata. Returned by GET and create/update operations.

componentKey

string · required

Unique key identifying this rule within its folder

object · required

JSON Schema object defining the validation rule

deprecated

boolean · required

Whether this rule has been deprecated

createdAt

string · date-time · readOnly · required

When this rule was created

etag

string · readOnly · required

Entity tag for optimistic concurrency control

RuleSummary

Lightweight rule metadata returned in folder listing. Does not include the full schema body.

folder

string · required

Folder this rule belongs to

componentKey

string · required

Unique key identifying this rule

deprecated

boolean · required

Whether this rule has been deprecated

createdAt

string · date-time

When this rule was created

object

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

updatedAt

string · date-time

When this rule was last updated

object

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

label

string

Optional human-readable label

CreateRuleBody

Request body for creating or updating a rule. The schemaJson field must be a valid JSON string.

schemaJson

string · required

Valid JSON string representing the rule's JSON Schema

Suggestion

A user-submitted content proposal targeting a specific topic within an entity. Part of the Write path — suggestions compete via community voting to become consensus.

suggestionId

string · uuid · readOnly · required

Unique identifier, server-generated

authorId

string · uuid · readOnly · required

User ID of the suggestion author

entityId

string · uuid · required

Entity this suggestion targets

nodeId

string · uuid · readOnly · required

Node the target entity belongs to

topicKey

string · required

Topic slot this suggestion fills

ruleKey

string · readOnly · required

JSON Schema rule key used to validate this suggestion

operation

string · enum · required

The type of content operation this suggestion proposes

Enum values:

SET

ADD

UPDATE

DELETE

value

required

The proposed content value. Shape is validated against the topic's JSON Schema rule.

status

string · enum · required

Current lifecycle status of the suggestion

Enum values:

active

rejected

merged

spam

deleted

score

integer · readOnly · required

Net vote score (upvotes minus downvotes)

upvotes

integer · readOnly · required

Total number of upvotes

downvotes

integer · readOnly · required

Total number of downvotes

createdAt

string · date-time · readOnly · required

ISO 8601 timestamp of creation

updatedAt

string · date-time · readOnly · required

ISO 8601 timestamp of last modification

object · required

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

object · required

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

itemKey

string | null

Item key for collection-type topics, null for single topics

deletedAt

string · date-time · readOnly

ISO 8601 timestamp of soft-deletion, if applicable

object

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

SuggestionPage

Paginated list of suggestions.

object[] · required

Suggestions in this page

cursor

string | null

Opaque cursor for fetching the next page, null if last page

CreateSuggestionInput

Request body for creating a new suggestion. The value payload is validated against the topic's JSON Schema rule.

entityId

string · minLength: 1 · required

Entity to submit the suggestion for

topicKey

string · minLength: 1 · required

Topic key this suggestion targets

operation

string · enum · required

The type of content operation

Enum values:

SET

ADD

UPDATE

DELETE

value

required

The proposed content value

itemKey

string | null · minLength: 1

Optional item key for collection-type topics

UpdateSuggestionInput

Request body for updating a suggestion. Both fields are optional but at least one must be provided. The suggestionId is taken from the URL path.

value

Updated content value

status

string · enum

Updated suggestion status

Enum values:

active

rejected

merged

spam

deleted

UserProfile

Public user profile. Email is always omitted from API responses to protect user privacy.

userId

string · uuid · readOnly · required

Unique identifier, server-generated

username

string · required

Display username

rank

string · enum · required

User rank based on contribution level

Enum values:

BEGINNER

NOVICE

ADEPT

EXPERT

MASTER

isActive

boolean · required

Whether the user account is active

createdAt

string · date-time · readOnly · required

ISO 8601 timestamp of account creation

updatedAt

string · date-time · readOnly · required

ISO 8601 timestamp of last profile update

photoUrl

string | null

URL to the user's avatar image

bio

string | null

User's bio or description

UserPage

Paginated list of user profiles.

object[] · required

User profiles in this page

cursor

string | null

Opaque cursor for fetching the next page, null if last page

CastVoteInput

Request body for casting a vote on a suggestion. Value 1 is upvote, -1 is downvote, 0 removes a previous vote.

suggestionId

string · minLength: 1 · required

ID of the suggestion to vote on

value

integer · enum · required

Vote value: 1 (upvote), 0 (remove), -1 (downvote)

Enum values:

-1

VoteDelta

Updated vote tallies returned after casting a vote. Reflects the new totals for the target suggestion.

score

integer · required

Net vote score (upvotes minus downvotes)

upvotes

integer · required

Total number of upvotes

downvotes

integer · required

Total number of downvotes

VoteMap

Map of the authenticated user's votes. Keys are suggestion IDs, values are vote values (1, 0, or -1).

object · required

Map of suggestionId to vote value

MinMaxHub API

Schemas

Download schema

ApiEnvelope

Standard response envelope wrapping all API responses. Every response includes a trace ID for debugging, a machine-readable status, and a human-readable message.

status

string · enum · required

Machine-readable status code

Enum values:

CREATED

ACCEPTED

NO_CONTENT

BAD_REQUEST

UNAUTHORIZED

FORBIDDEN

NOT_FOUND

message

string · required

Human-readable status message

traceId

string

Unique request trace ID for debugging and log correlation

Error

Standard error response envelope. All API errors follow this shape. The status field maps to AppError codes in the Lambda layer.

status

string · enum · required

Machine-readable error code

Enum values:

BAD_REQUEST

UNAUTHORIZED

FORBIDDEN

NOT_FOUND

CONFLICT

UNPROCESSABLE_ENTITY

ERROR

message

string · required

Human-readable error description

traceId

string

Request trace ID for debugging and log correlation

UserSummary

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

userId

string · uuid · required

Unique identifier of the user

username

string · required

Display username

photoUrl

string | null

URL to the user's avatar image

BreadcrumbItem

A single breadcrumb navigation entry with label and link.

label

string · required

Display text for the breadcrumb link

href

string · required

Relative URL path for the breadcrumb

CollectionItemDef

Definition for a single item within a collections-type template slot. Specifies the item key, display label, and optional defaults.

itemKey

string · minLength: 1 · required

Unique key identifying this item within the collection

label

string · minLength: 1 · required

Human-readable label for this collection item

object

Default field values pre-populated for new suggestions

lockedFields

string[]

Field keys that cannot be modified by suggestions

EntityLayoutTemplate

Defines a content slot in an entity's layout. Templates are inherited from the parent node and determine what topics appear on the entity page.

topicKey

string · minLength: 1 · required

Unique key identifying this topic slot

component

string · minLength: 1 · required

React component key used to render this template section

title

string · minLength: 1 · required

Display title for this template section

kind

string · enum · required

Whether this slot holds a single value or a collection of items

Enum values:

single

collections

order

integer · min: 0 · required

Display order (lower numbers appear first)

object

Optional hero image for this template section

collectionMode

string · enum

Display mode for collections-type templates

Enum values:

expandable

closed

rule

string · minLength: 1

JSON Schema rule key for validating suggestion values

object[]

Pre-defined items within a collections-type template

ComputeConsensusResult

Summary of a consensus computation run.

entityId

string · uuid · required

Entity that was recomputed

targetsProcessed

integer · required

Number of topic targets evaluated

winnersUpdated

integer · required

Number of winners that changed during this computation

computedAt

string · date-time · required

Timestamp of the computation

ConsensusItem

A single consensus record representing the winning suggestion for a specific topic target within an entity.

entityId

string · uuid · required

Entity this consensus belongs to

topicKey

string · required

Topic key this consensus covers

value

required

The winning suggestion's value payload

confidence

number · required

Confidence score (0-1) based on vote distribution

upvotes

integer · required

Total upvotes for the winning suggestion

downvotes

integer · required

Total downvotes for the winning suggestion

totalVotes

integer · required

Total number of votes cast

computedAt

string · date-time · readOnly · required

When this consensus was last computed

createdAt

string · date-time · readOnly · required

When this consensus record was first created

updatedAt

string · date-time · readOnly · required

When this consensus record was last updated

itemKey

string | null

Item key for collection-type topics, null for single topics

winningSuggestionId

string | null · uuid

ID of the suggestion that won consensus, null if no winner

authorId

string

User ID of the winning suggestion's author

authorUsername

string

Username of the winning suggestion's author

authorPhotoUrl

string

Avatar URL of the winning suggestion's author

ConsensusPageEntity

Lightweight entity metadata included in consensus page responses.

entityId

string · uuid · required

Unique identifier of the entity

nodeId

string · uuid · required

Parent node identifier

title

string · required

Display title

slug

string · required

URL-safe slug

slugPath

string · required

Full hierarchical slug path

ConsensusPageData

Full consensus page payload for SSR rendering. Contains entity metadata, layout configuration, and all computed consensus values.

object · required

Lightweight entity metadata included in consensus page responses.

object[] · required

Layout template configuration for this entity

object · required

Map of topic keys to their consensus values

computedAt

string · date-time · required

When the consensus was last computed

ModerateSuggestionInput

Request body for moderating a suggestion.

action

string · enum · required

Moderation action to take

Enum values:

approve

reject

reason

string

Optional reason for the moderation decision

ModerateSuggestionResult

Result of a moderation action on a suggestion.

suggestionId

string · uuid · required

ID of the moderated suggestion

action

string · enum · required

The moderation action that was taken

Enum values:

approve

reject

status

string · enum · required

Resulting status of the suggestion

Enum values:

merged

rejected

ModerationQueueItem

A single entry in the moderation queue.

object · required

A single consensus record representing the winning suggestion for a specific topic target within an entity.

alternativesCount

integer · required

Number of pending alternative suggestions

ModerationQueueResult

Paginated moderation queue response.

object[] · required

List of items pending moderation

nextToken

string

Opaque cursor for fetching the next page

ResolvePageData

Extended consensus page data returned by the slug resolver. Includes breadcrumb navigation in addition to entity, layout, and consensus data.

object · required

Lightweight entity metadata included in consensus page responses.

object[] · required

Layout template configuration for this entity

object · required

Map of topic keys to their consensus values

object[] · required

Breadcrumb navigation from root to this entity

computedAt

string · date-time · required

When the consensus was last computed

Entity

A content entry within a node. Entities hold structured content defined by their layout templates and populated by suggestions.

entityId

string · uuid · readOnly · required

Unique identifier, server-generated

nodeId

string · uuid · required

Parent node this entity belongs to

slug

string · pattern: ^[a-z0-9]+(?:-[a-z0-… · required

URL-safe identifier, unique within the parent node

slugPath

string · readOnly · required

Full hierarchical slug path from root

title

string · minLength: 1 · required

Human-readable display title

status

string · enum · required

Publication status of the entity

Enum values:

draft

published

archived

object[] · required

Content layout inherited from parent node templates

configVersion

integer · readOnly · required

Layout configuration version, incremented on refresh

createdAt

string · date-time · readOnly · required

ISO 8601 timestamp of creation

updatedAt

string · date-time · readOnly · required

ISO 8601 timestamp of last modification

object · required

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

object · required

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

EntityPage

Paginated list of entities.

object[] · required

Entities in this page

cursor

string | null

Opaque cursor for fetching the next page, null if last page

CreateEntityInput

Request body for creating a new entity. Validated against createEntitySchema in contracts.

nodeId

string · uuid · required

Parent node ID to create the entity under

slug

string · minLength: 1 · pattern: ^[a-z0-9]+(?:-[a-z0-… · required

URL-safe identifier, must be unique within the node

title

string · minLength: 1 · required

Human-readable display title

status

string · enum

Initial publication status

Enum values:

draft

published

archived

Default: draft

UpdateEntityInput

Request body for updating an entity. The entityId is taken from the URL path, not the request body.

title

string · minLength: 1 · required

New display title

status

string · enum · required

New publication status

Enum values:

draft

published

archived

RefreshLayoutResult

Result of refreshing an entity's layout from its parent node.

entityId

string · uuid · required

Entity that was refreshed

refreshed

boolean · required

Whether the layout actually changed

configVersion

integer · required

New configuration version after refresh

PresignRequest

Request body for generating an S3 presigned upload URL.

entityId

string · minLength: 1 · required

Entity the image is associated with

topicKey

string · minLength: 1 · required

Topic key the image belongs to

contentType

string · enum · required

MIME type of the image to upload

Enum values:

image/jpeg

image/png

image/webp

itemKey

string | null · minLength: 1

Optional item key for collection-type topics

PresignResponse

Presigned URL details for uploading an image to S3.

uploadUrl

string · uri · required

S3 presigned URL for PUT upload

imageUrl

string · uri · required

Final public URL where the image will be accessible

uploadId

string · required

Unique identifier for this upload operation

Node

A node in the taxonomy tree. Nodes form a hierarchical structure of categories and subcategories. Leaf nodes of kind "entity" hold content entries.

id

string · uuid · readOnly · required

Unique identifier, server-generated

treeId

string · readOnly · required

Tree partition identifier

slug

string · minLength: 1 · required

URL-safe identifier, unique among siblings

slugPath

string · readOnly · required

Full hierarchical slug path from root

path

string · readOnly · required

Materialized path from root hierarchy

title

string · minLength: 1 · required

Human-readable display title

nodeKind

string · enum · required

Whether this node is a category folder or an entity leaf

Enum values:

folder

entity

status

string · enum · required

Publication status of the node

Enum values:

draft

published

archived

depth

integer · min: 0 · readOnly · required

Depth in the tree (0 = root)

childCount

integer · min: 0 · readOnly · required

Number of direct children

createdAt

string · date-time · readOnly · required

ISO 8601 timestamp of creation

updatedAt

string · date-time · readOnly · required

ISO 8601 timestamp of last modification

object · required

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

object · required

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

parentId

string | null · uuid · readOnly

Parent node ID, null for root nodes

object | null

Optional structured content associated with the node

object[]

Layout templates that child entities inherit

configVersion

integer · readOnly

Template configuration version

NodePage

Paginated list of nodes.

object[] · required

Nodes in this page

cursor

string | null

Opaque cursor for fetching the next page, null if last page

CreateNodeInput

Request body for creating a new node. Provide either parentId or parentSlugPath to specify the parent. Omit both for root nodes.

slug

string · minLength: 1 · required

URL-safe identifier, must be unique among siblings

title

string · minLength: 1 · required

Human-readable display title

nodeKind

string · enum · required

Whether this node is a category folder or entity leaf

Enum values:

folder

entity

parentSlugPath

string

Slug path of the parent node (alternative to parentId)

parentId

string · uuid

UUID of the parent node (alternative to parentSlugPath)

object | null

Optional structured content

status

string · enum

Initial publication status

Enum values:

draft

published

archived

sortOrder

integer

Optional sort order among siblings

UpdateNodeTemplatesInput

Request body for updating a node's layout templates. The nodeId must match the URL path parameter.

nodeId

string · uuid · required

Node ID (must match the URL path parameter)

object[] · required

Array of template definitions to set on the node

RuleEntity

A full rule definition including its JSON Schema body and metadata. Returned by GET and create/update operations.

componentKey

string · required

Unique key identifying this rule within its folder

object · required

JSON Schema object defining the validation rule

deprecated

boolean · required

Whether this rule has been deprecated

createdAt

string · date-time · readOnly · required

When this rule was created

etag

string · readOnly · required

Entity tag for optimistic concurrency control

RuleSummary

Lightweight rule metadata returned in folder listing. Does not include the full schema body.

folder

string · required

Folder this rule belongs to

componentKey

string · required

Unique key identifying this rule

deprecated

boolean · required

Whether this rule has been deprecated

createdAt

string · date-time

When this rule was created

object

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

updatedAt

string · date-time

When this rule was last updated

object

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

label

string

Optional human-readable label

CreateRuleBody

Request body for creating or updating a rule. The schemaJson field must be a valid JSON string.

schemaJson

string · required

Valid JSON string representing the rule's JSON Schema

Suggestion

A user-submitted content proposal targeting a specific topic within an entity. Part of the Write path — suggestions compete via community voting to become consensus.

suggestionId

string · uuid · readOnly · required

Unique identifier, server-generated

authorId

string · uuid · readOnly · required

User ID of the suggestion author

entityId

string · uuid · required

Entity this suggestion targets

nodeId

string · uuid · readOnly · required

Node the target entity belongs to

topicKey

string · required

Topic slot this suggestion fills

ruleKey

string · readOnly · required

JSON Schema rule key used to validate this suggestion

operation

string · enum · required

The type of content operation this suggestion proposes

Enum values:

SET

ADD

UPDATE

DELETE

value

required

The proposed content value. Shape is validated against the topic's JSON Schema rule.

status

string · enum · required

Current lifecycle status of the suggestion

Enum values:

active

rejected

merged

spam

deleted

score

integer · readOnly · required

Net vote score (upvotes minus downvotes)

upvotes

integer · readOnly · required

Total number of upvotes

downvotes

integer · readOnly · required

Total number of downvotes

createdAt

string · date-time · readOnly · required

ISO 8601 timestamp of creation

updatedAt

string · date-time · readOnly · required

ISO 8601 timestamp of last modification

object · required

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

object · required

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

itemKey

string | null

Item key for collection-type topics, null for single topics

deletedAt

string · date-time · readOnly

ISO 8601 timestamp of soft-deletion, if applicable

object

Lightweight user reference embedded in created/updated metadata. Contains only public profile fields — never includes email.

SuggestionPage

Paginated list of suggestions.

object[] · required

Suggestions in this page

cursor

string | null

Opaque cursor for fetching the next page, null if last page

CreateSuggestionInput

Request body for creating a new suggestion. The value payload is validated against the topic's JSON Schema rule.

entityId

string · minLength: 1 · required

Entity to submit the suggestion for

topicKey

string · minLength: 1 · required

Topic key this suggestion targets

operation

string · enum · required

The type of content operation

Enum values:

SET

ADD

UPDATE

DELETE

value

required

The proposed content value

itemKey

string | null · minLength: 1

Optional item key for collection-type topics

UpdateSuggestionInput

Request body for updating a suggestion. Both fields are optional but at least one must be provided. The suggestionId is taken from the URL path.

value

Updated content value

status

string · enum

Updated suggestion status

Enum values:

active

rejected

merged

spam

deleted

UserProfile

Public user profile. Email is always omitted from API responses to protect user privacy.

userId

string · uuid · readOnly · required

Unique identifier, server-generated

username

string · required

Display username

rank

string · enum · required

User rank based on contribution level

Enum values:

BEGINNER

NOVICE

ADEPT

EXPERT

MASTER

isActive

boolean · required

Whether the user account is active

createdAt

string · date-time · readOnly · required

ISO 8601 timestamp of account creation

updatedAt

string · date-time · readOnly · required

ISO 8601 timestamp of last profile update

photoUrl

string | null

URL to the user's avatar image

bio

string | null

User's bio or description

UserPage

Paginated list of user profiles.

object[] · required

User profiles in this page

cursor

string | null

Opaque cursor for fetching the next page, null if last page

CastVoteInput

Request body for casting a vote on a suggestion. Value 1 is upvote, -1 is downvote, 0 removes a previous vote.

suggestionId

string · minLength: 1 · required

ID of the suggestion to vote on

value

integer · enum · required

Vote value: 1 (upvote), 0 (remove), -1 (downvote)

Enum values:

-1

VoteDelta

Updated vote tallies returned after casting a vote. Reflects the new totals for the target suggestion.

score

integer · required

Net vote score (upvotes minus downvotes)

upvotes

integer · required

Total number of upvotes

downvotes

integer · required

Total number of downvotes

VoteMap

Map of the authenticated user's votes. Keys are suggestion IDs, values are vote values (1, 0, or -1).

object · required

Map of suggestionId to vote value