Node API

Moera Node API is a JSON-based REST API. See introduction to Node REST API in the Overview section.

Timestamp below is the number of seconds that passed since 01-01-1970 00:00:00 in UTC timezone.

If an error occurs when processing a API request, Result structure is returned instead of the regular response. The structure contains the error code and message, and also the HTTP status code is set accordingly. All error codes are case-insensitive.

An error may occur on different stages of request processing.

  • If the request URL is unknown, not-found error is returned.
  • If the request Content-Type is unknown, invalid-content-type error is returned.
  • If incorrect JSON is provided, invalid-syntax error is returned.
  • If value of one of the arguments does not correspond its type, invalid-argument-value error is returned.
  • If authentication is required, but not provided, authentication.required error is returned.
  • If invalid authentication token or root secret is provided, authentication.invalid error is returned.
  • If the provided signature is incorrect, authentication.incorrect-signature error is returned.
  • If the provided carte is incorrect, one of the following error codes is returned:
    • carte.client-address-unknown - cannot determine client IP address;
    • carte.unknown-fingerprint - unknown fingerprint version encoded in the carte;
    • carte.invalid - the carte format is invalid;
    • carte.not-begun - the timespan of the carte has not begun yet;
    • carte.expired - the carte is expired;
    • carte.unknown-signing-key - cannot find public key for carte owner;
    • carte.invalid-signature - carte signature is invalid.
  • If the request needs a node name, but it is not defined, node-name-not-set error is returned.
  • If the request needs a signing key, but it is not defined, signing-key-not-set error is returned.
  • If request body does not pass validation, a validation error is returned. Look into the chapter on the particular structure for the list of validation errors that correspond to the structure.
  • If an error occurs while executing the operation, one of the errors listed in the corresponding operation's chapter is returned.
  • If a configuration error or a software bug occurs, server.misconfiguration error is returned.
  • If request processing involves a naming server, but it is not available, naming.not-available error is returned.

Authentication scheme, if specified in the request description, may be one of the following:

  • none or not present - authentication is not required;
  • root secret - Authorization: bearer secret:<token> header must be provided with <token> equal to the secret value set in the node configuration;
  • admin - admin token received after signing in must be passed in header Authorization: bearer [token:]<token>;
  • owner - only the owner of the content (posting, comment etc.) may perform this request, use admin token (for own content on the home node only), carte (passed in header Authorization: bearer carte:<token>) or signature (if present in the input) for authentication.
  • configurable - access to the request is configurable, the client may refer to the corresponding access hint to clarify and use token, carte or signature for authentication.

Standard permission groups are:

  • admin - administrator of the node;
  • owner - owner of the posting, comment etc.;
  • public - anybody.

cid parameter may be passed with any request. See Events page for the description of its purpose.

Table of Contents

  1. Activity Reactions object
  2. Asyncronous Operations object
  3. Cartes object
  4. Comments object
  5. Comment Revisions object
  6. Comment Reactions object
  7. Comment Reaction Totals object
  8. Contacts object
  9. Credentials object
  10. Deleted Postings object
  11. Deleted Posting Revisions object
  12. Domains object
  13. Draft Postings object
  14. Feeds object
  15. Node Name object
  16. Notifications object
  17. People object
  18. Postings object
  19. Posting Revisions object
  20. Posting Draft Revision object
  21. Posting Reactions object
  22. Posting Reaction Totals object
  23. Profile object
  24. Remote Comments object
  25. Remote Postings object
  26. Remote Posting Reactions object
  27. Settings object
  28. Stories object
  29. Subscribers object
  30. Subscriptions object
  31. Tokens object
  32. Web Push object
  33. Who Am I object
  34. Structures

Activity Reactions object

Local registry of all activity in the form of reactions performed by the node.

GET /activity/reactions/search

Get the list of all reactions performed by the node, filtered by some criteria.

Request body:
ActivityReactionFilter
Response:
ActivityReactionInfo[]
Authentication (read more):
admin
Name and signing key:
not required

Asyncronous Operations object

Asyncronous operations pending or just finished on the node.

GET /async-operations/remote-posting-verification/{id}

Get status of the asyncronous operation that performs verification of a remote posting signature.

Parameters:
String id - asynchronous operation ID
Response:
RemotePostingVerificationInfo
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
async-operation.not-found async operation with the given ID is not found

GET /async-operations/remote-reaction-verification/{id}

Get status of the asyncronous operation that performs verification of the signature of a reaction to a remote posting.

Parameters:
String id - asynchronous operation ID
Response:
RemoteReactionVerificationInfo
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
async-operation.not-found async operation with the given ID is not found

Cartes object

Cartes - cryptographic tokens used for authentication on any node besides the home node.

GET /cartes

Get a set of cartes that correspond to successive periods of time. The node may decide to return less cartes than the given limit.

Parameters:
int limit - maximum number of cartes returned
Response:
CarteSet
Authentication (read more):
admin
Name and signing key:
required

Comments object

Comments to a posting.

GET /postings/{postingId}/comments

Get a slice of the list of comments, delimited by before or after moments (but not both) and the given limit. If neither before nor after are provided, the latest comments are returned. The node may decide to return less comments than the given limit. The stories are always sorted by moment, ascending.

Parameters:
String postingId - ID of the posting
int before - filter comments posted at or before this moment
int after - filter comments posted strongly after this moment
int limit - maximum number of comments returned
Response:
CommentsSliceInfo
Authentication (read more):
none
Name and signing key:
not required
Errors:
Code Description
posting.not-found there is no posting with the given ID
comments.before-after-exclusive before and after parameters are not allowed together
limit.invalid limit parameter has an invalid value

POST /postings/{postingId}/comments

Create a comment from the given text and add it to the given posting. The comment owner must authenticate in some way. If the comment is not signed, it will be kept for a limited period of time and then erased.

Parameters:
String postingId - ID of the posting
Request body:
CommentText
Response:
CommentCreated
Authentication (read more):
owner
Name and signing key:
not required
Errors:
Code Description
posting.not-found there is no posting with the given ID

GET /postings/{postingId}/comments/{commentId}

Get an individual comment.

Parameters:
String postingId - ID of the posting
String commentId - ID of the comment
String include - Comma-separated list of additional blocks of information that are needed. The values are:
  • source - source text of the comment.
Response:
CommentInfo
Authentication (read more):
none
Name and signing key:
not required
Errors:
Code Description
comment.not-found there is no comment with the given ID
comment.wrong-posting the comment is not related to the given posting

PUT /postings/{postingId}/comments/{commentId}

Update the comment, creating a new revision of it. The text is processed just like in the POST request.

Parameters:
String postingId - ID of the posting
String commentId - ID of the comment
Request body:
CommentText
Response:
CommentInfo
Authentication (read more):
owner
Name and signing key:
not required
Errors:
Code Description
comment.not-found there is no comment with the given ID
comment.wrong-posting the comment is not related to the given posting

DELETE /postings/{postingId}/comments/{commentId}

Delete the comment. The comment may not be purged from the database immediately, but preserved for some period of time to give a chance to restore it.

Parameters:
String postingId - ID of the posting
String commentId - ID of the comment
Response:
CommentTotalInfo
Authentication (read more):
admin or owner
Name and signing key:
not required
Errors:
Code Description
comment.not-found there is no comment with the given ID
comment.wrong-posting the comment is not related to the given posting

Comment Revisions object

All revisions of the comment.

GET /postings/{postingId}/comments/{commentId}/revisions

Get all revisions of the comment.

Parameters:
String postingId - ID of the posting
String commentId - ID of the comment
Response:
CommentRevisionInfo[]
Authentication (read more):
configurable
Name and signing key:
not required
Errors:
Code Description
comment.not-found there is no comment with the given ID
comment.wrong-posting the comment is not related to the given posting

GET /postings/{postingId}/comments/{commentId}/revisions/{id}

Get an individual revision of the comment.

Parameters:
String postingId - ID of the posting
String commentId - ID of the comment
String id - ID of the revision
Response:
CommentRevisionInfo
Authentication (read more):
configurable
Name and signing key:
not required
Errors:
Code Description
comment.not-found there is no comment with the given ID
comment.wrong-posting the comment is not related to the given posting
comment-revision.not-found there is no revision with the given ID

Comment Reactions object

Reactions ("Likes") - simple textless answers to a comment.

POST /postings/{postingId}/comments/{commentId}/reactions

Add a reaction to the given comment. The reaction owner must authenticate in some way. Only one reaction is allowed from each owner to a particular comment. If a reaction from the same owner to this comment already exists, it is overwritten. If the reaction is not signed, the reaction will be kept for a limited period of time and then erased (the previous reaction of the same owner will be restored, if any).

