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 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 - URL parameter secret must be provided with the value equal to the secret value set in the node configuration;
  • admin - admin token received after signing in must be passed in URL parameter 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 URL parameter carte) 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. Credentials object
  5. Deleted Postings object
  6. Deleted Posting Revisions object
  7. Domains object
  8. Draft Postings object
  9. Feeds object
  10. Node Name object
  11. Notifications object
  12. People object
  13. Postings object
  14. Posting Revisions object
  15. Posting Draft Revision object
  16. Profile object
  17. Reaction Totals object
  18. Reactions object
  19. Remote Postings object
  20. Remote Reactions object
  21. Settings object
  22. Stories object
  23. Subscribers object
  24. Subscriptions object
  25. Tokens object
  26. Who Am I object
  27. 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

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.

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

DELETE /credentials

Delete credentials.

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

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.

Parameters:
String name - domain name
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

POST /domains

Create a new domain with the given hostname. If nodeId is not passed, it is generated automatically.

Request body:
DomainInfo
Response:
DomainInfo
Authentication (read more):
root secret
Name and signing key:
not required
Errors:
Code Description
domainInfo.name.blank the hostname is empty
domain.already-exists the domain with the given hostname 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 hostname
Request body:
DomainInfo
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

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

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.

Parameters:
String postingId - ID of the posting
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

Profile object

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

GET /profile

Get the profile.

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

PUT /profile

Update the profile.

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

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
reaction-totals.posting-not-found there is no posting with the given ID

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
reaction.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
reaction.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
reaction.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
reaction.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
reaction.posting-not-found there is no posting with the given ID

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 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.

Request body:
SettingInfo[]
Response:
Result
Authentication (read more):
admin
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, 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, 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 type - subscription type
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.

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

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 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

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

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

CredentialsCreated

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

DomainInfo

Type Name Description
String name domain's hostname or _default_ for the default domain
UUID nodeId domain's node ID
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

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

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
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 receiverPostingId ID of the original posting (for cached copies of remote postings only)
String ownerName node 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
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)
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
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 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

PostingText

Type Name Description
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)
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

Profile

Type Name Description
String fullName node owner's full name
String gender node owners's gender
String email node owner's E-mail address
Validation errors:
Code Description
profile.fullName.wrong-size the full name is too long
profile.gender.wrong-size the gender string is too long
profile.email.wrong-email the E-mail is not a well-formed E-mail address

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 -> 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
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 postingId ID of the posting
String postingRevisionId ID of the posting revision
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

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
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

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)
String remoteNodeName 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)
Operations (read more):
Name Description
edit update the story
delete delete the story

SubscriberDescription

Type Name Description
String type subscription type
String feedName feed name, if the subscription type requires one
String postingId posting ID, if the subscription type requires one
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
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
timestamp createdAt subscription creation timestamp

SubscriptionDescription

Type Name Description
String type subscription type
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 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
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

SubscriptionInfo

Type Name Description
String id subscription ID
String type subscription type
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 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

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.

WhoAmI

Type Name Description
String nodeName


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.