User-submitted content proposals (Write path). Each suggestion targets a specific topic within an entity and carries a value payload.
Create a new content suggestion
Submits a content suggestion for a specific topic within an entity. The value payload is validated against the topic's JSON Schema rule (schema-on-write). The suggestion enters the Write path for community voting. Requires authentication.
Create a new content suggestion › Request Body
entityIdEntity to submit the suggestion for
topicKeyTopic key this suggestion targets
operationThe type of content operation
valueThe proposed content value
itemKeyOptional item key for collection-type topics
Create a new content suggestion › Responses
Suggestion created successfully
statusMachine-readable status code
messageHuman-readable status message
traceIdUnique request trace ID for debugging and log correlation
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.
Get a suggestion by its unique identifier
Retrieves a single suggestion including its value payload, vote counts, and metadata. No authentication required.
path Parameters
idUnique identifier of the suggestion
Get a suggestion by its unique identifier › Responses
Suggestion retrieved successfully
statusMachine-readable status code
messageHuman-readable status message
traceIdUnique request trace ID for debugging and log correlation
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.
Soft-delete a suggestion
Marks a suggestion as deleted. Only the original author can delete their own suggestions. The suggestion remains in the database but is excluded from consensus computation. Requires authentication.
path Parameters
idUnique identifier of the suggestion to delete
Soft-delete a suggestion › Responses
Suggestion deleted successfully
statusMachine-readable status code
messageHuman-readable status message
traceIdUnique request trace ID for debugging and log correlation
dataUpdate a suggestion's value or status
Updates an existing suggestion. Only the original author can update the value. Moderators can change the status via consensus moderation. The suggestionId is taken from the URL path, not the request body. Requires authentication.
path Parameters
idUnique identifier of the suggestion to update
Update a suggestion's value or status › Request Body
valueUpdated content value
statusUpdated suggestion status
Update a suggestion's value or status › Responses
Suggestion updated successfully
statusMachine-readable status code
messageHuman-readable status message
traceIdUnique request trace ID for debugging and log correlation
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.
List suggestions by a specific author
Returns a paginated list of suggestions created by the specified author. Requires authentication.
path Parameters
idUnique identifier of the author (userId)
query Parameters
limitMaximum number of items to return per page
nextTokenOpaque cursor from a previous response for pagination
List suggestions by a specific author › Responses
Suggestions retrieved successfully
statusMachine-readable status code
messageHuman-readable status message
traceIdUnique request trace ID for debugging and log correlation
Paginated list of suggestions.
List suggestions for a specific entity
Returns a paginated list of suggestions targeting the specified entity, across all topics. No authentication required.
path Parameters
idUnique identifier of the entity
query Parameters
limitMaximum number of items to return per page
nextTokenOpaque cursor from a previous response for pagination
List suggestions for a specific entity › Responses
Suggestions retrieved successfully
statusMachine-readable status code
messageHuman-readable status message
traceIdUnique request trace ID for debugging and log correlation
Paginated list of suggestions.
List suggestions by target (entity + topic + item)
Returns a paginated list of suggestions filtered by entity, topic key, and optionally item key. Used to show all competing suggestions for a specific content slot. Requires authentication.
query Parameters
entityIdEntity to filter suggestions for
topicKeyTopic key to filter suggestions for
itemKeyOptional item key for collection-type topics
limitMaximum number of items to return per page
nextTokenOpaque cursor from a previous response for pagination
List suggestions by target (entity + topic + item) › Responses
Suggestions retrieved successfully
statusMachine-readable status code
messageHuman-readable status message
traceIdUnique request trace ID for debugging and log correlation
Paginated list of suggestions.