Parameters:
String postingId - ID of the posting
String commentId - ID of the comment
Request body:
ReactionDescription
Response:
ReactionCreated
Authentication (read more):
owner
Name and signing key:
not required
Errors:
Code Description
comment.not-found there is no comment with the given ID
comment.wrong-posting the comment is not related to the given posting
comment.not-signed cannot add a reaction to an unsigned comment
reaction.not-accepted the reaction is not acceptable

GET /postings/{postingId}/comments/{commentId}/reactions

Get a slice of the list of reactions to the given comment, optionally filtered by reaction type, delimited by before moment and the given limit. If before is not provided, the latest reactions are returned. The node may decide to return less reactions than the given limit. The reactions are always sorted by moment, descending.

Parameters:
String postingId - ID of the posting
String commentId - ID of the comment
boolean negative - true, to filter negative reactions, false, to filter positive ones
int emoji - filter by reaction code, usually interpreted by clients as emoji code point
int before - filter reactions created at or before this moment
int limit - maximum number of reactions returned
Response:
ReactionsSliceInfo
Authentication (read more):
none
Name and signing key:
not required
Errors:
Code Description
comment.not-found there is no comment with the given ID
comment.wrong-posting the comment is not related to the given posting
limit.invalid limit parameter has an invalid value

GET /postings/{postingId}/comments/{commentId}/reactions/{ownerName}

Get the detailed information about the reaction of the given owner to the given comment. If no reaction with such owner exist, an empty structure with just commentId is returned.

Parameters:
String postingId - ID of the posting
String commentId - ID of the comment
String ownerName - reaction owner node name
Response:
ReactionInfo
Authentication (read more):
none
Name and signing key:
not required
Errors:
Code Description
comment.not-found there is no comment with the given ID
comment.wrong-posting the comment is not related to the given posting

DELETE /postings/{postingId}/comments/{commentId}/reactions

Delete all reactions to the given comment.

Parameters:
String postingId - ID of the posting
String commentId - ID of the comment
Response:
Result
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
comment.not-found there is no comment with the given ID
comment.wrong-posting the comment is not related to the given posting

DELETE /postings/{postingId}/comments/{commentId}/reactions/{ownerName}

Delete the reaction of the given owner to the given comment.

Parameters:
String postingId - ID of the posting
String commentId - ID of the comment
String ownerName - reaction owner node name
Response:
ReactionTotalsInfo
Authentication (read more):
admin or owner
Name and signing key:
not required
Errors:
Code Description
comment.not-found there is no comment with the given ID
comment.wrong-posting the comment is not related to the given posting

Comment Reaction Totals object

Summary of reactions to a comment.

GET /postings/{postingId}/comments/{commentId}/reaction-totals

Get summary of reactions to the comment given.

Parameters:
String postingId - ID of the posting
String commentId - ID of the comment
Response:
ReactionTotalsInfo
Authentication (read more):
none
Name and signing key:
not required
Errors:
Code Description
comment.not-found there is no comment with the given ID
comment.wrong-posting the comment is not related to the given posting

Contacts object

Information about all nodes having a relationship with the node.

GET /contacts

Search for contacts matching the search query. Every space-delimited word in the query must case-insensitively match a beginning of the contact's node name or a beginning of any space-delimited word in the contact's full name. The order of words is not significant.

The node may decide to return less contacts than the given limit.

The contacts are sorted by their closeness to the node, which is calculated from the number of reactions and comments and their age.

Parameters:
String query - the search query
int limit - maximum number of contacts returned
Response:
ContactInfo[]
Authentication (read more):
none
Name and signing key:
not required
Errors:
Code Description
limit.invalid limit parameter has an invalid value

Credentials object

Credentials used to authenticate the administrator of the node.

GET /credentials

Check whether the credentials are initialized already.

Response:
CredentialsCreated
Authentication (read more):
none
Name and signing key:
not required

POST /credentials

Initialize credentials, if they are not set yet. Note that this operation can be executed without authentication, so this should be done as soon as possible after the node installation. Sign in is not allowed until the credentials are set.

Request body:
Credentials
Response:
Result
Authentication (read more):
none
Name and signing key:
not required
Errors:
Code Description
credentials.already-created credentials are already created

PUT /credentials

Update credentials. Either old password or credentials reset token should be set in the input for the operation to succeed. Credentials reset token is not related to the authentication token and usually is sent to the user by E-mail.

Request body:
CredentialsChange
Response:
Result
Authentication (read more):
none
Name and signing key:
not required
Errors:
Code Description
credentials.login-incorrect login incorrect (the old password is wrong)
credentials.wrong-reset-token credentials reset token is wrong
credentials.reset-token-expired credentials reset token is expired

DELETE /credentials

Delete credentials.

Response:
Result
Authentication (read more):
root secret
Name and signing key:
not required

POST /credentials/reset

The node generates credentials reset token that is sent to the node admin by E-mail or using any other way that is defined for credentials recovery. This token then may be used to change the credentials without knowing the password.

Response:
EmailHint
Authentication (read more):
none
Name and signing key:
not required
Errors:
Code Description
credentials.email-not-set E-mail address is not set for the node

Deleted Postings object

All deleted postings, that are not purged from the database yet.

GET /deleted-postings

Get the list of deleted postings, page by page. The node may decide to use smaller page size than the given limit. The postings are always sorted by the deletion timestamp, descending.

Parameters:
int page - page number, 0 by default
int limit - page size (maximum number of postings returned), the default is defined by the node
Response:
PostingInfo[]
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
page.invalid page parameter has an invalid value
limit.invalid limit parameter has an invalid value

GET /deleted-postings/{id}

Get an individual deleted posting.

Parameters:
String id - ID of the posting
Response:
PostingInfo
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
posting.not-found there is no deleted posting with the given ID

POST /deleted-postings/{id}/restore

Restore a posting. A new revision is created with the same content as in the latest revision.

Parameters:
String id - ID of the posting
Response:
PostingInfo
Authentication (read more):
admin
Name and signing key:
required
Errors:
Code Description
posting.not-found there is no posting with the given ID

Deleted Posting Revisions object

All revisions of the deleted posting. This object supports the same requests as Posting Revisions object, but uses /deleted-postings prefix instead of /postings.

Domains object

One instance of Moera node software can serve several virtual nodes. These virtual nodes are called domains and distinguished by the hostname passed in the HTTP request. Each virtual node has node ID, it is used in the database to designate the data that belongs to a particular node. The hostname is mapped to the node ID when the request is processed, using the list of registered domains. If there is no domain with such a name, the special _default_ domain is used.

GET /domains

Get the list of registered domains.

Response:
DomainInfo[]
Authentication (read more):
root secret
Name and signing key:
not required

GET /domains/{name}

Get information about the domain with the given hostname. If domain registration for this server is public, this request does not require authentication.

Parameters:
String name - domain name
Response:
DomainInfo
Authentication (read more):
root secret or none
Name and signing key:
not required
Errors:
Code Description
domain.not-found there is no domain with the given hostname

POST /domains

Create a new domain with the given hostname. If nodeId is not passed, it is generated automatically. If domain registration for this server is public, this request does not require authentication.

Request body:
DomainAttributes
Response:
DomainInfo
Authentication (read more):
root secret or none
Name and signing key:
not required
Errors:
Code Description
domain.already-exists a domain with the given hostname already exists
domain.node-id-used a domain with the given node ID already exists

PUT /domains/{name}

Update the domain with the given hostname. If the new hostname is not passed, the old hostname is preserved. (Note that you cannot pass a new name for the default hostname, because it cannot be renamed and _default_ is not a valid hostname. Skip this field if you want to update the default hostname.) If nodeId is not passed, it is generated automatically.

Parameters:
String name - domain's hostname
Request body:
DomainAttributes
Response:
DomainInfo
Authentication (read more):
root secret
Name and signing key:
not required
Errors:
Code Description
domain.not-found there is no domain with the given hostname
domain.cannot-rename-default cannot change the name of the default domain

DELETE /domains/{name}

Delete the domain with the given hostname. This operation deletes the domain record only, the user's data related to the domain is preserved.

Parameters:
String name - domain name
Response:
Result
Authentication (read more):
root secret
Name and signing key:
not required
Errors:
Code Description
domain.not-found there is no domain with the given hostname
domain.cannot-delete-default cannot delete the default domain

GET /domains/available

Get an available domain name that is recommended for the given node name. The domain name is usually chosen to be close to the node name in English transcription. If domain registration for this server is not public, this request is not accessible.

Parameters:
String nodeName - node name
Response:
DomainAvailable
Authentication (read more):
none
Name and signing key:
not required

Draft Postings object

All draft postings.

GET /draft-postings

Get the list of draft postings, page by page. The node may decide to use smaller page size than the given limit. The postings are always sorted by the creation timestamp, descending.

Parameters:
int page - page number, 0 by default
int limit - page size (maximum number of postings returned), the default is defined by the node
Response:
PostingInfo[]
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
page.invalid page parameter has an invalid value
limit.invalid limit parameter has an invalid value

POST /draft-postings

Create a new draft posting from the text given.

Request body:
PostingText
Response:
PostingInfo
Authentication (read more):
admin
Name and signing key:
required

GET /draft-postings/{id}

Get an individual draft posting.

Parameters:
String id - ID of the posting
Response:
PostingInfo
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
posting.not-found there is no draft posting with the given ID

PUT /draft-postings/{id}

Update the draft posting, overwriting the current revision of it.

Parameters:
String id - ID of the draft posting
Request body:
PostingText
Response:
PostingInfo
Authentication (read more):
admin
Name and signing key:
required
Errors:
Code Description
posting.not-found there is no draft posting with the given ID

DELETE /draft-postings/{id}

Delete the draft posting. The posting may not be purged from the database immediately, but preserved for some period of time to give a chance to restore it.

Parameters:
String id - ID of the draft posting
Response:
Result
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
posting.not-found there is no draft posting with the given ID

Feeds object

Feed is a set of stories collected for some purpose. The stories are sorted by moment, descending.

These are the standard feeds that have special meaning:

  • timeline - the main feed of publications;
  • instant - the feed of instant notifications;
  • news - the main feed of publications gathered from other nodes.

GET /feeds

Get general information about all feeds accessible by client.

Response:
FeedInfo[]
Authentication (read more):
none
Name and signing key:
not required

GET /feeds/{feedName}

Get general information about the feed.

Parameters:
String feedName - name of the feed
Response:
FeedInfo
Authentication (read more):
none
Name and signing key:
not required
Errors:
Code Description
feed.not-found there is no accessible feed with this name

GET /feeds/{feedName}/status

Get information about non-read and non-viewed stories in the feed.

Parameters:
String feedName - name of the feed
Response:
FeedStatus
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
feed.not-found there is no accessible feed with this name

PUT /feeds/{feedName}/status

Update information about non-read and non-viewed stories in the feed.

Parameters:
String feedName - name of the feed
Request body:
FeedStatusChange
Response:
FeedStatus
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
feed.not-found there is no accessible feed with this name

GET /feeds/{feedName}/stories

Get a slice of the feed, delimited by before or after moments (but not both) and the given limit. If neither before nor after are provided, the latest stories are returned. The node may decide to return less stories than the given limit. The stories are always sorted by moment, descending.

Parameters:
String feedName - name of the feed
int before - filter stories posted at or before this moment
int after - filter stories posted strongly after this moment
int limit - maximum number of stories returned
Response:
FeedSliceInfo
Authentication (read more):
none
Name and signing key:
not required
Errors:
Code Description
feed.not-found there is no accessible feed with this name
feed.before-after-exclusive before and after parameters are not allowed together
limit.invalid limit parameter has an invalid value

Node Name object

The name of the node. Read more about it in the Overview section. Operations with the node name are performed asynchronously - need to poll the node periodically to get the current status of the operation. Only one operation with the node name may be performed by the node at any moment.

GET /node-name

Get the name of the node. Admin user receives also the current status of the latest operation with the node name.

Response:
NodeNameInfo
Authentication (read more):
none
Name and signing key:
not required

POST /node-name

Register a new name for the node. The corresponding signing key is generated automatically and stored at the node. The updating key is generated and returned in the encoded form and in the form of mnemonic (a sequence of English words) that need to be written down and stored securely to be able to perform further operations with the name.

Request body:
NameToRegister
Response:
RegisteredNameSecret
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
naming.operation-pending another operation with the node name is pending currently

PUT /node-name

Update the name of the node. May be used to assign an already-registered name to the node (the corresponding signing key is generated automatically and stored at the node), or to prolong the name. The secret or mnemonic of the updating key must be provided for this operation.

Request body:
RegisteredNameSecret
Response:
Result
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
naming.operation-pending another operation with the node name is pending currently
registeredNameSecret.empty the registered name secret or mnemonic are not provided
node-name.name-absent the node name is not provided and not known by the node
node-name. various errors returned by naming server (see the list)

DELETE /node-name

Delete all the information related to the node name (including the signing key) from the node. The name record on the naming server is not touched.

Response:
Result
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
naming.operation-pending another operation with the node name is pending currently

Notifications object

Receiver of notifications from other nodes.

POST /notifications

Accept a notification packet from other node. Notification packets older than 10 minutes are ignored. The sending node should update the packet timestamp and the signature and send the packet again. This mechanism prevents attackers from recording and resending old signed packets.

Request body:
NotificationPacket
Response:
Result
Authentication (read more):
none
Name and signing key:
not required

People object

Information related to other nodes.

GET /people

Get general information about other nodes.

Response:
PeopleGeneralInfo
Authentication (read more):
none
Name and signing key:
not required

Postings object

All postings. Each posting may contain one or more revisions, a new revision is created every time the posting is updated. The latest revision is the current one, the previous ones are marked as deleted.

POST /postings

Create a new posting from the text given, sign it with the signing key and publish it in the given feeds (if any). The heading and the preview of the posting are created automatically, if needed.

Request body:
PostingText
Response:
PostingInfo
Authentication (read more):
configurable
Name and signing key:
required

PUT /postings/{id}

Update the posting, creating a new revision of it. The text is processed just like in the POST request.

Parameters:
String id - ID of the posting
Request body:
PostingText
Response:
PostingInfo
Authentication (read more):
configurable
Name and signing key:
required
Errors:
Code Description
posting.not-found there is no posting with the given ID
posting.not-original updating a non-original posting is not allowed

GET /postings/{id}

Get an individual posting.

Parameters:
String id - ID of the posting
String include - Comma-separated list of additional blocks of information that are needed. The values are:
  • source - source text of the posting.
Response:
PostingInfo
Authentication (read more):
none
Name and signing key:
not required
Errors:
Code Description
posting.not-found there is no posting with the given ID

DELETE /postings/{id}

Delete the posting. The posting may not be purged from the database immediately, but preserved for some period of time to give a chance to restore it.

Parameters:
String id - ID of the posting
Response:
Result
Authentication (read more):
configurable
Name and signing key:
not required
Errors:
Code Description
posting.not-found there is no posting with the given ID

GET /postings/features

Get information about supported features of postings.

Response:
PostingFeatures
Authentication (read more):
none
Name and signing key:
not required

Posting Revisions object

All revisions of the posting.

GET /postings/{postingId}/revisions

Get all revisions of the posting, but not more than limit. The node may decide to return less revisions than the given limit.

Parameters:
String postingId - ID of the posting
int limit - maximum number of revisions returned
Response:
PostingRevisionInfo[]
Authentication (read more):
configurable
Name and signing key:
not required
Errors:
Code Description
posting.not-found there is no posting with the given ID

GET /postings/{postingId}/revisions/{id}

Get an individual revision of the posting.

Parameters:
String postingId - ID of the posting
String id - ID of the revision
Response:
PostingRevisionInfo
Authentication (read more):
configurable
Name and signing key:
not required
Errors:
Code Description
posting.not-found there is no posting with the given ID
posting-revision.not-found there is no revision with the given ID

POST /postings/{postingId}/revisions/{id}/restore

Restore a revision of the posting. A new revision is created with the same content as in the given revision.

Parameters:
String postingId - ID of the posting
String id - ID of the revision
Response:
PostingRevisionInfo
Authentication (read more):
owner
Name and signing key:
required
Errors:
Code Description
posting.not-found there is no posting with the given ID
posting-revision.not-found there is no revision with the given ID
posting-revision.already-current the given revision is already the current one

Posting Draft Revision object

The draft revisions of the posting - the special revision designed for storing pending changes to the posting that are not published yet.

GET /postings/{postingId}/revisions/draft

Get the posting with the changes stored in its draft revision.

Parameters:
String postingId - ID of the posting
Response:
PostingInfo
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
posting.not-found there is no posting with the given ID

PUT /postings/{postingId}/revisions/draft

Update the draft revision of the posting.

Parameters:
String postingId - ID of the posting
Request body:
PostingText
Response:
PostingInfo
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
posting.not-found there is no posting with the given ID

DELETE /postings/{postingId}/revisions/draft

Erase all changes stored in the draft revision of the posting.

Parameters:
String postingId - ID of the posting
Response:
Result
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
posting.not-found there is no posting with the given ID

Posting Reactions object

Reactions ("Likes") - simple textless answers to a posting.

POST /postings/{postingId}/reactions

Add a reaction to the given posting. The reaction owner must authenticate in some way. Only one reaction is allowed from each owner to a particular posting. If a reaction from the same owner to this posting already exists, it is overwritten. If the reaction is not signed, the reaction will be kept for a limited period of time and then erased (the previous reaction of the same owner will be restored, if any).

Parameters:
String postingId - ID of the posting
Request body:
ReactionDescription
Response:
ReactionCreated
Authentication (read more):
owner
Name and signing key:
not required
Errors:
Code Description
posting.not-found there is no posting with the given ID
reaction.not-accepted the reaction is not acceptable

GET /postings/{postingId}/reactions

Get a slice of the list of reactions to the given posting, optionally filtered by reaction type, delimited by before moment and the given limit. If before is not provided, the latest reactions are returned. The node may decide to return less reactions than the given limit. The reactions are always sorted by moment, descending.

Parameters:
String postingId - ID of the posting
boolean negative - true, to filter negative reactions, false, to filter positive ones
int emoji - filter by reaction code, usually interpreted by clients as emoji code point
int before - filter reactions created at or before this moment
int limit - maximum number of reactions returned
Response:
ReactionsSliceInfo
Authentication (read more):
none
Name and signing key:
not required
Errors:
Code Description
posting.not-found there is no posting with the given ID
limit.invalid limit parameter has an invalid value

GET /postings/{postingId}/reactions/{ownerName}

Get the detailed information about the reaction of the given owner to the given posting. If no reaction with such owner exist, an empty structure with just postingId is returned.

Parameters:
String postingId - ID of the posting
String ownerName - reaction owner node name
Response:
ReactionInfo
Authentication (read more):
none
Name and signing key:
not required
Errors:
Code Description
posting.not-found there is no posting with the given ID

DELETE /postings/{postingId}/reactions

Delete all reactions to the given posting.

Parameters:
String postingId - ID of the posting
Response:
Result
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
posting.not-found there is no posting with the given ID

DELETE /postings/{postingId}/reactions/{ownerName}

Delete the reaction of the given owner to the given posting.

Parameters:
String postingId - ID of the posting
String ownerName - reaction owner node name
Response:
ReactionTotalsInfo
Authentication (read more):
admin or owner
Name and signing key:
not required
Errors:
Code Description
posting.not-found there is no posting with the given ID

Posting Reaction Totals object

Summary of reactions to a posting.

GET /postings/{postingId}/reaction-totals

Get summary of reactions to the posting given.

Parameters:
String postingId - ID of the posting
Response:
ReactionTotalsInfo
Authentication (read more):
none
Name and signing key:
not required
Errors:
Code Description
posting.not-found there is no posting with the given ID

Profile object

The profile - the detailed information about the node's owner, node's purpose etc.

GET /profile

Get the profile.

Parameters:
String include - Comma-separated list of additional blocks of information that are needed. The values are:
  • source - source text of the bio.
Response:
ProfileInfo
Authentication (read more):
none
Name and signing key:
not required

PUT /profile

Update the profile.

Request body:
ProfileAttributes
Response:
ProfileInfo
Authentication (read more):
admin
Name and signing key:
not required

Remote Comments object

Comments to postings located on other nodes.

POST /nodes/{nodeName}/postings/{postingId}/comments

Add a comment to the posting on the remote node and register it in the registry at the local node.

Parameters:
String nodeName - name of the remote node
String postingId - ID of the posting on the remote node
Request body:
CommentSourceText
Response:
Result
Authentication (read more):
admin
Name and signing key:
required

PUT /nodes/{nodeName}/postings/{postingId}/comments/{commentId}

Update a comment to the posting on the remote node.

Parameters:
String nodeName - name of the remote node
String postingId - ID of the posting on the remote node
String commentId - ID of the comment on the remote node
Request body:
CommentSourceText
Response:
Result
Authentication (read more):
admin
Name and signing key:
required

DELETE /nodes/{nodeName}/postings/{postingId}/comments/{commentId}

Delete a comment from the registry of all comments at the local node.

Parameters:
String nodeName - name of the remote node
String postingId - ID of the posting on the remote node
String commentId - ID of the comment on the remote node
Response:
Result
Authentication (read more):
admin
Name and signing key:
not required

POST /nodes/{nodeName}/postings/{postingId}/comments/{commentId}/verify

Verify the signature of the given comment to the posting on the remote node.

Parameters:
String nodeName - name of the remote node
String postingId - ID of the posting on the remote node
String commentId - ID of the comment on the remote node
Response:
AsyncOperationCreated
Authentication (read more):
admin
Name and signing key:
not required

Remote Postings object

Postings located on other nodes.

POST /nodes/{nodeName}/postings/{id}/verify

Verify the signature of the given posting.

Parameters:
String nodeName - name of the remote node
String id - ID of the posting on the remote node
Response:
AsyncOperationCreated
Authentication (read more):
admin
Name and signing key:
not required

POST /nodes/{nodeName}/postings/{id}/revisions/{revisionId}/verify

Verify the signature of the given revision of a posting.

Parameters:
String nodeName - name of the remote node
String id - ID of the posting on the remote node
String revisionId - ID of the posting revision
Response:
AsyncOperationCreated
Authentication (read more):
admin
Name and signing key:
not required

Remote Posting Reactions object

Reactions to postings located on other nodes.

POST /nodes/{nodeName}/postings/{postingId}/reactions

Add a reaction to the posting on the remote node and register it in the registry at the local node.

Parameters:
String nodeName - name of the remote node
String postingId - ID of the posting on the remote node
Request body:
ReactionAttributes
Response:
Result
Authentication (read more):
admin
Name and signing key:
required

DELETE /nodes/{nodeName}/postings/{postingId}/reactions

Delete a reaction from the registry of all reactions at the local node.

Parameters:
String nodeName - name of the remote node
String postingId - ID of the posting on the remote node
Response:
Result
Authentication (read more):
admin
Name and signing key:
not required

POST /nodes/{nodeName}/postings/{postingId}/reactions/{ownerName}/verify

Verify the signature of the reaction of the given owner to the posting on the remote node.

Parameters:
String nodeName - name of the remote node
String postingId - ID of the posting on the remote node
String ownerName - reaction owner node name
Response:
AsyncOperationCreated
Authentication (read more):
admin
Name and signing key:
not required

Settings object

Settings - the node and client settings. The node settings affect the node behavior. Only those settings are accepted that are known by the node, and their values are validated before saving. The node settings metadata can be obtained by request. The client settings are saved without validation and their metadata is built into the client. All client settings must have names starting with client. to distinguish them from the node ones. By convention, the client name is added to the prefix (client.<client name>.) to be able to store settings of several different clients at the same time.

GET /settings/node

Get all node settings, sorted by name. If a setting has not changed its value from the default, it is omitted.

Parameters:
String prefix - filter settings whose names start with the given prefix, case-sensitive
Response:
SettingInfo[]
Authentication (read more):
admin
Name and signing key:
not required

GET /settings/client

Get all client settings, sorted by name.

Parameters:
String prefix - filter settings whose names start with the given prefix, case-sensitive (client. prefix must be included)
Response:
SettingInfo[]
Authentication (read more):
admin
Name and signing key:
not required

GET /settings/node/metadata

Get all node settings metadata, sorted by name.

Parameters:
String prefix - filter settings whose names start with the given prefix, case-sensitive
Response:
SettingMetaInfo[]
Authentication (read more):
admin
Name and signing key:
not required

PUT /settings

Update the given settings. If the input contains node settings, they are validated and the first validation error is returned, if any. The update is always performed as whole - if there is an error saving any one of the settings in the input, none of them are updated.

If one of the settings to be updated is privileged, root secret authentication is required. If one of the settings to be updated is non-privileged, admin authentication is required.

Request body:
SettingInfo[]
Response:
Result
Authentication (read more):
admin or root secret
Name and signing key:
not required
Errors:
Code Description
setting.deserialization-failed setting value deserialization failed
setting.cannot-convert cannot convert value to the setting type
setting.invalid-value invalid value for the setting
setting.internal cannot set value of an internal setting
setting.unknown unknown setting

Stories object

All stories. Each story describes something happening in Moera, stories are building blocks for feeds. A story may reference a posting, a remote object etc.

GET /stories/{id}

Get an individual story.

Parameters:
String id - ID of the story
Response:
StoryInfo
Authentication (read more):
none
Name and signing key:
not required
Errors:
Code Description
story.not-found there is no story with the given ID

PUT /stories/{id}

Update the story.

Parameters:
String id - ID of the story
Request body:
StoryAttributes
Response:
StoryInfo
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
story.not-found there is no story with the given ID

Subscribers object

All nodes that have subscribed to notifications from this node.

GET /people/subscribers

Get the list of all subscribers, optionally filtered by some criteria.

Parameters:
String nodeName - filter by subscribed node name, may be omitted
String type - filter by subscription type (see SubscriptionDescription.type for the list of possible values), may be omitted
Response:
SubscriberInfo[]
Authentication (read more):
none
Name and signing key:
not required

POST /people/subscribers

Subscribe to a particular group of notifications.

Request body:
SubscriberDescription
Response:
SubscriberInfo
Authentication (read more):
owner
Name and signing key:
not required
Errors:
Code Description
subscriber.already-exists an identical subscriber already exists

GET /people/subscribers/{id}

Get an individual subscriber.

Parameters:
String id - ID of the subscriber
Response:
SubscriberInfo
Authentication (read more):
admin or owner
Name and signing key:
not required
Errors:
Code Description
subscriber.not-found there is no subscriber with the given ID

DELETE /people/subscribers/{id}

Delete a subscriber.

Parameters:
String id - ID of the subscriber
Response:
Result
Authentication (read more):
admin or owner
Name and signing key:
not required
Errors:
Code Description
subscriber.not-found there is no subscriber with the given ID

Subscriptions object

All nodes that send notifications to this node.

GET /people/subscriptions

Get the list of all subscriptions, optionally filtered by some criteria.

Parameters:
String nodeName - filter by node name, may be omitted
String type - filter by subscription type (see SubscriptionDescription.type for the list of possible values), may be omitted
Response:
SubscriptionInfo[]
Authentication (read more):
none
Name and signing key:
not required

POST /people/subscriptions

Register a subscription to notifications from a particular node.

Request body:
SubscriptionDescription
Response:
SubscriptionInfo
Authentication (read more):
admin
Name and signing key:
required
Errors:
Code Description
subscription.already-exists an identical subscription already exists

DELETE /people/subscriptions

Delete the subscription described by the given parameters.

Parameters:
String remoteNodeName - name of the node this node is subscribed to
String remoteSubscriberId - ID of the subscriber on the remote node
Response:
Result
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
subscription.not-found there is no subscription with the given parameters.

GET /people/subscriptions/search

Search for subscriptions by the given criteria.

Request body:
SubscriptionFilter
Response:
SubscriptionInfo[]
Authentication (read more):
admin
Name and signing key:
not required

Tokens object

The authentication token. Read more about token-base authentication in the Overview section.

GET /tokens/{token}

Get information about the token.

Parameters:
String token - the token
Response:
TokenInfo
Authentication (read more):
none
Name and signing key:
not required

POST /tokens

Sign in and create a token.

Request body:
Credentials
Response:
TokenCreated
Authentication (read more):
none
Name and signing key:
not required
Errors:
Code Description
credentials.not-created credentials are not created yet
credentials.login-incorrect login or password is incorrect

Web Push object

Management of Web Push subscriptions.

GET /web-push/key

Get Web Push application key.

Response:
WebPushKey
Authentication (read more):
admin
Name and signing key:
not required

POST /web-push/subscriptions

Add Web Push subscription.

Request body:
WebPushSubscriptionAttributes
Response:
WebPushSubscriptionInfo
Authentication (read more):
admin
Name and signing key:
not required

DELETE /web-push/subscriptions/{id}

Delete Web Push subscription.

Parameters:
String id - ID of the subscription
Response:
Result
Authentication (read more):
admin
Name and signing key:
not required
Errors:
Code Description
web-push-subscription.not-found there is no Web Push subscription with the given ID

Who Am I object

Brief information about the node.

GET /whoami

Get brief information about the node.

Response:
WhoAmI
Authentication (read more):
none
Name and signing key:
not required


Structures

AcceptedReactions

Type Name Description
String positive comma-separated list of codes of the positive reactions that are accepted; a code may be prefixed by 0x to designate hexadecimal number and + to designate a recommended reaction
String negative comma-separated list of codes of the negative reactions that are accepted (the format is the same as above)

ActivityReactionFilter

Type Name Description
RemotePosting[] postings include only reactions to remote postings from this list

ActivityReactionInfo

Type Name Description
String remoteNodeName name of the remote node
String remoteFullName full name of the remote node
String remotePostingId ID of the posting on the remote node
boolean negative true, if the reaction is negative, false, if positive
int emoji reaction code, usually interpreted by clients as emoji code point
timestamp createdAt reaction creation timestamp - the real time when the reaction was created

AsyncOperationCreated

Type Name Description
String id ID of the asyncronous operation that was created

Body

Type Name Description
String subject plain text
String text HTML

CarteInfo

Type Name Description
String carte
timestamp beginning timestamp of the beginning of the carte's life
timestamp deadline timestamp of the end of the carte's life

CarteSet

Type Name Description
String cartesIp the client IP address the cartes are bound to
CarteInfo[] cartes the cartes
timestamp createdAt cartes creation timestamp

Choice

Type Name Description
String value
String title user-readable title for the value

ClientReactionInfo

Type Name Description
boolean negative true, if the reaction is negative, false, if positive
int emoji reaction code, usually interpreted by clients as emoji code point
timestamp createdAt reaction creation timestamp - the real time when the reaction was created
timestamp deadline if present, the reaction will be erased at this time

CommentCreated

Type Name Description
CommentInfo comment details of the comment created
int total total number of comments in the posting after the creation

CommentInfo

Type Name Description
String id
String ownerName node name of the comment's owner
String ownerFullName full name of the comment's owner
String postingId ID of the parent posting of the comment
String postingRevisionId ID of the revision of parent posting that was current when the comment was created
String revisionId ID of the current revision of the comment
int totalRevisions total number of revisions the comment has
String bodyPreview preview of the comment's body, a string representation of a JSON structure, may be absent
String bodySrc the source text of the comment, a string representation of a JSON structure, may be absent if not requested
byte[] bodySrcHash hash of the source text of the comment
String bodySrcFormat format of the source text of the comment, the list of available formats is returned in PostingFeatures
String body body of the comment, a string representation of a JSON structure
String bodyFormat format of the body of the comment, may have any value meaningful for the client, including:
  • message - Body structure;
  • application - an application-specific structure.
String heading heading of the comment
RepliedTo repliedTo information about the comment this comment is replying to, may be absent
int moment
timestamp createdAt comment creation timestamp - the real time when the comment was created
timestamp editedAt comment editing timestamp - the last time the comment was updated
timestamp deletedAt comment deletion timestamp - the time when the comment was deleted, may be absent
timestamp revisionCreatedAt creation timestamp of the current revision of the comment
timestamp deadline comment purging timestamp - the time when the deleted comment will be purged from the database, may be absent
byte[] digest cryptographic digest of the comment
byte[] signature the comment's owner signature (use Comment fingerprint)
int signatureVersion signature version (i.e. fingerprint version)
String -> String[] operations list of the supported operations (see below) and the corresponding access hints
AcceptedReactions acceptedReactions types of reactions that the comment accepts
ClientReactionInfo clientReaction details of the existing reaction (if any) of the client's owner
ReactionTotalsInfo reactions reactions summary of the comment
Operations (read more):
Name Description
edit edit the comment
delete delete the comment
revisions view the comment's revisions
reactions view reactions to the comment

CommentRevisionInfo

Type Name Description
String id
String postingRevisionId ID of the posting revision that was actual at the moment of creation of this comment revision
String bodyPreview preview of the revision's body, a string representation of a JSON structure, may be absent
byte[] bodySrcHash hash of the source text of the revision
String bodySrcFormat format of the source text of the revision, the list of available formats is returned in PostingFeatures
String body body of the revision, a string representation of a JSON structure
String bodyFormat format of the body of the revision, may have any value meaningful for the client, including:
  • message - Body structure;
  • application - an application-specific structure.
String heading heading of the revision
timestamp createdAt revision creation timestamp - the real time when the revision was created
timestamp deletedAt revision deletion timestamp - the time when the revision was deleted, may be absent
timestamp deadline revision deletion timestamp - the time when the revision will be deleted and the previous revision will take its place, may be absent
byte[] digest cryptographic digest of the revision
byte[] signature the comment's owner signature (use Comment fingerprint)
int signatureVersion signature version (i.e. fingerprint version)
ClientReactionInfo clientReaction details of the existing reaction (if any) of the client's owner
ReactionTotalsInfo reactions reactions summary of the revision

CommentsSliceInfo

Type Name Description
int before the slice contains all comments before this moment, inclusive. May be the far future.
int after the slice contains all comments after this moment, exclusive. May be the far past.
CommentInfo[] comments the comments
int total total number of comments
int totalInPast number of comments before this slice till the far past
int totalInFuture number of comments after this slice till the far future

CommentSourceText

Type Name Description
String bodySrc the source text of the comment, a string representation of a JSON structure
String bodySrcFormat format of the source text of the comment, plain-text by default; the list of available formats is returned in PostingFeatures
AcceptedReactions acceptedReactions types of reactions that the comment accepts
String repliedToId ID of the comment this comment is replying to
Validation errors:
Code Description
commentText.bodySrc.blank body text is empty
commentText.bodySrc.wrong-size body text is too long
commentText.bodySrc.wrong-encoding body text is formatted incorrectly
commentText.acceptedReactions.positive.wrong-size list of accepted positive reactions is too long
commentText.acceptedReactions.positive.wrong-pattern list of accepted positive reactions has wrong format
commentText.acceptedReactions.negative.wrong-size list of accepted negative reactions is too long
commentText.acceptedReactions.negative.wrong-pattern list of accepted negative reactions has wrong format

CommentText

Type Name Description
String ownerName node name of the comment's owner
String ownerFullName full name of the comment's owner
String bodyPreview preview of the comment's body, a string representation of a JSON structure
String bodySrc the source text of the comment, a string representation of a JSON structure
String bodySrcFormat format of the source text of the comment, plain-text by default; the list of available formats is returned in PostingFeatures
String body body of the comment, a string representation of a JSON structure
String bodyFormat format of the body of the comment, may have any value meaningful for the client, including:
  • message - Body structure;
  • application - an application-specific structure.
timestamp createdAt comment creation timestamp - the real time when the comment was created
AcceptedReactions acceptedReactions types of reactions that the comment accepts
String repliedToId ID of the comment this comment is replying to
byte[] signature the comment's owner signature (use Comment fingerprint)
int signatureVersion signature version (i.e. fingerprint version)
Validation errors:
Code Description
commentText.bodySrc.blank body text is empty
commentText.bodySrc.wrong-size body text is too long
commentText.bodySrc.wrong-encoding body text is formatted incorrectly
commentText.bodySrcFormat.unknown unknown body text format
commentText.body.blank body is empty
commentText.body.wrong-size body is too long
commentText.body.wrong-encoding body encoding is incorrect
commentText.bodyPreview.wrong-encoding body preview encoding is incorrect
commentText.bodyFormat.blank body format is not set
commentText.bodyFormat.wrong-size body format is too long
commentText.createdAt.blank body creation timestamp is not set
commentText.createdAt.out-of-range body creation timestamp is too far from the current timestamp
commentText.acceptedReactions.positive.wrong-size list of accepted positive reactions is too long
commentText.acceptedReactions.positive.wrong-pattern list of accepted positive reactions has wrong format
commentText.acceptedReactions.negative.wrong-size list of accepted negative reactions is too long
commentText.acceptedReactions.negative.wrong-pattern list of accepted negative reactions has wrong format
commentText.repliedToId.not-found comment referred in `repliedToId` is not found

CommentTotalInfo

Type Name Description
int total total number of comments in the posting after the operation

ContactInfo

Type Name Description
String nodeName
String fullName
float closeness closeness of the contact to the node, which is calculated from the number of reactions and comments and their age

Credentials

Type Name Description
String login
String password
Validation errors:
Code Description
credentials.login.blank the login is empty
credentials.password.blank the password is empty

CredentialsChange

Type Name Description
String token credentials reset token
String oldPassword the current password
String login
String password
Validation errors:
Code Description
credentials.login.blank the login is empty
credentials.password.blank the password is empty

CredentialsCreated

Type Name Description
boolean created true if the credentials are initialized already, false otherwise

DomainAttributes

Type Name Description
String name domain's hostname or _default_ for the default domain
UUID nodeId domain's node ID
Validation errors:
Code Description
domainAttributes.name.blank the domain name is empty
domainAttributes.name.wrong-hostname the domain name is not a valid hostname
domainAttributes.nodeId.wrong-uuid the node ID is not a valid UUID

DomainAvailable

Type Name Description
String name fully-qualified domain name

DomainInfo

Type Name Description
String name domain's hostname or _default_ for the default domain
UUID nodeId domain's node ID
timestamp createdAt domain creation timestamp
Validation errors:
Code Description
domainInfo.name.blank the domain name is empty
domainInfo.name.wrong-hostname the domain name is not a valid hostname
domainInfo.nodeId.wrong-uuid the node ID is not a valid UUID

EmailHint

Type Name Description
String emailHint a masked E-mail address that should help user to understand which E-mail address was used without revealing it

FeedInfo

Type Name Description
String feedName name of the feed
String title title of the feed
String subscriberId ID of the subscriber, if the client is subscribed to notifications about this feed, null or absent otherwise
String -> String[] operations list of the supported operations (see below) and the corresponding access hints
Operations (read more):
Name Description
add add stories to the feed

FeedReference

Type Name Description
String feedName name of the feed
timestamp publishedAt story publication timestamp - the time the story is published under in the feed
boolean pinned true, if the story is pinned (should appear before any non-pinned story in the feed), false otherwise
int moment
String storyId ID of the story
String -> String[] operations list of the supported operations (see StoryInfo.operations) and the corresponding access hints for the story in the feed

FeedSliceInfo

Type Name Description
int before the slice contains all stories before this moment, inclusive. May be the far future.
int after the slice contains all stories after this moment, exclusive. May be the far past.
StoryInfo[] stories the stories

FeedStatus

Type Name Description
int notViewed number of stories that have not been viewed yet.
int notRead number of stories that have not been read yet.

FeedStatusChange

Type Name Description
boolean viewed new value of the viewed flag (null, if the flag is not changed).
boolean read new value of the read flag (null, if the flag is not changed).
int before change flags for all stories before this moment, inclusive.

NameToRegister

Type Name Description
String name
Validation errors:
Code Description
nameToRegister.name.blank the name is empty
nameToRegister.name.invalid the name is reserved, too long or contains invalid characters

NotificationPacket

Type Name Description
String id ID of the notification packet on the sending node (used to filter out duplicates)
String nodeName name of the sending node
String fullName full name of the sending node
timestamp createdAt notification packet creation timestamp
String type notification type
String notification the notification, a string representation of a JSON structure (see Notifications page for details)
byte[] signature the notification packet sender signature (use NotificationPacket fingerprint)
int signatureVersion signature version (i.e. fingerprint version)

NodeNameInfo

Type Name Description
String name
OperationStatus operationStatus status of the latest operation with the node name
timestamp operationStatusUpdated the last time the operation status was updated
String operationErrorCode if the operation with the node name was failed, the code of the failure
String operationErrorMessage if the operation with the node name was failed, the human-readable description of the failure
String -> String[] operations list of the supported operations (see below) and the corresponding access hints
Operations (read more):
Name Description
manage any modification of the node name, prolonging it etc.

PeopleGeneralInfo

Type Name Description
int feedSubscribersTotal total number of subscribers of the node
int feedSubscriptionsTotal total number of subscriptions of the node

PostingFeatures

Type Name Description
boolean subjectPresent true if new postings are recommended to have a subject, false otherwise
Choice[] sourceFormats List of source text formats the node understands. The well-known values are:
  • plain-text - plain text with newlines and paragraphs delimited by empty line;
  • html - HTML-formatted text, the node may allow only limited set of tags;
  • markdown - text in Markdown format.

PostingInfo

Type Name Description
String id
String revisionId ID of the current revision of the posting
String receiverRevisionId ID of the current revision of the original posting (for cached copies of remote postings only)
int totalRevisions total number of revisions the posting has
String receiverName name of the node where the posting was published (for cached copies of remote postings only)
String receiverFullName full name of the node where the posting was published (for cached copies of remote postings only)
String receiverPostingId ID of the original posting (for cached copies of remote postings only)
String ownerName node name of the posting's owner
String ownerFullName full name of the posting's owner
String bodyPreview preview of the posting's body, a string representation of a JSON structure, may be absent
String bodySrc the source text of the posting, a string representation of a JSON structure, may be absent if not requested
byte[] bodySrcHash hash of the source text of the posting
String bodySrcFormat format of the source text of the posting, the list of available formats is returned in PostingFeatures
String body body of the posting, a string representation of a JSON structure
String bodyFormat format of the body of the posting, may have any value meaningful for the client, including:
  • message - Body structure;
  • application - an application-specific structure.
String heading heading of the posting
UpdateInfo updateInfo description of the latest update
timestamp createdAt posting creation timestamp - the real time when the posting was created
timestamp editedAt posting editing timestamp - the last time the posting was updated
timestamp deletedAt posting deletion timestamp - the time when the posting was deleted, may be absent
timestamp receiverCreatedAt original posting creation timestamp (for cached copies of remote postings only)
timestamp receiverEditedAt original posting editing timestamp (for cached copies of remote postings only)
timestamp receiverDeletedAt original posting deletion timestamp (for cached copies of remote postings only)
timestamp revisionCreatedAt creation timestamp of the current revision of the posting
timestamp receiverRevisionCreatedAt creation timestamp of the current revision of the original posting (for cached copies of remote postings only)
timestamp deadline posting purging timestamp - the time when the deleted posting will be purged from the database, may be absent
boolean draft true, if the posting is a draft, false otherwise
boolean draftPending true, if the posting has a pending draft revision, false otherwise, may be absent if not requested
byte[] signature the posting's owner signature (use Posting fingerprint)
int signatureVersion signature version (i.e. fingerprint version)
FeedReference[] feedReferences array of references to the posting from stories in feeds
String -> String[] operations list of the supported operations (see below) and the corresponding access hints
AcceptedReactions acceptedReactions types of reactions that the posting accepts
ClientReactionInfo clientReaction details of the existing reaction (if any) of the client's owner
ReactionTotalsInfo reactions reactions summary of the posting
boolean reactionsVisible true, if the posting allows to view detailed information about reactions to anybody except posting and reaction owners, false otherwise
boolean reactionTotalsVisible true, if the posting allows to view number of reactions to anybody except the posting owner, false otherwise
PostingSourceInfo[] sources details of the sources the posting was received from (for cached copies of remote postings only)
int totalComments total number of comments to the posting
PostingSubscriptionsInfo subscriptions existing subscriptions of the client's owner
Operations (read more):
Name Description
edit edit the posting
delete delete the posting
revisions view the posting's revisions
reactions view reactions to the posting

PostingRevisionInfo

Type Name Description
String id
String receiverId ID of the original revision (for cached copies of remote postings only)
String bodyPreview preview of the revisions's body, a string representation of a JSON structure, may be absent
byte[] bodySrcHash hash of the source text of the revision
String bodySrcFormat format of the source text of the revision, the list of available formats is returned in PostingFeatures
String body body of the revision, a string representation of a JSON structure
String bodyFormat format of the body of the revision, see detailed description in PostingInfo.bodyFormat
String heading heading of the revision
UpdateInfo updateInfo description of the latest update
timestamp createdAt revision creation timestamp - the real time when the revision was created
timestamp deletedAt revision deletion timestamp - the time when the revision was deleted, may be absent
timestamp receiverCreatedAt original revision creation timestamp (for cached copies of remote postings only)
timestamp receiverDeletedAt original revision deletion timestamp (for cached copies of remote postings only)
byte[] signature the revision's owner signature (use Posting fingerprint)
int signatureVersion signature version (i.e. fingerprint version)
ClientReactionInfo clientReaction details of the existing reaction (if any) of the client's owner
ReactionTotalsInfo reactions reactions summary of the posting revision

PostingSourceInfo

Type Name Description
String nodeName name of the remote node
String fullName full name of the remote node
String feedName name of the feed on the remote node
String postingId ID of the posting on the remote node
timestamp createdAt timestamp when the posting was received from this source

PostingSubscriptionsInfo

Type Name Description
String comments ID of the existing subscription to posting comments, if any

PostingText

Type Name Description
String ownerFullName full name of the posting's owner
String bodySrc the source text of the posting, a string representation of a JSON structure
String bodySrcFormat format of the source text of the posting, plain-text by default; the list of available formats is returned in PostingFeatures
AcceptedReactions acceptedReactions types of reactions that the posting accepts
boolean reactionsVisible true, if the posting allows to view detailed information about reactions to anybody except posting and reaction owners, false otherwise
boolean reactionTotalsVisible true, if the posting allows to view number of reactions to anybody except the posting owner, false otherwise
StoryAttributes[] list of publications in feeds that must be made after creating the posting (for new postings only)
UpdateInfo updateInfo description of the update
Validation errors:
Code Description
postingText.bodySrc.blank body text is empty
postingText.bodySrc.wrong-size body text is too long
postingText.bodySrc.wrong-encoding body text is formatted incorrectly
postingText.bodySrcFormat.unknown unknown body text format
postingText.acceptedReactions.positive.wrong-size list of accepted positive reactions is too long
postingText.acceptedReactions.positive.wrong-pattern list of accepted positive reactions has wrong format
postingText.acceptedReactions.negative.wrong-size list of accepted negative reactions is too long
postingText.acceptedReactions.negative.wrong-pattern list of accepted negative reactions has wrong format
postingText.publications.cannot-modify publications field is not allowed in posting modification query

ProfileAttributes

Type Name Description
String fullName node owner's full name
String gender node owners's gender
String email node owner's E-mail address
String title node title
String bioSrc the source text of node owner's bio (arbitrary text)
String bioSrcFormat format of the source text of node owner's bio, markdown by default; the list of available formats is returned in PostingFeatures
Validation errors:
Code Description
profileAttributes.fullName.wrong-size the full name is too long
profileAttributes.gender.wrong-size the gender string is too long
profileAttributes.email.wrong-size the E-mail is too long
profileAttributes.email.wrong-email the E-mail is not a well-formed E-mail address
profileAttributes.title.wrong-size the title is too long
profileAttributes.bioSrc.wrong-size the bio is too long

ProfileInfo

Type Name Description
String fullName node owner's full name
String gender node owners's gender
String email node owner's E-mail address
String title node title
String bioSrc the source text of node owner's bio (arbitrary text), may be absent if not requested
String bioSrcFormat format of the source text of node owner's bio, markdown by default, may be absent if not requested; the list of available formats is returned in PostingFeatures
String bioHtml HTML representation of node owner's bio
String -> String[] operations list of the supported operations (see below) and the corresponding access hints
Operations (read more):
Name Description
edit change the profile

ReactionAttributes

Type Name Description
boolean negative true, if the reaction is negative, false, if positive
int emoji reaction code, usually interpreted by clients as emoji code point

ReactionCreated

Type Name Description
ReactionInfo reaction details of the reaction created
ReactionTotalsInfo totals summary of reactions after the creation

ReactionDescription

Type Name Description
String ownerName reaction owner node name
String ownerFullName reaction owner full name
boolean negative true, if the reaction is negative, false, if positive
int emoji reaction code, usually interpreted by clients as emoji code point
byte[] signature the reaction owner signature (use Reaction fingerprint)
int signatureVersion signature version (i.e. fingerprint version)

ReactionInfo

Type Name Description
String ownerName reaction owner node name
String ownerFullName reaction owner full name
String postingId ID of the posting
String postingRevisionId ID of the posting revision, if relevant
String commentId ID of the comment, if relevant
String commentRevisionId ID of the comment revision, if relevant
boolean negative true, if the reaction is negative, false, if positive
int emoji reaction code, usually interpreted by clients as emoji code point
int moment
timestamp createdAt reaction creation timestamp - the real time when the reaction was created
timestamp deadline if present, the reaction will be erased at this time
byte[] signature the reaction owner signature (use Reaction fingerprint)
int signatureVersion signature version (i.e. fingerprint version)
String -> String[] operations list of the supported operations (see below) and the corresponding access hints
Operations (read more):
Name Description
delete delete the reaction

ReactionsSliceInfo

Type Name Description
int before the slice contains all reactions before this moment, inclusive. May be the far future.
int after the slice contains all reactions after this moment, exclusive. May be the far past.
int total total number of reactions in the whole list
ReactionInfo[] reactions the reactions

ReactionTotalInfo

Type Name Description
int emoji reaction code, usually interpreted by clients as emoji code point
int total total number of reactions with the given code (may be absent)
float share share the reactions with the given code stand from the total number of reactions (may be absent, if total is present)

ReactionTotalsInfo

Type Name Description
ReactionTotalInfo[] positive summary of positive reactions
ReactionTotalInfo[] negative summary of negative reactions

RegisteredNameSecret

Type Name Description
String name
String[] mnemonic human-friendly mnemonic of the updating key
String secret base64-encoded secret of the updating key

RemotePosting

Type Name Description
String nodeName name of the node
String postingId ID of the posting on the node

RemotePostingVerificationInfo

Type Name Description
String id asynchronous operation ID
String nodeName
String postingId
String revisionId
String status status of the operation, may be one of:
  • running - the verification is pending;
  • correct - the signature is correct;
  • incorrect - the signature is incorrect;
  • error - the verification cannot be performed due to an error.
String errorCode error code
String errorMessage human-readable error message

RemoteReactionVerificationInfo

Type Name Description
String id asynchronous operation ID
String nodeName
String postingId
String reactionOwnerName node name of the reaction's owner
String status status of the operation, may be one of:
  • running - the verification is pending;
  • correct - the signature is correct;
  • incorrect - the signature is incorrect;
  • error - the verification cannot be performed due to an error.
String errorCode error code
String errorMessage human-readable error message

RepliedTo

Type Name Description
String id ID of the comment
String revisionId ID of the comment revision
String name node name of the comment's owner
String fullName full name of the comment's owner
String heading heading of the comment
byte[] digest cryptographic digest of the comment

Result

Type Name Description
String errorCode error code
String message human-readable error message

SettingInfo

Type Name Description
String name name of the setting
String value value of the setting

SettingMetaInfo

Type Name Description
String name name of the setting
String type type of the setting, may be one of:
  • bool - boolean, may have value true or false
  • Duration - period of time, an non-negative integer followed by a single character designating a measurement unit:
    • s - seconds;
    • m - minutes;
    • h - hours;
    • d - days.
  • int - integer
  • string - string
String defaultValue default value of the setting
boolean privileged the setting is privileged - may be changed by server owner only
String title human-friendly description of the setting
SettingTypeModifiers modifiers additional modifiers that may help to choose a proper UI component for the setting value and to validate the input; meaning of the modifiers depend on the setting type

SettingTypeModifiers

Type Name Description
String min (int, Duration) minimal value
String max (int, Duration) maximal value
boolean multiline (string) true, if the value is a multiline text
boolean never (Duration) true, if value never is allowed
boolean always (Duration) true, if value always is allowed

StoryAttributes

Type Name Description
String feedName name of the feed
timestamp publishAt story publication timestamp - the time the story must be published under in the feed
boolean pinned true, if the story is pinned (should appear before any non-pinned story in the feed), false otherwise
boolean viewed value of the viewed flag (null, if the flag is not changed).
boolean read value of the read flag (null, if the flag is not changed).

StoryInfo

Type Name Description
String id
String feedName name of the feed
String storyType type of the story (see Stories page for description of various story types and their meaning)
timestamp createdAt story creation timestamp - the real time when the story was created
timestamp publishedAt story publication timestamp - the time the story is published under in the feed
boolean pinned true, if the story is pinned (should appear before any non-pinned story in the feed), false otherwise
int moment
boolean viewed true, if the story has been viewed by node owner, false otherwise
boolean read true, if the story has been read by node owner, false otherwise
String -> String[] operations list of the supported operations (see below) and the corresponding access hints
String summary user-readable summary of the story
String trackingId ID (visible by node admin only) that may be used to update the story viewed/read status without authentication
PostingInfo posting the posting this story is about (may be absent or contain only ID)
CommentInfo comment the comment this story is about (may be absent or contain only ID)
String remoteNodeName name of the node this story is about (may be absent)
String remoteFullName full name of the node this story is about (may be absent)
String remotePostingId ID of the posting at remote node this story is about (may be absent)
String remoteCommentId ID of the comment at remote node this story is about (may be absent)
Operations (read more):
Name Description
edit update the story
delete delete the story

SubscriberDescription

Type Name Description
String type subscription type, (see SubscriptionDescription.type for the list of possible values)
String feedName feed name, if the subscription type requires one
String postingId posting ID, if the subscription type requires one
String ownerFullName full name of the subscriber
timestamp lastUpdatedAt timestamp of the latest known state of the object, may be absent
Validation errors:
Code Description
subscriberDescription.type.blank type is empty
subscriberDescription.feedName.blank feed name is empty
subscriberDescription.feedName.not-found feed is not found
subscriberDescription.postingId.blank posting ID is empty
subscriberDescription.postingId.not-found posting is not found

SubscriberInfo

Type Name Description
String id subscriber ID
String type subscription type, (see SubscriptionDescription.type for the list of possible values)
String feedName feed name, if the subscription type requires one
String postingId posting ID, if the subscription type requires one
String nodeName name of the subscribed node
String fullName full name of the subscribed node
timestamp createdAt subscription creation timestamp

SubscriptionDescription

Type Name Description
String type subscription type, the possible values are:
  • feed - subscribe to new stories in the feed;
  • posting - subscribe to updates to the posting;
  • posting-comments - subscribe to new comments to the posting;
  • profile - subscribe to updates to the node profile.
String feedName feed name on this node that receives notifications
String remoteSubscriberId ID of the subscriber on the remote node
String remoteNodeName name of the node this node is subscribed to
String remoteFullName full name of the node this node is subscribed to
String remoteFeedName feed name on the remote node, if the subscription type requires one
String remotePostingId posting ID on the remote node, if the subscription type requires one
String reason subscription reason, the well-known values are:
  • user - node owner asked to subscribe;
  • mention - node name was mentioned;
  • comment - node owner commented the posting.
Validation errors:
Code Description
subscriptionDescription.type.blank type is empty
subscriptionDescription.feedName.blank feed name is empty
subscriptionDescription.feedName.not-found feed is not found
subscriptionDescription.remoteSubscriberId.blank subscriber ID is empty
subscriptionDescription.remoteSubscriberId.wrong-size subscriber ID is too long
subscriptionDescription.remoteNodeName.blank node name is empty
subscriptionDescription.remoteNodeName.wrong-size node name is too long
subscriptionDescription.remoteFeedName.wrong-size remote feed name is too long
subscriptionDescription.remotePostingId.wrong-size posting ID is too long
subscriptionDescription.reason.blank subscription reason is empty

SubscriptionFilter

Type Name Description
RemotePosting[] postings list of postings

SubscriptionInfo

Type Name Description
String id subscription ID
String type subscription type, (see SubscriptionDescription.type for the list of possible values)
String feedName feed name on this node that receives notifications
String remoteSubscriberId ID of the subscriber on the remote node
String remoteNodeName name of the node this node is subscribed to
String remoteFullName full name of the node this node is subscribed to
String remoteFeedName feed name on the remote node, if the subscription type requires one
String remotePostingId posting ID on the remote node, if the subscription type requires one
timestamp createdAt subscription creation timestamp
String reason subscription reason (see the list of well-known values in SubscriptionDescription.reason

TokenCreated

Type Name Description
String token the token
String[] permissions The list of permission groups assigned to the token.

TokenInfo

Type Name Description
String token the token
boolean valid true if the token is valid, false otherwise.
String[] permissions The list of permission groups assigned to the token. See also the list of standard permission groups.

UpdateInfo

Type Name Description
boolean important true, if the update is important, false (the default) otherwise
String description description of the update

WebPushKey

Type Name Description
String key BASE64-encoded key

WebPushSubscriptionAttributes

Type Name Description
String endpoint Web Push endpoint URL
String publicKey VAPID public signing key
String authKey VAPID authentication key
Validation errors:
Code Description
webPushSubscriptionAttributes.endpoint.blank endpoint is empty
webPushSubscriptionAttributes.endpoint.wrong-size endpoint is too long
webPushSubscriptionAttributes.publicKey.blank public key is empty
webPushSubscriptionAttributes.publicKey.wrong-size public key is too long
webPushSubscriptionAttributes.authKey.blank auth key is empty
webPushSubscriptionAttributes.authKey.wrong-size auth key is too long

WebPushSubscriptionInfo

Type Name Description
String id Web Push subscription ID

WhoAmI

Type Name Description
String nodeName
boolean nodeNameChanging true if node name is about to be changed
String fullName node owner's full name
String gender node owners's gender
String title node title


Enums

OperationStatus

This enum is used to designate the operation status both by the naming server and by the node.

Value Description
WAITING operation is waiting to be sent to the naming server
ADDED operation was accepted by the naming server
STARTED the naming server started to proceed the operation
SUCCEEDED operation completed successfully
FAILED operation failed
UNKNOWN operation status is unknown


HTTP status codes

Code Description
200 No error.
201 Object created successfully. The object location is provided in Location: header.
400 Validation of the request body failed.
401 Invalid authentication token or root secret.
403 Authentication required, but not provided.
404 Unrecognized request or object not found.
405 Method not allowed.
409 Operation failed.
500 The node configured incorrectly or a bug in the node software; naming service not available.