Overhide Broker API

Base URL: /broker, Version: 1.0.0, overhide documentation

This is the API contract expected to be exposed by an overhide "broker". This API is represented by the green "broker API" connector in the overhide component model:

overhide component model

Read this API with reference to the glossary.

A note on schemes used in the API.

Operations GET, PUT, POST, DELETE use the HTTPS scheme. These endpoints should be understood as standard REST requests. These configuration/discovery exchanges involve text parameters on the URL line and text/numeric payloads in the JSON representation. They use BASE64 encoding: the BASE64 encoding is explicitly stated.

Operations WIRE are WebSocket events that use a custom wire protocol. The SSL secured WebSockets connection is to the same address as the HTTPS connection. Authentication occurs using HTTPS and seamlessly propagates to the WSS connection.

Wire-protocol events require an additional step of a handshake between client and broker: beyond just being authenticated. Failure to handshake will result in "no handshake" 400-series error codes on wire-protocol events.

Please review the flow-control documentation to understand the WIRE protocol flow-control mechanisms.

A note on the wire-protocol payload notation.

WSS event exchanged payloads are comprised of compact byte streams. In the documentation payloads with byte streams are described as descriptors in the following format:

syntax	bytes	value
foo	2
bar	1	N
for i in N {
baz	4
}

The above indicates that the first 3 bytes are followed by a loop of 4 byte words. The number of iteration is specified by bits 16-23.

All numeric values greater than a byte are sent in network order, big-endian format. The foo above is 2-bytes wide, the first byte having the most significant bits.

Schemes: https, wss

Summary

Tag: capabilities

Discover capabilities of the overhide broker system.

subscription providers
subscription tiers

Operation	Description
GET /capabilities/remuneration-providers	List of remuneration providers supported.
GET /capabilities/{remuneration-key}/tiers	List of subscription tiers available.
GET /capabilities/address	Retrieve this broker's broker-address for the remuneration-provider used by caller's identity.
GET /capabilities/version	Retrieve this broker's API version.

Tag: flow-control

Flow controls include toggles for the client and the broker to agree on message maximums, message fragmentation parameters, as well as acknowledgment and continuation messages for fragments of large payloads.

The various flow-control events are modeled below:

overhide flow-control infographic

Before the client can exchange data with the overhide broker it needs to authenticate and handshake.

The first synchronous HTTPS call is a PUT to /auth/credentials; returning an identity. Subsequently, when the client establishes a Websocket connection with the broker (Websocket connect(identity)) it provides the identity as per WSS Auth.

From this point on the exchanges take place over the Websocket protocol, ursng WIRE events as documented here.

Before any data exchanges can take place, the client communicates its desired fragment and aggregate message parameters using the handshake event. The server agrees--"shakes on it" with a "response" WIRE event having a code of 200/OK.

The client proceeds to send a large datastore-value that is necessairly fragmented into multiple WIRE events. The exchange is started with a set data event. The flags attribute of this set data event does not have the 0x80 bit set: indicating that the payload byte-stream is the first fragment of multiple fragments for the large aggregate message. The broker replies with a "response" WIRE event having a code of 200/OK. The client does not send the subsequent fragment until the broker confirms receipt of the previous fragment with such a "response" WIRE event.

The client sends subsequent fragments using the continue events. Before sending each subsequent fragment the client expects a "response" WIRE event having a code of 200/OK.

The client sends the final fragment with a flags having the 0x80 bit toggled: indicating last fragment sent.

The final exchange modeled is the client retrieving a large payload from the broker. The exchange is initiated with a get data event. The broker responds with a WIRE event having a code of 206/fragment. The client accepts the payload byte-stream as the first fragment of a larger response. The client sends an acknowledge event to the broker; acknowledging receipt of the fragment and freeing the broker to send the subsequent fragment.

The broker does so, looping through the 206-acknowledge exchanges.

When the broker sends the last fragment of the aggregate message byte-stream, it sends it with a code of 200/OK. The client doesn't have to acknowledge this last response as it's not a 206/fragment.

Operation	Description
WIRE handshake	Client initiates handshake with broker.
WIRE continue	Continue sending fragments of a message to a "setter" endpoint of a broker.
WIRE acknowledge	Acknowledge receipt of a response fragment from a "getter" endpoint of a broker.
WIRE halt	Halt fragmented sending or receiving.
WIRE watchdog	Check if connection is live.

Tag: data-stewardship

Stewardship of a users's data.

Stewardship of data is important regardless whether an identity opts-in into decentralized storage or not. All but one of these APIs deal with stwardship regardless of decentralization opt-in selected: see opt-in endpoint and segment-key specific opt-in.

These APIs allow a client to:

manage this broker's stewardship mode for an identity's data: active/passive stewardship
manage distributed persistence network particulars for a user
review content propagation status--of user's data and messages--to the distributed persistence network
batch export and import of all user's data and messages

Envisioned use cases include backup and broker transfer including data migration.

The stewardship APIs enable data decentralization and broker trustlessness.

Each use case below is accompanied by a sequence diagram with the following markup:

messages in red are API calls detailed in this section
blue messages are external calls outside of overhide broker API but dealing with overhide managed data
green messages are messages dealing with broker-lookup; broker-lookup availability is assumed in the use cases
other API calls are indicated for context and glanced over

Sample Use Case: Designation of Stewards

Consider the following sequence modelling overhide API calls required to associate user data with two overhide brokers; one designated as an active data steward and one designated to be a passive data steward.

overhide designation of stewards infographic

In this sequence the client subscribes to broker 1 and authenticates [1]. It's important to note that the first time a new user authenticates to a broker a new set of GUIDs is generated pointing to the user's data on the broker's distributed persistence network (e.g. IPFS "names" PKI pair for IPFS).

At this point broker 1 is read-only. Any attempts to write data or post messages would yield a 400 -- "cannot write, broker not an active steward of user's data". To make the broker writable, it's designated as an active data steward [3].

When participating in broker-lookup the PUT /active-stewardship call--to make broker 1 an active data steward--requires we know the broker's host name (or IP). The PUT /active-stewardship call is the mechanism that registers the broker as a user's active broker; hence the necessary signing of the particular metadata to push into the broker-lookup network. Step [2] retrieves the broker's hostname for signing and pushing into the method [3].

The client writes then reads data as desired [5]. The data is eventually made consistent with the distributed persistence network (e.g. IPFS) [5.1].

Presumably the distributed persistence network backing broker 1 is a public decentralized data-store that allows common tooling access [7]. To access the client's data we need its reference. The reference is retrieved as a GUID [6].

Another overhide broker is subscribed to by the client--to guarantee pinning of the user's data as a backup [8].

At this point broker 2 is subscribed to, but it is not associated with the user's data as referenced by broker 1 [9-10]. The second broker has a compeltelly different GUID for the user's data on the distributed persistence network.

Once the client furnished the GUID form broker 1 to broker 2 [11], broker 2 starts acting as a passive steward of the user's data [12-14].

Sample Use Case: Disassociation from Steward Over Persistence Network With Pour-Active Steward

The user may have a reason to diassociate from an overhide broker. In the following sequence we model the API calls required to disassociate user data from broker 1: including ensuring the disassociated broker cannot clobber any new data and that old user data is not consuming resources on the broker.

This use case leverages broker-lookup and a distributed persistence network (e.g. IPFS) for the migration.

overhide disassociation from steward using persistence network infographic

We start with broker 1 being the active data steward and broker 2 being the passive data steward. Use of broker-lookup with GET /broker-lookup [1] indicates broker 1 as the activeBrokerHost to the client. The client works with broker 1 [2] and broker 2 is eventually consistent via the distributed persistence network [2.1,2.1.1].

Before continuing we verify that broker 2 (passive) is synching to the data from broker 1 [3,4]. If both brokers return the same GUID we know they're working with the same data.

We prevent any further writes to broker 1 by making it passive [5].

We put broker 2 into a special "pour-active" mode [6]. A "pour-active" data-steward is an "active" data-steward with special caveats to allow for consistency during data migration. Enabling "pour-active" mode on a broker is a temporary measure before transitioning to "active" mode.

Putting broker 2 into "pour-active" mode prompts it to tell the broker-lookup network that broker 1 is now the drainBrokerHost and that broker 2 is the new activeBrokerHost [6.1].

The client discovers that state of the hosts [7] and continues to use the brokers in tandem, uninterrupted [8,9]. The reads on both brokers [8,9] respect the decision matrix as per result code 246. Reads against broker 2 could return result code 422 when a segment-key is not yet available. Writes on broker 1 are disallowed with result code 400 -- "cannot write, broker not an active steward of user's data". Writes to broker 2 [8] proceed as usual except are not synched with the distributed persistence network (while in "pour-active" mode).

While the user is accessing the brokers in tandem, broker 2 is busy finalizing it's eventual consistency with the distirbuted persistence network. Data access and migration are occuring at the same time: ovrehide broker 2 accepts distributed persistence network data changes for all segment-keys not already overwritten via an explicit API write.

[11] and [12] check to see if syching data over the distributed persistence network is finished. Once done, we can make broker 2 a standard active steward [13]. The change to the broker's stewardship mode is reflected in the broker-lookup [13.1].

At this point broker 1 is a passive steward for the user's data. But since we set out to migrate to broker 2 and disassociate the user's data from broker 1; now that the migration is done we tell broker 1 to delete the data and stop synching [14].

The user continues to use the client to access their data [15-16.1].

Sample Use Case: Client Driven Export+Fill With Pour-Active Steward

In the previous use case we model data migration over a distributed persistence network. In that case we require all data to be migrated to be opted-in into distributed persistence.

In this use case we accomplish the same migration over-the-top without use of a distributed persistence network. This works for all your data; opted-in and not.

overhide disassociation from steward using export+fill infographic

The use case starts with broker 1 as the active broker and broker 2 is not in the picture. The client works with broker 1 [1,2].

When the user decides to switch brokers of their data, they use the client to subscribe to broker 2 [3].

Switching stewardship modes is done in quick succession to avoid interruption [4-5.1]. We now have broker 2 in pour-active mode and broker 1 as a passive steward.

Putting broker 2 into "pour-active" mode prompts it to tell the broker-lookup network that broker 1 is now the drainBrokerHost and that broker 2 is the new activeBrokerHost [5.1].

The client discovers that state of the hosts [6] and continues to use the brokers in tandem, uninterrupted [7,8]. The reads on both brokers [7,8] respect the decision matrix as per result code 246. Reads against broker 2 could return result code 422 when a segment-key is not yet available. Writes on broker 1 are disallowed with result code 400 -- "cannot write, broker not an active steward of user's data". Writes to broker 2 [7] proceed as usual.

While the user is accessing the brokers in tandem, the client is used to export data out of broker 1 [9] and fill the data into broker 2 [10]. The fill operation is an over-the-top alternative to indiscriminate importing: the fill operation does not overwrite exitsting segment-keys on broker 2. This, in combination with the result codes describe in the previous paragraph, allows for over-the-top migration of user's data while the user continues to access their data via the client.

At the end the user deletes their data from [12] and continues to access data with broker 2 [13,14].

Sample Use Case: Client Driven Export+Import

The previous two use cases described data migration with minimal interruption to user's access to their data.

For completeness, this use case describes the most basic over-the-top data migration that does interrupt the user's access to their data. This use case is likely practical when a single user is migrating their data and they're fine waiting for their data to export and import before continuing to use it. Contrast this to the previous use cases--which are likely more practical when the data migrating user is a service provider--whose data is being accessed by many other users (e.g. delegtes) while the migration is in progress.

overhide disassociation from steward using export+import infographic

The sequence is similar to the previous use cases with two notable differences. First difference being the ERROR in writing data during the migration [6]. Second difference being the import call [9]. This call clobbers all data on broker 2 with the import payload.

Operation	Description
WIRE import	Indiscriminately Set all user's data on the broker system.
WIRE fill	Discriminately set all user's data on the broker system.
WIRE export	Extract all user's data from the broker system.
POST /opt-in-data/{type-key}/{guid}	Set all user's opt-in data from a connected persistence network.
DELETE /opt-in-data	Delete all user's data on the broker system.
PUT /active-stewardship	Make this broker an active-steward of the user's data.
DELETE /active-stewardship	Make this broker a passive-steward of the user's data
PUT /pour-active-stewardship	Put this broker into active-steward mode for data migration.
GET /{segment-key}/persistence-status	Retrieve content hashes at different memory levels.
PUT /guids	Generate new GUIDs for user's data.
GET /guids	Retrieve GUIDs to user's data on connected persistence networks.
GET /latest-snapshot-id/{guid}	Get latest sync-point with persistence network.

Tag: broker-lookup

Allow services to discover users' specific broker host names and IPs through user-addresses.

Broker-targetting metadata is set into the broker-lookup network via whichever broker enters active steward mode on behalf of the user with either:

PUT /active-stewardship
PUT /pour-active-stewardship

As such broker-lookup works in conjunction with data-stewardship APIs and data-stewardship benefits greatly from broker-lookup.

broker-lookup sequence

These APIs are optionally implemented by brokers. The user's active broker and the broker used to resolve a lookup (perhaps one and the same) need to support broker-lookup with all the supported remuneration-keys: i.e. these APIs cannot return 405 -- "Method Not Allowed".

Read more on broker-lookup in the reference implementation write-up and read-through the data-stewardship use cases.

Operation	Description
GET /broker-lookup/{user-address}	Resolve user-addres to broker host name or IP.
PUT /broker-lookup	Set broker-lookup entry.

Tag: auth

Authentication, authorization, and credential management:

authenticate providing an access token: authenticate subscribers of the system and invitees of subscribers of the system.
work with authority levels.
opt-in persistence network storage
change identity credentials. Setting identity for the first time is done with the authenticate endpoint.
work with subscription details for a supported remuneration API and a given identity.

Operation	Description
PUT /auth/credentials	Authenticate an identity returning a token.
GET /auth/authorities	Retrieves authorities for an identity.
PUT /auth/guest-credentials	Authenticate an invitee's user-address as a guest of a subscriber's user-address.
PUT /auth/changed-credentials	Change authentication of token's user.
PUT /auth/opt-in/{agree}	Opt-in to store all data for an identity via the broker's decentralized persistence.
GET /auth/{remuneration-key}/{from-address}/{to-address}/transactions	Retrieve remuneration transactions.

Tag: subletting

Subletting is one of two features allowing for services where a service's user isn't forced to participate in remunerating the broker. The other such feature is delegates. Read more about subletting in the delegates and subletting write-up

These APIs allow a subscriber (some user) to transfer some of their storage quotas for the benefit of a subtenant (another user).

Unlike delegates, the subtenant fully owns and controls this data.

A subtenant can access this data as long as they satisfy all constraints enumerated in the PUT /sublet method or the subtenant becomes a regular subscriber of this broker.

Operation	Description
GET /sublet	Get existing "sublet" arrangement.
PUT /sublet	Set a "sublet" arrangement.
DELETE /sublet	Delete a "sublet" arrangement.

Tag: data

Data key-value CRUD operations; modifying data values in datastore-keys.

Operation	Description
WIRE set data	Set value of datastore-key.
WIRE get data	Get value of datastore-key.
WIRE delete data	Delete datastore-key.

Tag: backchannel queues

Publishing messages to backchannel queues, subscribing to notifications, and de-queueing the messages.

Operation	Description
WIRE post message	Enqueue a message to a given datastore-key backchannel.
WIRE fetch messages	Retrieve all messages from the backchannel at the givent datastore-key.
WIRE acknowledge messages	Acknowledge all messages with timestamps up to and including a specified unixtime-millis for given datastore-key.
WIRE subscribe	Owner--identified in token--subscribes to notifications of new messages in datastore-key.

Tag: delegate

Delegates are one of two features allowing for services where a service's user isn't forced to participate in remunerating the broker. The other such feature is subletting. Read more about delegation in the delegates and subletting write-up

Delegate data stored by a segment-key is meant to be accessed by a user who doesn't own the segment-key.

Delegate enabled segment-keys partition their storage. Each partition is separate and accessible by an identity that is different from the owner of the segment-key.

Each delegate keeps their data completely separate from other delegates under the same segment-key.

Backchannel-queues may also be partitioned by delegate: these backchannel-queues are qualified via delegate query parameters on the backchannel endpoints and are not explicitly listed here.

Delegated data continues to be owned by the segment-key owner--it's a chunk of the owner's data they allot for use by visiting users. The delegate feature provides visiting users a way to access this data.

Operation	Description
WIRE set delegate data	A delegate sets their specific value under this datastore-key.
WIRE get delegate data	A delegate retrieves their specific value under this datastore-key.
WIRE delete delegate data	A delegate deletes their specific data under this datastore-key.
WIRE get all delegate values	Retrieves all delegate data under segment-key as map of delegate identities to content.

Tag: datastore-key settings

Setting access metadata for datastore-keys.

write rights
publish rights
delegate access rights
entry-fee: minimum remuneration to access
read/write limits
opt-in for decentralized storge

Sample Use Case: Service Provider Requiring Authorization via entry-fee

Setting entry-fee gates on segment-keys is a mechanism to require payment from users of those segment-keys.

Service providers set minimum entry-fees on some segment-keys that their service or application requires as part of their functional flow.

Any user, whether authorized as a subscriber or visitor, have their ledger-of-choice checked for existing transactions from themselves to the service provider. The tally of transactions within an entry-fee gate established period of time must be at least equal to the entry-fee requirement to gain access (read, write, publish, subscribe).

This entry-fee requirement enables a service provider to leverage the simple ledger-based authorization flow via overhide brokers.

Operation	Description
PUT /{segment-key}/settings	Setup settings for given datastore-key (segment-key @ identity).
GET /{segment-key}/settings	Returns settings for a given datastore-key.

Tag: metrics

Usage metrics for specific datastore-keys or overall for the identity.

Operation	Description
GET /metrics	Returns metrics for all datastore-keys owned by an identity.
GET /{segment-key}/metrics	Returns metrics for a given datastore-key.
WIRE segment-keys	Retrieve key-names of all segment-keys owned by an indentity.

Security

Authorization Header

Type: apiKey

Name:: Authorization
In:: header
Description:: Provides an authentication token as retrieved with either the authentication endpoint or the invitee credentials endpoint.

The token returned by either call must be provided in an "Authorization" header to HTTPS calls secured with this security definition.

The tokens are whitelisted by the overhide broker until revoked or expired (at broker's purview).

The token contains the identity--hashed in implementation specific ways--to help with access control for the rest of the API.

Details in the identity write-up.

Authorization WSS

Type: apiKey

Name:

auth

In:

query

Description:

Provides an authentication token as retrieved with either the authentication endpoint or the invitee credentials endpoint.

For WSS, the token must be provided when establishing the connection:

  WebSocket = require 'ws'
  ws = new WebSocket 'ws://localhost:8000',{
    headers : {
      token: "..."
    }
  }

Token details are same as per the Authorization Header security scheme.

Paths

Make this broker a passive-steward of the user's data

DELETE /active-stewardship

Tags: data-stewardship

All of the user's data with caller's identity is now under this broker's passive-stewardship.

Data--as available on the distributed persistence network--will be pinned/hosted by this broker. It will be eventually consistent with data as written to an active-steward on the network.

Data writes are prohibited to passive-stewards.

200 OK

Stewardship status change successful.

403 Forbidden #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Make this broker an active-steward of the user's data.

PUT /active-stewardship

Tags: data-stewardship

All of the user's data with caller's identity is now under this broker's active-stewardship.

Once activated, the user can write data to their datastore-keys.

Stops pulling updates from decentralized storage and starts pushing updates to decentralized storage.

This call is idempotent: call this to change from pour-active-stewardship.

WARNING: having more than one "active" data-steward may lead to write race-conditions on the distributed persistence network with unknown consequences.

application/json

Activation parameters.

broker-address-signed: string

BASE64 encoded.

The broker-address on the reumneration-provider matching caller's identity--as provided by /capabilities/address--signed with the private key corrsponding to the user-address of identity.

Signature algorithm is remuneration-key specific; for Ethereum it's keccak-256, for Bitcoin it's secp256k1. Refer to the ledger's remuneration API.

Providing this parameter signals we want to advertise this broker as the caller's user-address' activeHost to the lookup network corresponding to the remuneration-key used for this identity.

If the lookup network currently has a drain-host entry, the drain-host entry is removed from the lookup network.

200 OK

Stewardship status change successful.

400 Bad Request

Bad request:

invalid signature
cannot process input

403 Forbidden #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Retrieves authorities for an identity.

GET /auth/authorities

Tags: auth

Retrieve authorities for an identity. Authorities are rates and limits as specified by the Authorities return object.

If an identity has multiple transactions with a reumneration provider, the transactions are added to yield the best service tier.

Authorities are valid for the duration of the security token.

See identities write-up for more information.

application/json

200 OK: Authorized rates and limits are returned.

Authorities
401 Unauthorized #/responses/401: For an endpoint protected with the token security definition, an "Authorization" header was not provided a valid token--as returned from the authenticate endpoint.
429 Too Many Requests #/responses/429: Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Change authentication of token's user.

PUT /auth/changed-credentials

Tags: auth

application/json

New authentication credentials for user indicated by the identity in the security header.

NOTE: If the user's data is tracked by multiple brokers the user's identity has to be changed on all data-stewards of the user's data. Changing identity on one data-steward and failing to do same on the rest yields brokers that track stale data.

new-remuneration-key: string

Key from remuneration-providers which contains subscription payment(s) from the provided new-user-address to this broker's broker-address.

Must be one of the remuneration provider keys from this broker's capabilities.

new-secret-phrase: string

BASE64 Encoded.

A new secret phrase for the new user-address. Once credentials are changed successfully; the new-secret-phrase is tied to the new-user-address indefinitely, unless changed again by changed-credentials.

new-user-address: string

A public user-address to verify an active subscription to this broker's broker-address.

Must be a valid address with the remuneration provider indicated in new-remuneration-key.

A valid address is an address on an accepted remuneration provider that is involved in some transaction on that ledger.

new-secret-phrase-signed: string

BASE64 encoded.

The new-secret-phrase provided above signed with the private key corrsponding to the new-user-address.

Signature algorithm is remuneration-key specific; for Ethereum it's keccak-256, for Bitcoin it's secp256k1. Refer to the ledger's remuneration API.

200 OK

Credentials successfully changed.

400 Bad Request

Bad request:

invalid remuneration-key, doesn't match broker system capabilities
address incompatible with remuneration provider
invalid signature
invalid secret-phrase
cannot process input

401 Unauthorized #/responses/401

For an endpoint protected with the token security definition, an "Authorization" header was not provided a valid token--as returned from the authenticate endpoint.

409 Conflict #/responses/409-identity-conflict

Go play a lottery: the generated identity conflicts with some other identity or ended up being a restricted number <10000.

user-address hashed with its secret-phrase must be unique within the system. Another user-address/secret-phrase already in the system hashes to the same hash as the provided user-address/secret-phrase.

Try a different secret-phrase.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Authenticate an identity returning a token.

PUT /auth/credentials

Tags: auth

Authenticate an identity returning a token to be used for token authentication in the rest of the API.

application/json

Authentication parameters.

remuneration-key: string

Key from remuneration-providers which contains subscription payment(s) from the provided user-address to this broker's broker-address.

Must be one of the remuneration provider keys from this broker's capabilities.

secret-phrase: string

BASE64 encoded.

A secret phrase for the specified user-address. Once a user authenticates against the broker with a secret-phrase and a user-address, the secret-phrase is tied to the user-address indefinitely, unless changed by changed-credentials. Using the incorrect scecret-phrase will result in a 400 -- "invalid secret-phrase". (more information)

user-address: string

A public user-address to verify an active subscription to this broker's broker-address.

Must be a valid address with the remuneration provider indicated in remuneration-key.

A valid address is an address on an accepted remuneration provider that is involved in some transaction on that ledger.

secret-phrase-signed: string

BASE64 encoded.

The secret-phrase provided above signed with the private key corrsponding to the user-address.

Signature algorithm is remuneration-key specific; for Ethereum it's keccak-256, for Bitcoin it's secp256k1. Refer to the ledger's remuneration API.

application/json

200 OK

Authentication token is returned to be used in subsequent calls into overhide broker.

400 Bad Request

Bad request:

invalid remuneration-key, doesn't match broker system capabilities
address incompatible with remuneration provider
invalid signature
invalid secret-phrase
cannot process input

402 Payment Required

Payment Required -- Remuneration provider indicates insufficient transactions to the broker system to meet a service tier subscription requirements.

See subscriptions write-up.

409 Conflict #/responses/409-identity-conflict

Go play a lottery: the generated identity conflicts with some other identity or ended up being a restricted number <10000.

Try a different secret-phrase.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.

449

Retry With:

The response body contains a string.

Retry this request with secret-phrase set to the response string and secret-phrase-signed be a signature of the respons string.

Receiving this response is dependent on broker-specific heuristics. The broker may challenge the client with this response (always, sometimes, never).

Authenticate an invitee's user-address as a guest of a subscriber's user-address.

PUT /auth/guest-credentials

Tags: auth

Authenticate an invitee's user-address as a guest of a subscriber's user-address.

An invitee into the system must provide a valid address on an accepted remuneration provider. An invitee must prove ownership of said valid address.

A valid address is an address on an accepted remuneration provider that is involved in some transaction on that ledger.

Transactions--on a supported remuneration-provider--from the invitee-user-address to the provided inviter-user-address are part of the state of the returned access token by this call. The inviter may set fee expectations on segment-key. If fees paid are expected, the invitee must necessairly have transacted with the inviting subscriber.

The inviting subscriber must expose their user-address and a shared-phrase that's used to hash their user-address into an identity. The shared-phrase is equivalent to the secret-phrase passed into the authenticate endpoint: except it's not kept secret by the inviting user. This is necessary to authorize the invitee to the inviting subscriber, and to ensure the inviting subscriber's user-address does in fact hash to the desired indentity: we don't want to just pass the inviting subscriber's identity, we want to calculate it.

Returns an "invitee" token to be used for token authentication in the rest of the API.

The invitee-user-address hashed by invitee-secret-phrase is the invitee's identity for the purposes of write/publish permissions on segment-key.

application/json

Authentication parameters.

remuneration-key: string

Key from remuneration-providers which contains subscription payment(s) from the provided user-address to this broker's broker-address.

Must be one of the remuneration provider keys from this broker's capabilities.

shared-phrase: string

BASE64 Encoded.

A shared phrase by the inviter to the invitee for the specified inviter-user-address. The shared-phrase and the inviter-user-address must compute to an authorized identity on the system. This is the identity inviting the invitee.

inviter-user-address: string

A public user-address to verify an active subscription to this broker's broker-address.

Must be a valid address with the remuneration provider indicated in remuneration-key.

A valid address is an address on an accepted remuneration provider that is involved in some transaction on that ledger.

Used in combination with shared-phrase, see shared-phrase above.

invitee-secret-phrase: string

BASE64 Encoded.

A secret phrase for the specified invitee-user-address.

The broker shall allow the same invitee-user-address to be used with multiple different invitee-secret-phrases. The broker can hash the invitee-user-address in a broker-specific way and make this hashed version available in the visitor's authentication token for use with this API: for duplicate delegate-identity checks. The hashed invitee-user-address is not stored off outside the broker's metadata (i.e. on the distributed persistence network).

invitee-user-address: string

A public user-address, must be a valid address with the remuneration provider indicated in remuneration-key.

A valid address is an address on an accepted remuneration provider that is involved in some transaction on that ledger.

Transactions from this address to inviter-user-address are stored in the returned access token to check fees on invitee-accessed segment-key.

invitee-secret-phrase-signed: string

BASE64 encoded.

The invitee-secret-phrase provided above signed with the private key corrsponding to the invitee-user-address.

Signature algorithm is remuneration-key specific; for Ethereum it's keccak-256, for Bitcoin it's secp256k1. Refer to the ledger's remuneration API.

application/json

200 OK

Invitee authentication token is returned to be used in subsequent calls into overhide broker.

400 Bad Request

Bad request:

invalid remuneration-key, doesn't match broker system capabilities
address incompatible with remuneration provider
invalid signature
invalid secret-phrase
cannot process input

402 Payment Required

Payment Required -- Remuneration provider indicates no transactions exist between the user addresses in parameters.

See subscriptions write-up.

409 Conflict #/responses/409-identity-conflict

Go play a lottery: the generated identity conflicts with some other identity or ended up being a restricted number <10000.

Try a different secret-phrase.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.

449

Retry With:

The response body contains a string.

Retry this request with invitee-secret-phrase set to the response string and invitee-secret-phrase-signed be a signature of the respons string.

Receiving this response is dependent on broker-specific heuristics. The broker may challenge the client with this response (always, sometimes, never).

Opt-in to store all data for an identity via the broker's decentralized persistence.

PUT /auth/opt-in/{agree}

Tags: auth

Opt-in to store all data for an identity via the broker's decentralized persistence.

By default all data for an identity is stored on this broker's local persistence.

Unless opted-in, data is not decentralized: it does not end up on the broker's decentralized persistence.

For fine-grained control you may instead selectivelly opt-in each key segment-key.

You can still inspect all your data; import or export it manually.

To automatically make all of an identity's data eventually consistent with the decentralized persistence network, ensure to opt-in that identity with this endpoint.

application/json

agree


agree	Truthy string such as 'true' matching the regex `/t/i` will opt-in. To opt-out send in a falsey string such as 'false' not matching that regex. All data for authenticated identity will be opted in.	path	string

Truthy string such as 'true' matching the regex /t/i will opt-in. To opt-out send in a falsey string such as 'false' not matching that regex.

All data for authenticated identity will be opted in.

path

string

200 OK

Opt-in changed.

400 Bad Request

Bad request:

cannot process input

401 Unauthorized #/responses/401

For an endpoint protected with the token security definition, an "Authorization" header was not provided a valid token--as returned from the authenticate endpoint.

409 Conflict #/responses/409-identity-conflict

Go play a lottery: the generated identity conflicts with some other identity or ended up being a restricted number <10000.

Try a different secret-phrase.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Retrieve remuneration transactions.

GET /auth/{remuneration-key}/{from-address}/{to-address}/transactions

Tags: auth

Retrieve the latest remuneration transactions on remuneration-key from from-address to to-address


remuneration-key	Key from remuneration-providers which contains payment(s) from the provided from-address to the provided to-address. Must be one of the remuneration provider keys from this broker's capabilities.	path	string
from-address	A public address from which to verify payment details (amount/date) to the to-address. Must be a valid address from the remuneration provider indicated in remuneration-key. A valid address is an address on an accepted remuneration provider that is involved in some transaction on that ledger.	path	string
to-address	The target public address to check for payment made. Must be a valid address from the remuneration provider indicated in remuneration-key. A valid address is an address on an accepted remuneration provider that is involved in some transaction on that ledger. This could be this broker system's public payment address with the reumneration provider (as retrieved via remuneration provider). This could be any other public address furnished by the remuneration provider, e.g. the service's public address: to check for app purchase etc.	path	string
max-most-recent	Number of most recent transactions to retrieve.	query	integer
since	Retrieve transactions since this date-time (inclusive) until now. The date-time is a string in ISO 8601/RFC3339 format.	query	string

application/json

200 OK

List of transactions.

Transaction

400 Bad Request

Bad request:

invalid remuneration-key, doesn't match broker system capabilities
address incompatible with remuneration provider
cannot process input

401 Unauthorized #/responses/401

For an endpoint protected with the token security definition, an "Authorization" header was not provided a valid token--as returned from the authenticate endpoint.

409 Conflict #/responses/409-identity-conflict

Go play a lottery: the generated identity conflicts with some other identity or ended up being a restricted number <10000.

Try a different secret-phrase.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Set broker-lookup entry.

PUT /broker-lookup

Tags: broker-lookup

Set broker-lookup entry.

The user-address and remuneration-key to be set into the broker-lookup are taken from the calling identity as per the authorized token passed in.

application/json

Lookup parameters.

active-broker-address-signed: string

BASE64 encoded.

Signature of this brokers address as retrieved with GET /capabilities/address.

The broker's address is signed by the calling identity's user-address.

The signing user-address and the signed broker's address must be for ledger corresponding to remuneration-key of calling identity.

Signature algorithm is remuneration-key specific; for Ethereum it's keccak-256, for Bitcoin it's secp256k1. Refer to the ledger's remuneration API.

drain-broker-host: string

A host name or IP of a broker we want to advertise as the drain-host: this can be retrieved with GET /capabilities/address on the origin passive steward.

drain-broker-host-signed: string

BASE64 encoded.

Signature of the above drain-broker-host.

Must be signed by the calling identity's user-address.

The signing user-address must be for ledger corresponding to remuneration-key of calling identity.

Signature algorithm is remuneration-key specific; for Ethereum it's keccak-256, for Bitcoin it's secp256k1. Refer to the ledger's remuneration API.

200 OK

Set OK.

400 Bad Request

Bad request:

address incompatible with remuneration provider
invalid signature
cannot process input
cannot write, broker not an active steward of user's data
- check broker-lookup to find active steward and write there
cannot continue, invalid stewardship mode

405 Method Not Allowed #/responses/405

Method not allowed.

The broker-lookup subsystem is not provided/enabled by this broker.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Resolve user-addres to broker host name or IP.

GET /broker-lookup/{user-address}

Tags: broker-lookup

Resolve a user-address (from a supported ledger as per remuneration-keys) into a broker host name or IP.

The returned broker information points to the user's currently active steward and drain-host, if any.


user-address	A public user-address whom to lookup. Must be a valid address with one of the supported ledgers. A valid address is an address on an accepted remuneration provider that is involved in some transaction on that ledger.	path	object

user-address

A public user-address whom to lookup.

Must be a valid address with one of the supported ledgers.

A valid address is an address on an accepted remuneration provider that is involved in some transaction on that ledger.

path

object

application/json

200 OK

Returns broker information for the user-address:

{
  "address": "..",      
  "remunerationKey": "..",
  "activeBrokerAddress": "..",       
  "activeBrokerAddressSigned": "..", 
  "activeBrokerHost": "..",
  "activeBrokerHostSigned": "..",    
  "drainBrokerHost": "..",
  "drainBrokerHostSigned": "..",
  "timestamp": "..",
  "timestampSignedByAddress": "..",
  "timestampSignedByActiveBrokerAddress": ".."
}

address is the user-address.
remunerationKey is one of the supported remuneration-keys.
activeBrokerAddress is the broker-address of the active steward.
activeBrokerAddressSigned is activeBrokerAddress signed by address
- since address signs activeBrokerAddress, only the owner of this user-address can update their active steward's broker-address.
activeBrokerHost is the host name or IP of active steward broker.
- this is the host name or IP to use for the rest of these API calls.
activeBrokerHostSigned is activeBrokerHost signed by activeBrokerAddress
- since activeBrokerAddress signs activeBrokerHost, the active steward can change the host name or IP without involving the user.
- this indirection is useful for load-balancing and other operations aspects of the broker.
drainBrokerHost is the host name or IP of the drain-host, if any.
drainBrokerHostSigned is drainBrokerHost signed by address
- since address signs drainBrokerHost, only the owner of this user-address can update their drain-host.
timestamp when information was published into broker-lookup network
- ISO 8601/RFC3339 format
timestampSignedByAddress is timestamp signed by address
- must be present and valid if timestampSignedByActiveBrokerAddress is not present and valid.
timestampSignedByActiveBrokerAddress is timestamp signed by activeBrokerAddress
- must be present and valid if timestampSignedByAddress is not present and valid.

404 Not Found #/responses/404-cannot-resolve

Cannot resolve address.

405 Method Not Allowed #/responses/405

Method not allowed.

The broker-lookup subsystem is not provided/enabled by this broker.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.

Retrieve this broker's broker-address for the remuneration-provider used by caller's identity.

GET /capabilities/address

Tags: capabilities

Retrieve this broker's broker-address for the remuneration-provider used by caller's identity.

text/plain

200 OK: This broker's broker-address for the remuneration-provider used by caller's identity.
429 Too Many Requests #/responses/429: Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.

List of remuneration providers supported.

GET /capabilities/remuneration-providers

Tags: capabilities

Mapping of remuneration providers to the broker's public address for given provider.

application/json

200 OK: Array of objects each defining one remuneration provider mapping.

RemunerationProvider
429 Too Many Requests #/responses/429: Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.

Retrieve this broker's API version.

GET /capabilities/version

Tags: capabilities

Retrieve this broker's API version.

text/plain

200 OK: This broker's API version as: implementation:version:qualifier.

implementation is a tag identifying broker instance implementer (brand).

version is overhide version implemented (version of this document).

qualifier is a version qualifying tag (e.g. wip, alpha, beta, dev, stable).
429 Too Many Requests #/responses/429: Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.

List of subscription tiers available.

GET /capabilities/{remuneration-key}/tiers

Tags: capabilities

List of subscription tiers available for this broker from a given remuneration provider.


remuneration-key		path	object

application/json

200 OK

Array of objects each defining one remuneration tier mapping.

RemunerationTier

400 Bad Request

Bad request:

invalid remuneration-key, doesn't match broker system capabilities

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.

Retrieve GUIDs to user's data on connected persistence networks.

GET /guids

Tags: data-stewardship

Returns the GUIDs pointing to persisted data for the identity. This broker must be the owner of whatever private metadata is necessary to furnish data to the persistence network at said GUID.

This getter works in conjunction with the opt-in-data import POST setter for data pinning/distribution.

application/json

200 OK

List of type-key, GUID pairs. Each GUID is mapped to a type-key.
A type-key identifies the type of persistence network the GUID is for.

GUID

403 Forbidden #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Generate new GUIDs for user's data.

PUT /guids

Tags: data-stewardship

Replace current GUIDs by new generated GUIDs. Tie the new GUIDs to the authenticated identity making this call.

All data owned by the identity on the corresponding distributed persistence network--as per the provided current GUID--is tied to the new GUIDs.
New GUIDs are initialized by the broker and bound by this broker to the user.

This operation is useful to ensure no other broker can alter your data after a broker transfer. All other stewards of your data will need to be made aware of the GUID change.

If this broker is not an active steward of data for identity, call fails with a 400 -- "cannot write, broker not an active steward of user's data". Note that pour-active-stewards are considered passive stewards for this call.

application/json

200 OK

List of new GUID pairs. Only GUIDs corresponding to the parameter GUID are returned: this might be a subset of all user's GUIDs on the broker.

GUID

403 Forbidden #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Get latest sync-point with persistence network.

GET /latest-snapshot-id/{guid}

Tags: data-stewardship

Get persisntence network (GUID) specific identifier of latest sync-point between broker and persistence network.

For active brokers this is an identifier of the latest write to persistence network.

For passive (and pour-active) brokers this is the identifier of the latest snapshot on persistence network that was fully synced to the broker

This getter works in conjunction with the opt-in-data import POST setter for data pinning/distribution.


guid	A GUID as returned by GET/guids on this broker.	path	string

test/plain

200 OK

The identifier.

400 Bad Request

Bad request:

cannot process input

403 Forbidden #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Returns metrics for all datastore-keys owned by an identity.

GET /metrics

Tags: metrics

Returns overall metrics for all datastore-keys (segment-keys @ identity) owned by an identitiy.

application/json

200 OK

Metrics for all datastore-keys (segment-keys @ identity) of the user.

Metrics

246 #/responses/246

Inconclusive - check other broker for newer data.

The 246 status code has the same structure as a 200/OK and indicates success, but requires caller to second-guess this result.

It is always returned by getter calls on:

passive hosts in cases where an active host would return a 200/OK.
pour-active-stewardship hosts when request is for data in a segment-key that hasn't been explicitly written to via data or backchannel APIs. Once a segment-key is written to by one of these APIs--since the broker was put into pour-active-stewardship mode for an identity--the pour-active-steward will return a 200/OK.

Upon receipt of a 246 status code as a response to a getter call the client must check whichever complementary broker is reported by broker-lookup--if any. A complementary broker to an active pour host is the passive drain host and vice versa.

Once both complimentary hosts--reported by broker-lookup--respond with a value and a status code, consult the following decision matrix as to which broker's value to use :

	200/OK from ACTIVE (pour)	246/Inconclusive from ACTIVE (pour)	422/Unprocessable from ACTIVE (pour)	246/Inconclusive from PASSIVE (drain)	ERROR from PASSIVE (drain)	PASSIVE (drain) not set
200/OK from ACTIVE (pour)	X	X	X	use ACTIVE's value	use ACTIVE's value	use ACTIVE's value
246/Inconclusive from ACTIVE (pour)	X	X	X	use PASSIVE's value	use ACTIVE's value	use ACTIVE's value
422/Unprocessable from ACTIVE (pour)	X	X	X	use PASSIVE's value	ERROR	ERROR
246/Inconclusive from PASSIVE (drain)	use ACTIVE's value	use PASSIVE's value	use PASSIVE's value	X	X	X
ERROR from PASSIVE (drain)	use ACTIVE's value	use ACTIVE's value	ERROR	X	X	X
PASSIVE (drain) not set	use ACTIVE's value	use ACTIVE's value	ERROR	X	X	X

The decision which broker's value to use as source of truth depends on their returned status codes.

403 Forbidden #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

404 Not Found #/responses/404-datastore-key

Invalid datastore-key requested; segment-key or identity mismatch.

422 Unprocessable Entity #/responses/422

Unprocessable - not filled yet, check draining host for data.

When a getter method called on a pour-active-steward doesn't find a segment-key for an identity it returns this status code instead of a 400/BAD-REQUEST (with "invalid datastore-key requested; segment-key or identity mismatch" for the reason).

Upon receipt of a 422 status code as a response to a getter call the client must attempt the getter call with the complementary draining passive broker as reported by broker-lookup--if any.

Refer to write-up on the 246 status code for a decision matrix as to what the client should do.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Delete all user's data on the broker system.

DELETE /opt-in-data

Tags: data-stewardship

Delete all user's data on the broker system, based on identity passed in.

Broker can be in any stewardship mode.


wait-until-persisted	Optional request to synchronously block result until change to datastore-key is persisted.	query	boolean
wait-until-shared	Optional request to synchronously block result until change to datastore-key is shared on distributed persistence network.	query	boolean

200 OK

If all data is deleted.

400 Bad Request

Bad request:

cannot process input

403 Forbidden #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Set all user's opt-in data from a connected persistence network.

POST /opt-in-data/{type-key}/{guid}

Tags: data-stewardship

For all segment-key available on the decentralized persistence, data in this broker's segment-key is wiped and reset to data available at the same identity on the specificed persistence network. The network data is identified by the provided GUID. The broker must be able to exchange data on the network that's identified by type-key.

This message can only be called on a passive or pour-active steward. Calling this message on an active steward will result in error code 400 -- "cannot continue, invalid stewardship mode".

Note that the only segment-key imported are ones explicitly opted-in on some active steward (other than this steward) with either the opt-in endpoint or the segment-key specific opt-in.

This setter works in conjunction with the GUIDs getter, which is to be called against the source broker instance. The source broker is a broker currently furnishing the data to the network.

If transferring a segment-key with a public restricted identity (0 .. 9999), if the segment-key already exists at provided identity for a different owner, the message call fails with a 409 -- "datastore-key ownership conflict; segment-key @ identity already reserved".

If the type-key requested is not supported by this broker system the message call fails with a 400 -- "invalid type-key, doesn't match broker system capabilities".

If data from the remote GUID cannot be extracted or in otherwise unavailable the message call fails with a 502 -- "cannot reach data".

If the payload from the other broker is malformated and cannot be imported the message call fails with a 400 -- "cannot process input", followed by additional optional verbiage.

application/json


type-key	A type-key as per enumertion.	path	string
guid	A GUID on the type-key network of the source of import data. Retrieve this using GUIDs getter on the exporting broker instance.	path	string

200 OK

Data successfully set.

400 Bad Request

Bad request:

invalid type-key, doesn't match broker system capabilities
cannot process input
cannot write, broker not an active steward of user's data
- check broker-lookup to find active steward and write there
cannot continue, invalid stewardship mode

403 Forbidden #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.

502 Bad Gateway #/responses/502

Cannot reach data.


Authorization Header

Put this broker into active-steward mode for data migration.

PUT /pour-active-stewardship

Tags: data-stewardship

All of the user's data with caller's identity is now under this broker's active-stewardship with caveats:

getter methods will return 246/Inconclusive on successful reads of segment-key that weren't explicitly written to: see response status code 246. This is important for continuity of data-access during migrations:
1. finishing up any persistence storage network synchronization from a previously active-steward before making this broker a regular active-steward. See data-stewardship for use-cases.
2. allowing for time-consuming explicit export from a previously active-steward and explicit fill of this broker; before making this broker a regular active-steward. See data-stewardship for use-cases.
accepts decentralized storage data changes until an explicit API write to a segment-key:
- overwrites data in that segment-key as usual (see response code *246)
- causes the segment-key to stops being overwritten by decentralized storage changes
- causes the segment-key to start returning 200/OK on getter methods instead of 246/Inconclusive

Once activated, the user can write data to their datastore-keys.

Ensures updates from decentralized storage continue to be pulled; does not push updates to decentralized storage.

This call is idempotent: call this to change from passive or active stewardship.

Note that this pour-active stewardship mode is complementary with the fill endpoint when not leveraging distributed persistence.

When in this pour-active stewardship mode--while waiting for persistence network to synchronize data from a passive-steward--this pour-active steward can be safely transitioned to an active steward once the passive-steward and this broker both return the same identifier from GET /latest-snapshot-id.

WARNING: having more than one "active" data-steward may lead to write race-conditions on the distributed persistence network with unknown consequences.

application/json

Activation parameters.

drain-host: string

This parameter can only be provided if drain-host-signed and broker-address-signed are also provided.

This is the host name or IP address of the passive-steward broker we're draining data from into this broker.

This host name or IP address--if properly signed by drain-host-signed--will be pushed to the lookup network corresponding to the remuneration-key used for this identity.

Once the lookup network has this drain-host it can aid all data-access during a migration.

drain-host-signed: string

BASE64 encoded.

This parameter can only be provided if drain-host and broker-address-signed are also provided.

This is the drain-host (provided above) signed with the private key corrsponding to the user-address of identity.

Signature algorithm is remuneration-key specific; for Ethereum it's keccak-256, for Bitcoin it's secp256k1. Refer to the ledger's remuneration API.

broker-address-signed: string

BASE64 encoded.

The broker-address on the reumneration-provider matching caller's identity--as provided by /capabilities/address--signed with the private key corrsponding to the user-address of identity.

Signature algorithm is remuneration-key specific; for Ethereum it's keccak-256, for Bitcoin it's secp256k1. Refer to the ledger's remuneration API.

Providing this parameter signals we want to advertise this broker as the caller's user-address' activeHost to the lookup network corresponding to the remuneration-key used for this identity.

200 OK

Stewardship status change successful.

400 Bad Request

Bad request:

invalid signature
cannot process input

403 Forbidden #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Delete a "sublet" arrangement.

DELETE /sublet

Tags: subletting

Delete a sublet arrangement, if any.

200 OK: If arrangement is deleted or no arrangement existed.
401 Unauthorized #/responses/401: For an endpoint protected with the token security definition, an "Authorization" header was not provided a valid token--as returned from the authenticate endpoint.
429 Too Many Requests #/responses/429: Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Get existing "sublet" arrangement.

GET /sublet

Tags: subletting

Retrieve the existing sublet arrangement for calling subscriber.

application/json

200 OK

Subletting arrangement for subscriber on this broker.

The response payload can be an empty object {} if no subletting arrangement defined.

fees-schedule: object[]

If specified, mandates that before a subletting arrangement can take place during subtenant login, the broker checks for ledger transactions from subtenant to subscriber. This is the fees-schedule dictating permission to access.

object

value: number

Amount of currency--as per remuneration-key required to sublet.

A 0-value implies at least one transaction of any value (perhaps just the ledger transaction fees) must be present.

within-seconds: number

All transactions--on the remuneration provider indicated with remuneration-key--with a timestamp more recent than within-seconds before the time of login, have their amounts tallied and compared to value. If the tally is at least value the fees-schedule is met.

A 0-value means for all-time.

remuneration-key: string

One of the remuneration provider keys from /capabilities/remuneration-providers

The provided address corresponds to one of the remuneration providers, define it.

storage-limit-bytes: number

Maximum number of bytes of total content allowed to be sublet from subscriber to subtenant.

401 Unauthorized #/responses/401

For an endpoint protected with the token security definition, an "Authorization" header was not provided a valid token--as returned from the authenticate endpoint.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Set a "sublet" arrangement.

PUT /sublet

Tags: subletting

Transfer some authorities limits(the sublet arrangement) on this broker from this method caller's identity (the subscriber) to any subtenant satisfying any specified fees-schedule.

Allows a subtenant to authorize into broker to use resources--up to the limits subleted--with their user-address as owner.

This method merely instruments subletting arrangements from this subscriber to any user authorizing as a subtenant. Upon subtenant's next login with PUT /auth/credentials the subletting arrangement--along with any other sublets--is alloted if and only if:

the subtenant meets requirements outlined by the fees-schedule of this call, if any
the subtenant doesn't already have an [active subscription] on this broker
the subtenant doesn't already have an entry in broker-lookup other than this broker
this broker is the subtenant's active steward
the subscriber has an active subscription with a current storage utilization below 1

Notes:

subletting is broker specific, non-transferable.
a user cannot be a subtenant of multiple subscribers on different brokers
- user will need a different user-address for each sublet
- expected response from broker: 400 -- "cannot sublet: already active on another broker"
only a single subletting arrangement can be set per subscriber per broker

application/json

Subletting payload.

fees-schedule: object[]

object

value: number

Amount of currency--as per remuneration-key required to sublet.

A 0-value implies at least one transaction of any value (perhaps just the ledger transaction fees) must be present.

within-seconds: number

A 0-value means for all-time.

remuneration-key: string

One of the remuneration provider keys from /capabilities/remuneration-providers

The provided address corresponds to one of the remuneration providers, define it.

storage-limit-bytes: number

Maximum number of bytes of total content allowed to be sublet from subscriber to subtenant.

200 OK

Data successfully set.

400 Bad Request

Bad request:

invalid remuneration-key, doesn't match broker system capabilities
cannot process input
cannot write, broker not an active steward of user's data
- check broker-lookup to find active steward and write there
cannot continue, invalid stewardship mode
cannot sublet: already active on another broker

401 Unauthorized #/responses/401

For an endpoint protected with the token security definition, an "Authorization" header was not provided a valid token--as returned from the authenticate endpoint.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Returns metrics for a given datastore-key.

GET /{segment-key}/metrics

Tags: metrics

Returns data and backchannel metrics for a given datastore-key (segment-key @ identity).

segment-key

Base64 encoded segment-key.

path

string

identity

Optional identity. If provided, must be one of public restricted identities: 0 .. 9999. If not provided, identity is that of token owner.

See glossary.

query

string

application/json

200 OK

Metrics for this datastore-key (segment-key @ identity).

Metrics

246 #/responses/246

Inconclusive - check other broker for newer data.

The 246 status code has the same structure as a 200/OK and indicates success, but requires caller to second-guess this result.

It is always returned by getter calls on:

passive hosts in cases where an active host would return a 200/OK.
pour-active-stewardship hosts when request is for data in a segment-key that hasn't been explicitly written to via data or backchannel APIs. Once a segment-key is written to by one of these APIs--since the broker was put into pour-active-stewardship mode for an identity--the pour-active-steward will return a 200/OK.

Once both complimentary hosts--reported by broker-lookup--respond with a value and a status code, consult the following decision matrix as to which broker's value to use :

	200/OK from ACTIVE (pour)	246/Inconclusive from ACTIVE (pour)	422/Unprocessable from ACTIVE (pour)	246/Inconclusive from PASSIVE (drain)	ERROR from PASSIVE (drain)	PASSIVE (drain) not set
200/OK from ACTIVE (pour)	X	X	X	use ACTIVE's value	use ACTIVE's value	use ACTIVE's value
246/Inconclusive from ACTIVE (pour)	X	X	X	use PASSIVE's value	use ACTIVE's value	use ACTIVE's value
422/Unprocessable from ACTIVE (pour)	X	X	X	use PASSIVE's value	ERROR	ERROR
246/Inconclusive from PASSIVE (drain)	use ACTIVE's value	use PASSIVE's value	use PASSIVE's value	X	X	X
ERROR from PASSIVE (drain)	use ACTIVE's value	use ACTIVE's value	ERROR	X	X	X
PASSIVE (drain) not set	use ACTIVE's value	use ACTIVE's value	ERROR	X	X	X

The decision which broker's value to use as source of truth depends on their returned status codes.

400 Bad Request

Bad request:

cannot process input

403 Forbidden #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

404 Not Found #/responses/404-datastore-key

Invalid datastore-key requested; segment-key or identity mismatch.

422 Unprocessable Entity #/responses/422

Unprocessable - not filled yet, check draining host for data.

Upon receipt of a 422 status code as a response to a getter call the client must attempt the getter call with the complementary draining passive broker as reported by broker-lookup--if any.

Refer to write-up on the 246 status code for a decision matrix as to what the client should do.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Retrieve content hashes at different memory levels.

GET /{segment-key}/persistence-status

Tags: data-stewardship

Returns content-hashes representing latest content stored at each memory level for a given datastore-key (segment-key @ identity).

segment-key

Base64 encoded segment-key.

path

string

identity

Optional identity. If provided, must be one of public restricted identities: 0 .. 9999. If not provided, identity is that of token owner.

See glossary.

query

string

application/json

200 OK

The content-hashes for the datastore-key (segment-key @ identity).

PersistenceStatus

246 #/responses/246

Inconclusive - check other broker for newer data.

The 246 status code has the same structure as a 200/OK and indicates success, but requires caller to second-guess this result.

It is always returned by getter calls on:

passive hosts in cases where an active host would return a 200/OK.
pour-active-stewardship hosts when request is for data in a segment-key that hasn't been explicitly written to via data or backchannel APIs. Once a segment-key is written to by one of these APIs--since the broker was put into pour-active-stewardship mode for an identity--the pour-active-steward will return a 200/OK.

Once both complimentary hosts--reported by broker-lookup--respond with a value and a status code, consult the following decision matrix as to which broker's value to use :

	200/OK from ACTIVE (pour)	246/Inconclusive from ACTIVE (pour)	422/Unprocessable from ACTIVE (pour)	246/Inconclusive from PASSIVE (drain)	ERROR from PASSIVE (drain)	PASSIVE (drain) not set
200/OK from ACTIVE (pour)	X	X	X	use ACTIVE's value	use ACTIVE's value	use ACTIVE's value
246/Inconclusive from ACTIVE (pour)	X	X	X	use PASSIVE's value	use ACTIVE's value	use ACTIVE's value
422/Unprocessable from ACTIVE (pour)	X	X	X	use PASSIVE's value	ERROR	ERROR
246/Inconclusive from PASSIVE (drain)	use ACTIVE's value	use PASSIVE's value	use PASSIVE's value	X	X	X
ERROR from PASSIVE (drain)	use ACTIVE's value	use ACTIVE's value	ERROR	X	X	X
PASSIVE (drain) not set	use ACTIVE's value	use ACTIVE's value	ERROR	X	X	X

The decision which broker's value to use as source of truth depends on their returned status codes.

400 Bad Request

Bad request:

cannot process input

403 Forbidden #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

404 Not Found #/responses/404-datastore-key

Invalid datastore-key requested; segment-key or identity mismatch.

422 Unprocessable Entity #/responses/422

Unprocessable - not filled yet, check draining host for data.

Upon receipt of a 422 status code as a response to a getter call the client must attempt the getter call with the complementary draining passive broker as reported by broker-lookup--if any.

Refer to write-up on the 246 status code for a decision matrix as to what the client should do.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Returns settings for a given datastore-key.

GET /{segment-key}/settings

Tags: datastore-key settings

Returns data and backchannel settings for a given datastore-key (segment-key @ identity).


segment-key	See glossary.	path	string
identity	Optional identity. If provided, must be one of public restricted identities: 0 .. 9999. If not provided, identity is that of token owner. See glossary.	query	string

segment-key

See glossary.

path

string

identity

Optional identity. If provided, must be one of public restricted identities: 0 .. 9999. If not provided, identity is that of token owner.

See glossary.

query

string

application/json

200 OK

The value of datastore-key (segment-key @ identity).

DatastoreKeySettings

246 #/responses/246

Inconclusive - check other broker for newer data.

The 246 status code has the same structure as a 200/OK and indicates success, but requires caller to second-guess this result.

It is always returned by getter calls on:

passive hosts in cases where an active host would return a 200/OK.
pour-active-stewardship hosts when request is for data in a segment-key that hasn't been explicitly written to via data or backchannel APIs. Once a segment-key is written to by one of these APIs--since the broker was put into pour-active-stewardship mode for an identity--the pour-active-steward will return a 200/OK.

Once both complimentary hosts--reported by broker-lookup--respond with a value and a status code, consult the following decision matrix as to which broker's value to use :

	200/OK from ACTIVE (pour)	246/Inconclusive from ACTIVE (pour)	422/Unprocessable from ACTIVE (pour)	246/Inconclusive from PASSIVE (drain)	ERROR from PASSIVE (drain)	PASSIVE (drain) not set
200/OK from ACTIVE (pour)	X	X	X	use ACTIVE's value	use ACTIVE's value	use ACTIVE's value
246/Inconclusive from ACTIVE (pour)	X	X	X	use PASSIVE's value	use ACTIVE's value	use ACTIVE's value
422/Unprocessable from ACTIVE (pour)	X	X	X	use PASSIVE's value	ERROR	ERROR
246/Inconclusive from PASSIVE (drain)	use ACTIVE's value	use PASSIVE's value	use PASSIVE's value	X	X	X
ERROR from PASSIVE (drain)	use ACTIVE's value	use ACTIVE's value	ERROR	X	X	X
PASSIVE (drain) not set	use ACTIVE's value	use ACTIVE's value	ERROR	X	X	X

The decision which broker's value to use as source of truth depends on their returned status codes.

400 Bad Request

Bad request:

cannot process input

403 Forbidden #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

404 Not Found #/responses/404-datastore-key

Invalid datastore-key requested; segment-key or identity mismatch.

422 Unprocessable Entity #/responses/422

Unprocessable - not filled yet, check draining host for data.

Upon receipt of a 422 status code as a response to a getter call the client must attempt the getter call with the complementary draining passive broker as reported by broker-lookup--if any.

Refer to write-up on the 246 status code for a decision matrix as to what the client should do.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Setup settings for given datastore-key (segment-key @ identity).

PUT /{segment-key}/settings

Tags: datastore-key settings

Setup data and backchannel settings for given datastore-key (segment-key @ identity).

If this broker is not an (pour) active steward of data for identity, call fails with a 400 -- "cannot write, broker not an active steward of user's data"

application/json

DatastoreKeySettings


segment-key	Base64 encoded segment-key.	path	string
identity	Optional identity. If provided, must be one of public restricted identities: 0 .. 9999. If not provided, identity is that of token owner. See glossary.	query	string
wait-until-persisted	Optional request to synchronously block result until change to datastore-key is persisted.	query	boolean
wait-until-shared	Optional request to synchronously block result until change to datastore-key is shared on distributed persistence network.	query	boolean

200 OK

Settings applied successfully.

400 Bad Request

Bad request:

address incompatible with remuneration provider
invalid signature
cannot process input
cannot write, broker not an active steward of user's data
- check broker-lookup to find active steward and write there
cannot continue, invalid stewardship mode

403 Forbidden #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

404 Not Found #/responses/404-datastore-key

Invalid datastore-key requested; segment-key or identity mismatch.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization Header

Acknowledge receipt of a response fragment from a "getter" endpoint of a broker.

WIRE acknowledge

Tags: flow-control

The response payload of the following WIRE events--as well as broker initiated messages (see subscribe endpoint)--may be fragmented into multiple responses:

WIRE get data
WIRE fetch messages
WIRE get delegate data
WIRE get all delegate values
WIRE segment-keys
WIRE export

All WSS response events from the broker and broker-initiated events adhere to the WIRE response specification.

Any WIRE response with code 206 (fragment response) must be acknowledged by this acknowledge message: the broker will not send additional messages until receipt of acknowledgment.

Any broker-initiated WIRE message with code 222--subscription event--must be acknowledged by this acknowledge message: the broker will not send additional messages until receipt of acknowledgment.

WIRE events enumerating that they expect a response with code 206 (fragment response) or 222 (subscription event) need concern themselves with these acknowledgments. WIRE events not enumerating a response code 206 or 222 will never have a fragmented response.

Note that this message does not expect a response from the broker.

syntax	bytes	value
req-id	8
len	8	1
opcode	1	0x20

req-id: number

Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.

This is the request ID who's fragmented response we're acknowledging.

len: number

Length in bytes constituting the remainder of this message: number of bytes that follow this len.

opcode: bytes

Operation code.


Authorization WSS

Acknowledge all messages with timestamps up to and including a specified unixtime-millis for given datastore-key.

WIRE acknowledge messages

Tags: backchannel queues

Acknowledge all messages with timestamp up to and including a specified unixtime-millis have been handled. All messages up to and including the specified unixtime-millis will be removed from the backchannel.

Acknowledge messages if authorized identity is the owner of the datastore-key.

Acknowledge delegated messages if authorized identity is not the owner of the datastore-key but is complementary with the datastore-key's delegate configuration.

If this broker is not an (pour) active steward of data for identity, call fails with a 400 -- "cannot write, broker not an active steward of user's data"

application/octet-stream

syntax	bytes	value
req-id	8
len	8	SL + IL + 12
opcode	1	0x06
segment-key-len	1	SL == length(segment-key)
segment-key	SL
identity-len	1	IL == length(identity)
identity	IL
flags	1
unixtime-millis	8

req-id: number

Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.

len: number

Length in bytes constituting the remainder of this message: number of bytes that follow this len.

opcode: bytes

Operation code.

segment-key-len: number

Length in bytes of segment-key.

segment-key: bytes

See glossary.

identity-len: number

Length in bytes of identity.

identity: bytes

Optional identity. If provided, qualifies the datastore-key owner--complementary to delegation.

May be one of public identities: 0 .. 9999.

If not provided, authorized identity defaults as owner.

See glossary.

flags: bytes

A byte of flags.

value	name	description
0x04	wait-until-persisted	`1`: wait until datastore-key changes are persisted
0x08	wait-until-shared	`1`: wait until datastore-key changes are shared on distributed persistence network

unixtime-millis: number

unixtime-millis up to which--inclusive--to acknowledge backchannel processing.

application/octet-stream

RESPONSE #/responses/WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

Code 200 signifies the response is complete. For unfragmented responses only one response message is returned and it has a code of 200. A fragmented response returns one or more code 206 events followed by a final code 200 response; signalling end of fragments--at which point the aggregate payload can be reconstituted.

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

code == 200

Success. Empty.

code == 400

Bad request:

no handshake
message outside handshake constraints
cannot process input
cannot write, broker not an active steward of user's data
- check broker-lookup to find active steward and write there
cannot continue, invalid stewardship mode

code == 403 #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

code == 404 #/responses/404-datastore-key

Invalid datastore-key requested; segment-key or identity mismatch.

code == 429 #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization WSS

Continue sending fragments of a message to a "setter" endpoint of a broker.

WIRE continue

Tags: flow-control

For the following WIRE events the message payload may be fragmented into multiple requests:

WIRE set data
WIRE post message
WIRE import

The first request is one of the above WIRE event calls. Subsequent requests are this continuation call. All the requests are sequential fragments of the same aggregate message. The order of the initial WIRE event call and these subsequent continuation fragments is guaranteed.

Any "setter" WIRE event that may have it's request fragmented will indicate that it respects the 0x80 (done) flag value in it's properties description. Any WIRE event that doesn't consider the 0x80 (done) flag may not have its message stream--initiated by endpoint call with a req-id--continued with these continue fragment messages.

The first WIRE event transmits the first bytes of the payload and indicates that there are more fragments required by keeping the 0x80 flag (done) unset.

Subsequent continuation fragments transfer the remainder of the aggregate message byte-stream to the broker. The last message has it's 0x80 flag (done) set.

The client must not send subsequent fragments until the broker responds with a 200 code to the previous request.

application/octet-stream

syntax	bytes	value
req-id	8
len	8	length(payload) + 2
opcode	1	0x10
flags	1
payload	*

req-id: number

Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.

This is the request ID we're continuing with this fragment.

len: number

Length in bytes constituting the remainder of this message: number of bytes that follow this len.

opcode: bytes

Operation code.

flags: bytes

A byte of flags.

value	name	description
0x80	done	`0x1`: this is the last fragment of the payload for req-id

payload: bytes

The fragment byte-stream.

application/octet-stream

RESPONSE #/responses/WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

code == 200

Success. Empty.

code == 400

Bad request:

no handshake
message outside handshake constraints
cannot process input
cannot write, broker not an active steward of user's data
- check broker-lookup to find active steward and write there
cannot continue, invalid stewardship mode

code == 429 #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization WSS

Delete datastore-key.

WIRE delete data

Tags: data

Delete datastore-key (segment-key @ identity). The datastore-key must be owned by the token owner.

If this broker is not an (pour) active steward of data for identity, call fails with a 400 -- "cannot write, broker not an active steward of user's data"

application/octet-stream

syntax	bytes	value
req-id	8
len	8	SL + IL + 4
opcode	1	0x03
segment-key-len	1	SL == length(segment-key)
segment-key	SL
identity-len	1	IL == length(identity)
identity	IL
flags	1

req-id: number

Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.

len: number

Length in bytes constituting the remainder of this message: number of bytes that follow this len.

opcode: bytes

Operation code.

segment-key-len: number

Length in bytes of segment-key.

segment-key: bytes

See glossary.

identity-len: number

Length in bytes of identity.

identity: bytes

Optional identity. If not provided, identity is that of token owner.

See glossary.

flags: bytes

A byte of flags.

value	name	description
0x04	wait-until-persisted	`1`: wait until datastore-key changes are persisted
0x08	wait-until-shared	`1`: wait until datastore-key changes are shared on distributed persistence network

application/octet-stream

RESPONSE #/responses/WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

code == 200

Success. Empty.

code == 400

Bad request:

no handshake
message outside handshake constraints
cannot process input
cannot write, broker not an active steward of user's data
- check broker-lookup to find active steward and write there
cannot continue, invalid stewardship mode

code == 403 #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

code == 404 #/responses/404-datastore-key

Invalid datastore-key requested; segment-key or identity mismatch.

code == 429 #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization WSS

A delegate deletes their specific data under this datastore-key.

WIRE delete delegate data

Tags: delegate

Delete delegate's data filed under the datastore-key (segment-key @ identity).

This call requires two identities: the segment-key and identity request parameters constitute the datastore-key. The identity from the authorization header is used to qualify the data stored at the segment-key: this identity is the delegate.

The datastore-key must be owned by the identity from request parameter.

If this broker is not an (pour) active steward of data for identity, call fails with a 400 -- "cannot write, broker not an active steward of user's data"

application/octet-stream

syntax	bytes	value
req-id	8
len	8	SL + IL + 4
opcode	1	0x0A
segment-key-len	1	SL == length(segment-key)
segment-key	SL
identity-len	1	IL == length(identity)
identity	IL
flags	1

req-id: number

Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.

len: number

Length in bytes constituting the remainder of this message: number of bytes that follow this len.

opcode: bytes

Operation code.

segment-key-len: number

Length in bytes of segment-key.

segment-key: bytes

See glossary.

identity-len: number

Length in bytes of identity.

identity: bytes

Required identity of segment-key owner--authorization header identity is used for qualifying the delegate.

See glossary.

flags: bytes

A byte of flags.

value	name	description
0x04	wait-until-persisted	`1`: wait until datastore-key changes are persisted
0x08	wait-until-shared	`1`: wait until datastore-key changes are shared on distributed persistence network

application/octet-stream

RESPONSE #/responses/WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

code == 200

Success. Empty.

code == 400

Bad request:

no handshake
message outside handshake constraints
cannot process input
cannot write, broker not an active steward of user's data
- check broker-lookup to find active steward and write there
cannot continue, invalid stewardship mode

code == 403 #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

code == 404 #/responses/404-datastore-key

Invalid datastore-key requested; segment-key or identity mismatch.

code == 429 #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization WSS

Extract all user's data from the broker system.

WIRE export

Tags: data-stewardship

Extract all of the caller's data, based on caller's identity.

application/octet-stream

syntax	bytes	value
req-id	8
len	8	SL + IL + 3
opcode	1	0x0E

req-id: number: Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.
len: number: Length in bytes constituting the remainder of this message: number of bytes that follow this len.
opcode: bytes: Operation code.

application/octet-stream

400 Bad Request

Bad request:

no handshake
message outside handshake constraints
cannot process input

403 Forbidden #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

429 Too Many Requests #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.

RESPONSE #/responses/WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

code == 200

All data in JSON format with UTF-8 encoding.

ImportExportPayload

code == 206 #/responses/206

A fragment of the full response. Payload byte-stream to reconstitute--in-order--into the aggregate as described by the 200 response code.

Subsequent 206 responses may follow--in-order for reconstituting the response byte stream--until the aggregate response is finalized with a 200 response code.

Every 206 response must be acknowledged by the client before the broker will send subsequent fragments.


Authorization WSS

Retrieve all messages from the backchannel at the givent datastore-key.

WIRE fetch messages

Tags: backchannel queues

Retrieve all messages from the backchannel at the given datastore-key (segment-key @ identity).

Retrieves messages if authorized identity is the owner of the datastore-key.

Retrieves delegated messages if authorized identity is not the owner of the datastore-key but is complementary with the datastore-key's delegate configuration.

application/octet-stream

syntax	bytes	value
req-id	8
len	8	SL + IL + 3
opcode	1	0x05
segment-key-len	1	SL == length(segment-key)
segment-key	SL
identity-len	1	IL == length(identity)
identity	IL

req-id: number

Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.

len: number

Length in bytes constituting the remainder of this message: number of bytes that follow this len.

opcode: bytes

Operation code.

segment-key-len: number

Length in bytes of segment-key.

segment-key: bytes

See glossary.

identity-len: number

Length in bytes of identity.

identity: bytes

Optional identity. If provided, qualifies the datastore-key owner--complementary to delegation.

May be one of public identities: 0 .. 9999.

If not provided, authorized identity defaults as owner.

See glossary.

application/octet-stream

RESPONSE #/responses/WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

code == 200

Messages enqueued at datastore-key (segment-key @ identity) ordered by increasing non-unique unixtime-millis.

Messages returned may not have unique unixtime-millis--more than one message may have the same unixtime-millis.

The broker guarantees that the messages in the payload comprise all unacknowledged message with a unixtime-millis up-to and including the highest unixtime-millis.

syntax	bytes	value
loop {
unixtime-millis	8
message-len	8	ML = length(message)
message	*
}

unixtime-millis: number: Non-unique UNIX Epoch timestamp (milliseconds) of the message.
message-len: number: Length in bytes of message.
message: bytes: The message byte stream value.

code == 206 #/responses/206

A fragment of the full response. Payload byte-stream to reconstitute--in-order--into the aggregate as described by the 200 response code.

Subsequent 206 responses may follow--in-order for reconstituting the response byte stream--until the aggregate response is finalized with a 200 response code.

Every 206 response must be acknowledged by the client before the broker will send subsequent fragments.

code == 246 #/responses/246

Inconclusive - check other broker for newer data.

The 246 status code has the same structure as a 200/OK and indicates success, but requires caller to second-guess this result.

It is always returned by getter calls on:

passive hosts in cases where an active host would return a 200/OK.
pour-active-stewardship hosts when request is for data in a segment-key that hasn't been explicitly written to via data or backchannel APIs. Once a segment-key is written to by one of these APIs--since the broker was put into pour-active-stewardship mode for an identity--the pour-active-steward will return a 200/OK.

Once both complimentary hosts--reported by broker-lookup--respond with a value and a status code, consult the following decision matrix as to which broker's value to use :

	200/OK from ACTIVE (pour)	246/Inconclusive from ACTIVE (pour)	422/Unprocessable from ACTIVE (pour)	246/Inconclusive from PASSIVE (drain)	ERROR from PASSIVE (drain)	PASSIVE (drain) not set
200/OK from ACTIVE (pour)	X	X	X	use ACTIVE's value	use ACTIVE's value	use ACTIVE's value
246/Inconclusive from ACTIVE (pour)	X	X	X	use PASSIVE's value	use ACTIVE's value	use ACTIVE's value
422/Unprocessable from ACTIVE (pour)	X	X	X	use PASSIVE's value	ERROR	ERROR
246/Inconclusive from PASSIVE (drain)	use ACTIVE's value	use PASSIVE's value	use PASSIVE's value	X	X	X
ERROR from PASSIVE (drain)	use ACTIVE's value	use ACTIVE's value	ERROR	X	X	X
PASSIVE (drain) not set	use ACTIVE's value	use ACTIVE's value	ERROR	X	X	X

The decision which broker's value to use as source of truth depends on their returned status codes.

code == 400

Bad request:

no handshake
message outside handshake constraints
cannot process input

code == 403 #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

code == 404 #/responses/404-datastore-key

Invalid datastore-key requested; segment-key or identity mismatch.

code == 422 #/responses/422

Unprocessable - not filled yet, check draining host for data.

Upon receipt of a 422 status code as a response to a getter call the client must attempt the getter call with the complementary draining passive broker as reported by broker-lookup--if any.

Refer to write-up on the 246 status code for a decision matrix as to what the client should do.

code == 429 #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization WSS

Discriminately set all user's data on the broker system.

WIRE fill

Tags: data-stewardship

All of the user's data with caller's identity that is deemed older than the payload is wiped and reset to the payload.

If transferring a segment-key that already exists on the broker for caller's identity, the segment-key in the payload is ignored.

If the payload is malformated and cannot be imported the message call fails with a 400 -- "cannot process input", followed by additional optional verbiage.

If this broker is not a (pour) active steward of data for identity, call fails with a 400 -- "cannot write, broker not an active steward of user's data"

application/octet-stream

syntax	bytes	value
req-id	8
len	8	SL + IL + length(payload) + 4
opcode	1	0x0D
flags	1
payload	*

req-id: number

Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.

len: number

Length in bytes constituting the remainder of this message: number of bytes that follow this len.

opcode: bytes

Operation code.

flags: bytes

A byte of flags.

value	name	description
0x04	wait-until-persisted	`1`: wait until datastore-key changes are persisted
0x08	wait-until-shared	`1`: wait until datastore-key changes are shared on distributed persistence network
0x80	done	`1`: this payload is not fragmented; `0`: this payload is a fragment and subsequent continue messages will follow after the broker responds with a 200.

payload: object

All data in JSON format with UTF-8 encoding.

Payload adheres to the ImportExportPayload definition.

application/octet-stream

RESPONSE #/responses/WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

code == 200

Success. Empty.

code == 400

Bad request:

no handshake
message outside handshake constraints
cannot process input
cannot write, broker not an active steward of user's data
- check broker-lookup to find active steward and write there
cannot continue, invalid stewardship mode

code == 403 #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

code == 429 #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization WSS

Retrieves all delegate data under segment-key as map of delegate identities to content.

WIRE get all delegate values

Tags: delegate

Retrieve all delegate data under datastore-key (segment-key @ identity) as map of delegate identities to content.

The segment-key and identity request parameters constitute the datastore-key.

application/octet-stream

syntax	bytes	value
req-id	8
len	8	SL + IL + 3
opcode	1	0x0B
segment-key-len	1	SL == length(segment-key)
segment-key	SL
identity-len	1	IL == length(identity)
identity	IL

req-id: number

Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.

len: number

Length in bytes constituting the remainder of this message: number of bytes that follow this len.

opcode: bytes

Operation code.

segment-key-len: number

Length in bytes of segment-key.

segment-key: bytes

See glossary.

identity-len: number

Length in bytes of identity.

identity: bytes

Required identity of segment-key owner.

See glossary.

application/octet-stream

RESPONSE #/responses/WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

code == 200

List of all delegate data under the datastore-key.

syntax	bytes	value
loop {
delegate-len	1	DL == length(delegate)
delegate	DL
message-len	8	ML = length(message)
message	*
}

delegate-len: number: Length in bytes of delegate.
delegate: bytes: Qualifies which delegate of segment-key this message corresponds to. The value is the delegate's identity.
message-len: number: Length in bytes of message.
message: bytes: The message byte stream value.

code == 206 #/responses/206

A fragment of the full response. Payload byte-stream to reconstitute--in-order--into the aggregate as described by the 200 response code.

Subsequent 206 responses may follow--in-order for reconstituting the response byte stream--until the aggregate response is finalized with a 200 response code.

Every 206 response must be acknowledged by the client before the broker will send subsequent fragments.

code == 246 #/responses/246

Inconclusive - check other broker for newer data.

The 246 status code has the same structure as a 200/OK and indicates success, but requires caller to second-guess this result.

It is always returned by getter calls on:

passive hosts in cases where an active host would return a 200/OK.
pour-active-stewardship hosts when request is for data in a segment-key that hasn't been explicitly written to via data or backchannel APIs. Once a segment-key is written to by one of these APIs--since the broker was put into pour-active-stewardship mode for an identity--the pour-active-steward will return a 200/OK.

Once both complimentary hosts--reported by broker-lookup--respond with a value and a status code, consult the following decision matrix as to which broker's value to use :

	200/OK from ACTIVE (pour)	246/Inconclusive from ACTIVE (pour)	422/Unprocessable from ACTIVE (pour)	246/Inconclusive from PASSIVE (drain)	ERROR from PASSIVE (drain)	PASSIVE (drain) not set
200/OK from ACTIVE (pour)	X	X	X	use ACTIVE's value	use ACTIVE's value	use ACTIVE's value
246/Inconclusive from ACTIVE (pour)	X	X	X	use PASSIVE's value	use ACTIVE's value	use ACTIVE's value
422/Unprocessable from ACTIVE (pour)	X	X	X	use PASSIVE's value	ERROR	ERROR
246/Inconclusive from PASSIVE (drain)	use ACTIVE's value	use PASSIVE's value	use PASSIVE's value	X	X	X
ERROR from PASSIVE (drain)	use ACTIVE's value	use ACTIVE's value	ERROR	X	X	X
PASSIVE (drain) not set	use ACTIVE's value	use ACTIVE's value	ERROR	X	X	X

The decision which broker's value to use as source of truth depends on their returned status codes.

code == 400

Bad request:

no handshake
message outside handshake constraints
cannot process input

code == 403 #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

code == 404 #/responses/404-datastore-key

Invalid datastore-key requested; segment-key or identity mismatch.

code == 422 #/responses/422

Unprocessable - not filled yet, check draining host for data.

Upon receipt of a 422 status code as a response to a getter call the client must attempt the getter call with the complementary draining passive broker as reported by broker-lookup--if any.

Refer to write-up on the 246 status code for a decision matrix as to what the client should do.

code == 429 #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization WSS

Get value of datastore-key.

WIRE get data

Tags: data

Get value of datastore-key (segment-key @ identity).

application/octet-stream

syntax	bytes	value
req-id	8
len	8	SL + IL + 3
opcode	1	0x02
segment-key-len	1	SL == length(segment-key)
segment-key	SL
identity-len	1	IL == length(identity)
identity	IL

req-id: number

Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.

len: number

Length in bytes constituting the remainder of this message: number of bytes that follow this len.

opcode: bytes

Operation code.

segment-key-len: number

Length in bytes of segment-key.

segment-key: bytes

See glossary.

identity-len: number

Length in bytes of identity.

identity: bytes

Optional identity. If not provided, identity is that of token owner.

See glossary.

application/octet-stream

RESPONSE #/responses/WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

code == 200

The value of datastore-key (segment-key @ identity).

code == 206 #/responses/206

A fragment of the full response. Payload byte-stream to reconstitute--in-order--into the aggregate as described by the 200 response code.

Subsequent 206 responses may follow--in-order for reconstituting the response byte stream--until the aggregate response is finalized with a 200 response code.

Every 206 response must be acknowledged by the client before the broker will send subsequent fragments.

code == 246 #/responses/246

Inconclusive - check other broker for newer data.

The 246 status code has the same structure as a 200/OK and indicates success, but requires caller to second-guess this result.

It is always returned by getter calls on:

passive hosts in cases where an active host would return a 200/OK.
pour-active-stewardship hosts when request is for data in a segment-key that hasn't been explicitly written to via data or backchannel APIs. Once a segment-key is written to by one of these APIs--since the broker was put into pour-active-stewardship mode for an identity--the pour-active-steward will return a 200/OK.

Once both complimentary hosts--reported by broker-lookup--respond with a value and a status code, consult the following decision matrix as to which broker's value to use :

	200/OK from ACTIVE (pour)	246/Inconclusive from ACTIVE (pour)	422/Unprocessable from ACTIVE (pour)	246/Inconclusive from PASSIVE (drain)	ERROR from PASSIVE (drain)	PASSIVE (drain) not set
200/OK from ACTIVE (pour)	X	X	X	use ACTIVE's value	use ACTIVE's value	use ACTIVE's value
246/Inconclusive from ACTIVE (pour)	X	X	X	use PASSIVE's value	use ACTIVE's value	use ACTIVE's value
422/Unprocessable from ACTIVE (pour)	X	X	X	use PASSIVE's value	ERROR	ERROR
246/Inconclusive from PASSIVE (drain)	use ACTIVE's value	use PASSIVE's value	use PASSIVE's value	X	X	X
ERROR from PASSIVE (drain)	use ACTIVE's value	use ACTIVE's value	ERROR	X	X	X
PASSIVE (drain) not set	use ACTIVE's value	use ACTIVE's value	ERROR	X	X	X

The decision which broker's value to use as source of truth depends on their returned status codes.

code == 400

Bad request:

no handshake
message outside handshake constraints
cannot process input

code == 403 #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

code == 404 #/responses/404-datastore-key

Invalid datastore-key requested; segment-key or identity mismatch.

code == 422 #/responses/422

Unprocessable - not filled yet, check draining host for data.

Upon receipt of a 422 status code as a response to a getter call the client must attempt the getter call with the complementary draining passive broker as reported by broker-lookup--if any.

Refer to write-up on the 246 status code for a decision matrix as to what the client should do.

code == 429 #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization WSS

A delegate retrieves their specific value under this datastore-key.

WIRE get delegate data

Tags: delegate

Retrieve contents from datastore-key (segment-key @ identity) qualified by the caller's identity.

application/octet-stream

syntax	bytes	value
req-id	8
len	8	SL + IL + 3
opcode	1	0x09
segment-key-len	1	SL == length(segment-key)
segment-key	SL
identity-len	1	IL == length(identity)
identity	IL

req-id: number

Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.

len: number

Length in bytes constituting the remainder of this message: number of bytes that follow this len.

opcode: bytes

Operation code.

segment-key-len: number

Length in bytes of segment-key.

segment-key: bytes

See glossary.

identity-len: number

Length in bytes of identity.

identity: bytes

Required identity of segment-key owner--authorization header identity is used for qualifying the delegate.

See glossary.

application/octet-stream

RESPONSE #/responses/WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

code == 200

The value of datastore-key (segment-key @ identity).

code == 206 #/responses/206

A fragment of the full response. Payload byte-stream to reconstitute--in-order--into the aggregate as described by the 200 response code.

Subsequent 206 responses may follow--in-order for reconstituting the response byte stream--until the aggregate response is finalized with a 200 response code.

Every 206 response must be acknowledged by the client before the broker will send subsequent fragments.

code == 246 #/responses/246

Inconclusive - check other broker for newer data.

The 246 status code has the same structure as a 200/OK and indicates success, but requires caller to second-guess this result.

It is always returned by getter calls on:

passive hosts in cases where an active host would return a 200/OK.
pour-active-stewardship hosts when request is for data in a segment-key that hasn't been explicitly written to via data or backchannel APIs. Once a segment-key is written to by one of these APIs--since the broker was put into pour-active-stewardship mode for an identity--the pour-active-steward will return a 200/OK.

Once both complimentary hosts--reported by broker-lookup--respond with a value and a status code, consult the following decision matrix as to which broker's value to use :

	200/OK from ACTIVE (pour)	246/Inconclusive from ACTIVE (pour)	422/Unprocessable from ACTIVE (pour)	246/Inconclusive from PASSIVE (drain)	ERROR from PASSIVE (drain)	PASSIVE (drain) not set
200/OK from ACTIVE (pour)	X	X	X	use ACTIVE's value	use ACTIVE's value	use ACTIVE's value
246/Inconclusive from ACTIVE (pour)	X	X	X	use PASSIVE's value	use ACTIVE's value	use ACTIVE's value
422/Unprocessable from ACTIVE (pour)	X	X	X	use PASSIVE's value	ERROR	ERROR
246/Inconclusive from PASSIVE (drain)	use ACTIVE's value	use PASSIVE's value	use PASSIVE's value	X	X	X
ERROR from PASSIVE (drain)	use ACTIVE's value	use ACTIVE's value	ERROR	X	X	X
PASSIVE (drain) not set	use ACTIVE's value	use ACTIVE's value	ERROR	X	X	X

The decision which broker's value to use as source of truth depends on their returned status codes.

code == 400

Bad request:

no handshake
message outside handshake constraints
cannot process input

code == 403 #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

code == 404 #/responses/404-datastore-key

Invalid datastore-key requested; segment-key or identity mismatch.

code == 422 #/responses/422

Unprocessable - not filled yet, check draining host for data.

Upon receipt of a 422 status code as a response to a getter call the client must attempt the getter call with the complementary draining passive broker as reported by broker-lookup--if any.

Refer to write-up on the 246 status code for a decision matrix as to what the client should do.

code == 429 #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization WSS

Halt fragmented sending or receiving.

WIRE halt

Tags: flow-control

Any fragmented sending or receiving--as per the continue or acknowledge endpoints--may be halted.

A halt signals further fragments should not be sent, should be dropped.

Only the client can initiate a halt. The broker may similarly halt on timeout conditions as per handshake.

application/octet-stream

syntax	bytes	value
req-id	8
len	8	1
opcode	1	0x30

req-id: number

Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.

This is the request ID who's fragmented response we're acknowledging.

len: number

Length in bytes constituting the remainder of this message: number of bytes that follow this len.

opcode: bytes

Operation code.

application/octet-stream

RESPONSE #/responses/WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

code == 200

Halt seen.

code == 400

Bad request:

no handshake
cannot write, broker not an active steward of user's data
- check broker-lookup to find active steward and write there
cannot continue, invalid stewardship mode

code == 429 #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization WSS

Client initiates handshake with broker.

WIRE handshake

Tags: flow-control

The handshake should take place immediatelly after upgrading an authenticated HTTPS connection to WSS, before raising any other WIRE events.

The handshake constitutes message maximums and message fragmentation parameters.

The client sends the maximums to the broker. If the broker agrees to the values it responds with a 200: finalizing the handshake (see responses).

If the values are not acceptable to the broker, the broker responds with a 413; suggesting alternate values (see responses). The handshake is broken off at this point. The client needs to re-start the handshake, adjusting the values sent in.

All WIRE events following a successful handshake need to keep their message exchanges consistent with the constraints of the handshake, else risk a "message outside handshake constraints" (400) response.

application/octet-stream

syntax	bytes	value
req-id	8
len	8	17
opcode	1	0xFF
max-fragment-size	4
max-aggregate-size	8
ack-timeout-millis	4

req-id: number

Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.

len: number

Length in bytes constituting the remainder of this message: number of bytes that follow this len.

opcode: bytes

Operation code.

max-fragment-size: number

A large message payload must be split up into fragments at most max-fragment-size bytes long.

A suggested default is 256KiB.

max-aggregate-size: number

The maximum size of a message payload--the aggregate of all fragments.

ack-timeout-millis: number

Milliseconds specifying period within which a fragment acknowledgment is expected before sender can halt exchange.

application/octet-stream

RESPONSE #/responses/WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

code == 200

Handshake achieved: broker agrees with the flow-control values as per this handshake request from the client.

code == 413

The broker rejects the flow-control values.

Suggested values are returned in the response byte-stream:

syntax	bytes	value
max-fragment-size	4
max-aggregate-size	8
ack-timeout-millis	4

Handshake is not established, the client should retry the handshake with the values suggested by the broker.

code == 429 #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization WSS

Indiscriminately Set all user's data on the broker system.

WIRE import

Tags: data-stewardship

All of the user's data with caller's identity is wiped and reset to the payload.

When filling broker in pour-active-steward mode don't use this import--as it's indiscriminate--use fill instead.

If the payload is malformated and cannot be imported the message call fails with a 400 -- "cannot process input", followed by additional optional verbiage.

If this broker is not an (pour) active steward of data for identity, call fails with a 400 -- "cannot write, broker not an active steward of user's data"

application/octet-stream

syntax	bytes	value
req-id	8
len	8	SL + IL + length(payload) + 4
opcode	1	0x0C
flags	1
payload	*

req-id: number

Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.

len: number

Length in bytes constituting the remainder of this message: number of bytes that follow this len.

opcode: bytes

Operation code.

flags: bytes

A byte of flags.

value	name	description
0x04	wait-until-persisted	`1`: wait until datastore-key changes are persisted
0x08	wait-until-shared	`1`: wait until datastore-key changes are shared on distributed persistence network
0x80	done	`1`: this payload is not fragmented; `0`: this payload is a fragment and subsequent continue messages will follow after the broker responds with a 200.

payload: object

All data in JSON format with UTF-8 encoding.

Payload adheres to the ImportExportPayload definition.

application/octet-stream

RESPONSE #/responses/WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

code == 200

Success. Empty.

code == 400

Bad request:

no handshake
message outside handshake constraints
cannot process input
cannot write, broker not an active steward of user's data
- check broker-lookup to find active steward and write there
cannot continue, invalid stewardship mode

code == 403 #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

code == 429 #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization WSS

Enqueue a message to a given datastore-key backchannel.

WIRE post message

Tags: backchannel queues

Enqueue a message to a given datastore-key (segment-key @ identity) backchannel.

If the datastore-key's allow-publish setting is "self", the identity in the authentication token must match the datastore-key owner.

If the datastore-key's allow-publish setting is "signed", the author of the backchannel message is the identity tied ot the authorization token passed to this API. Message author's identity is present in the token and compared to the allowed-publishers list--if any--for this datastore-key.

If the datastore-key's allow-publish setting is "any", the identity in the authentication token must simply be valid: a valid broker system user is publishing.

See the settings getter for the above settings.

If this broker is not an (pour) active steward of data for identity, call fails with a 400 -- "cannot write, broker not an active steward of user's data"

application/octet-stream

syntax	bytes	value
req-id	8
len	8	SL + IL + DL + length(payload) + 5
opcode	1	0x04
segment-key-len	1	SL == length(segment-key)
segment-key	SL
identity-len	1	IL == length(identity)
identity	IL
delegate-len	1	DL == length(delegate)
delegate	DL
flags	1
payload	*

req-id: number

Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.

len: number

Length in bytes constituting the remainder of this message: number of bytes that follow this len.

opcode: bytes

Operation code.

segment-key-len: number

Length in bytes of segment-key.

segment-key: bytes

See glossary.

identity-len: number

Length in bytes of identity.

identity: bytes

Optional identity. If provided, must be complementary to the delegate parameter, or one of public restricted identities: 0 .. 9999. If not provided, identity is that of token owner.

See glossary.

delegate-len: number

Length in bytes of delegate.

delegate: bytes

Qualifies that this backchannel message is meant for a delegate of segment-key. The value is the delegate's identity.

This value could be a glob *. The * glob value means the message is posted to all delegates: it's enqueued on all their queues.

The delegate is the message recepient and must satisfy settings on the segment-key allowing delegate publication of mesages.

If this parameter is present, the identity request parameter is mandatory. The segment-key and the identity request parameters constitute the datstore-key.

The authorized user is the sender.

flags: bytes

A byte of flags.

value	name	description
0x04	wait-until-persisted	`1`: wait until datastore-key changes are persisted
0x08	wait-until-shared	`1`: wait until datastore-key changes are shared on distributed persistence network
0x80	done	`1`: this payload is not fragmented; `0`: this payload is a fragment and subsequent continue messages will follow after the broker responds with a 200.

payload: bytes

The payload byte-stream.

application/octet-stream

RESPONSE #/responses/WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

code == 200

Success. Empty.

code == 400

Bad request:

no handshake
message outside handshake constraints
cannot process input
cannot write, broker not an active steward of user's data
- check broker-lookup to find active steward and write there
cannot continue, invalid stewardship mode

code == 403 #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

code == 404 #/responses/404-datastore-key

Invalid datastore-key requested; segment-key or identity mismatch.

code == 429 #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization WSS

Retrieve key-names of all segment-keys owned by an indentity.

WIRE segment-keys

Tags: metrics

Retrieve key-names of all segment-keys owned by an indentity.

application/octet-stream

syntax	bytes	value
req-id	8
len	8	IL + 1
opcode	1	0x0F

req-id: number: Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.
len: number: Length in bytes constituting the remainder of this message: number of bytes that follow this len.
opcode: bytes: Operation code.

application/octet-stream

RESPONSE #/responses/WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

code == 200

Key-names of segment-keys in a loop.

syntax	bytes	value
loop {
key-name	128
}

code == 206 #/responses/206

A fragment of the full response. Payload byte-stream to reconstitute--in-order--into the aggregate as described by the 200 response code.

Subsequent 206 responses may follow--in-order for reconstituting the response byte stream--until the aggregate response is finalized with a 200 response code.

Every 206 response must be acknowledged by the client before the broker will send subsequent fragments.

code == 400

Bad request:

no handshake
message outside handshake constraints
cannot process input

code == 403 #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

code == 429 #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization WSS

Set value of datastore-key.

WIRE set data

Tags: data

Payload contents is written as a new value into datastore-key (segment-key @ identity).

For the set to succeed the datastore-key (segment-key @ identity) must either be brand new of already owned by authorization token owner.

If this broker is not an (pour) active steward of data for identity, call fails with a 400 -- "cannot write, broker not an active steward of user's data"

application/octet-stream

syntax	bytes	value
req-id	8
len	8	SL + IL + length(payload) + 4 + [32]
opcode	1	0x01
segment-key-len	1	SL == length(segment-key)
segment-key	SL
identity-len	1	IL == length(identity)
identity	IL
flags	1
if flags & 0x10 {
write-gate	32
}
payload	*

req-id: number

Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.

len: number

Length in bytes constituting the remainder of this message: number of bytes that follow this len. 32 bytes are added for a write-gate if flags has 0x10 set.

opcode: bytes

Operation code.

segment-key-len: number

Length in bytes of segment-key.

segment-key: bytes

See glossary.

identity-len: number

Length in bytes of identity.

identity: bytes

Optional identity. If not provided, identity is that of token owner.

See glossary.

flags: bytes

A byte of flags.

value	name	description
0x04	wait-until-persisted	`1`: wait until datastore-key changes are persisted
0x08	wait-until-shared	`1`: wait until datastore-key changes are shared on distributed persistence network
0x10	gate-the-write	`1`: use SHA256 in write-gate to check value at segment-key for equality before overriding.
0x80	done	`1`: this payload is not fragmented; `0`: this payload is a fragment and subsequent continue messages will follow after the broker responds with a 200.

write-gate: bytes

Optional write "gate": a 32 byte SHA256 hash value of the content being replaced by this set operation. If this hash does not match the current value at this segment-key, this set operation will fail with error code 409.

payload: bytes

The payload byte-stream.

application/octet-stream

RESPONSE #/responses/WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

code == 200

Success. Empty.

code == 400

Bad request:

no handshake
message outside handshake constraints
cannot process input
cannot write, broker not an active steward of user's data
- check broker-lookup to find active steward and write there
cannot continue, invalid stewardship mode

code == 403 #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

code == 409 #/responses/409

Setter encountered a conflict. Consult error message:

write-conflict:

Occurs when a data set operation includes a write-gate parameter that has a SHA256 value which does not match the SHA256 hash of the current (in-datastore) value of a segment-key.

A data write is requested on a segment-key that has an unexpected value in the datastore. Implies there is a concurrent write issue.
datastore-key conflict:

Datastore-key ownership conflict; segment-key @ identity already reserved.

code == 429 #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization WSS

A delegate sets their specific value under this datastore-key.

WIRE set delegate data

Tags: delegate

Payload contents is written as a new value into datastore-key (segment-key @ identity) qualified by the caller's identity.

For the set to succeed the datastore-key (segment-key @ identity) must exist and be owned by the identity from the request parameter.

A delegate can only write their value to this segment-key settings on segment-key permitting. Only the delegate identified can write data. The settings are solely to identify who the delegates can be.

If this broker is not an (pour) active steward of data for identity, call fails with a 400 -- "cannot write, broker not an active steward of user's data"

application/octet-stream

syntax	bytes	value
req-id	8
len	8	SL + IL + length(payload) + 4 + [32]
opcode	1	0x08
segment-key-len	1	SL == length(segment-key)
segment-key	SL
identity-len	1	IL == length(identity)
identity	IL
flags	1
if flags & 0x10 {
write-gate	32
}
payload	*

req-id: number

Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.

len: number

Length in bytes constituting the remainder of this message: number of bytes that follow this len. 32 bytes are added for a write-gate if flags has 0x10 set.

opcode: bytes

Operation code.

segment-key-len: number

Length in bytes of segment-key.

segment-key: bytes

See glossary.

identity-len: number

Length in bytes of identity.

identity: bytes

Required identity of segment-key owner--authorization header identity is used for qualifying the delegate.

See glossary.

flags: bytes

A byte of flags.

value	name	description
0x04	wait-until-persisted	`1`: wait until datastore-key changes are persisted
0x08	wait-until-shared	`1`: wait until datastore-key changes are shared on distributed persistence network
0x10	gate-the-write	`1`: use SHA256 in write-gate to check value at segment-key for equality before overriding.
0x80	done	`1`: this payload is not fragmented; `0`: this payload is a fragment and subsequent continue messages will follow after the broker responds with a 200.

write-gate: bytes

payload: bytes

The payload byte-stream.

application/octet-stream

RESPONSE #/responses/WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

code == 200

Value successfully set.

code == 400

Bad request:

no handshake
message outside handshake constraints
cannot process input
cannot write, broker not an active steward of user's data
- check broker-lookup to find active steward and write there
cannot continue, invalid stewardship mode

code == 403 #/responses/403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

code == 409 #/responses/409

Setter encountered a conflict. Consult error message:

write-conflict:

Occurs when a data set operation includes a write-gate parameter that has a SHA256 value which does not match the SHA256 hash of the current (in-datastore) value of a segment-key.

A data write is requested on a segment-key that has an unexpected value in the datastore. Implies there is a concurrent write issue.
datastore-key conflict:

Datastore-key ownership conflict; segment-key @ identity already reserved.

code == 429 #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization WSS

Owner--identified in token--subscribes to notifications of new messages in datastore-key.

WIRE subscribe

Tags: backchannel queues

Owner--identified in token--subscribes to notifications of new messages in datastore-key (segment-key @ identity).

Subscribes to messages if authorized identity is the owner of the datastore-key.

Subscribes to delegated messages if authorized identity is not the owner of the datastore-key but is complementary with the datastore-key's delegate configuration.

If the shunt query parameter is not specified, subscription doesn't send actual message content, just notification of new messages with a new unixtime-millis.

If the shunt query parameter is specified, full message content is sent via subscription. Unless the auto-acknowledge flag is set, the messages do have to be explicitly acknowledged to clear the backchannel queue. Failure to acknowledge messages with auto-acknowledge off and limit-bytes set may lead to a full backchannel queue and dropped messages; not forwarded to these live subscriptions.

If this broker is not an (pour) active steward of data for identity and the auto-acknowledge flag is set, call fails with a 400 -- "cannot write, broker not an active steward of user's data"

application/octet-stream

syntax	bytes	value
req-id	8
len	8	SL + IL + 4
opcode	1	0x07
segment-key-len	1	SL == length(segment-key)
segment-key	SL
identity-len	1	IL == length(identity)
identity	IL
flags	1

req-id: number

Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.

len: number

Length in bytes constituting the remainder of this message: number of bytes that follow this len.

opcode: bytes

Operation code.

segment-key-len: number

Length in bytes of segment-key.

segment-key: bytes

See glossary.

identity-len: number

Length in bytes of identity.

identity: bytes

Optional identity. If provided, qualifies the datastore-key owner--complementary to delegation.

May be one of public identities: 0 .. 9999.

If not provided, authorized identity defaults as owner.

See glossary.

flags: bytes

A byte of flags.

value	name	description
0x01	shunt	`0`: subscription doesn't send actual message content, just notification of new messages with a new unixtime-millis. `1`: full message content is sent via subscription.
0x02	auto-acknowledge	`0`: explicit acknowledgment via acknowledge call required. `1`: messages are auto-acknowledged, not queued. This falg only applies in conjunction with the shunt flag
0x04	wait-until-persisted	`1`: wait until datastore-key changes are persisted (only relevant if auto-acknowledge is `1`)
0x08	wait-until-shared	`1`: wait until datastore-key changes are shared on distributed persistence network (only relevant if auto-acknowledge is `1`)

application/octet-stream

RESPONSE #/responses/WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

code == 222

For as long as the connection remains opened, all datastore-keys--subscribed to using this subscribe request--may emit 222 responses.

Each 222 event requires a subsequent acknowledgment by the client.

The following details the possible messages that will come across.

An example event stream coming across the Web socket for a non-shunt subscription:

syntax	bytes	value
loop {
unixtime-millis	8
}

The events stream are just unixtime-milliss, indicating messages are present to be retrieved via the getter.

An example event stream coming across the Web scoket for a shunt subscription:

syntax	bytes	value
flags	1
loop {
unixtime-millis	8
message-len	8	ML = length(message) + 1
message	*
}

flags: bytes

A byte of flags.

The 0x80 (done) flag--if 1--indicates that all messages in the descriptor loop are done; do not have fragment bytes outstanding. A 0 value indicates that the last message in the descriptor loop is fragmented and bytes are still outstanding. Those bytes will come down in the imediatelly following 222 subscription events. The unixtime-millis will be repeated for all fragments. The aggregate fragments are all transmitted for the message if the 0x80 (done) flag comes down as a 1 or the fragmented message is not the last message in the descriptor loop.

value	name	description
0x80	done	`1`: all the messages in the descriptor loop are done--do not have outstanding fragments--`0`: the last message in the descriptor loop has additional fragments, to come down in the imediatelly following 222 subscription events

unixtime-millis: number

Non-unique UNIX Epoch timestamp (milliseconds) of the message.

message-len: number

Length in bytes of message.

message: bytes

The message byte stream value.

code == 400

Bad request:

no handshake
message outside handshake constraints
cannot process input
cannot write, broker not an active steward of user's data
- check broker-lookup to find active steward and write there
cannot continue, invalid stewardship mode

code == 404 #/responses/404-datastore-key

Invalid datastore-key requested; segment-key or identity mismatch.


Authorization WSS

Check if connection is live.

WIRE watchdog

Tags: flow-control

Check if connection is live. Broker has until ack-timeout-millis (as per handshake) to respond with a 200/woof.

application/octet-stream

syntax	bytes	value
req-id	8
len	8	1
opcode	1	0x50

req-id: number

Request ID: a connection specific unique identifier of the request/responses. Has no meaning beyond connection.

This is the request ID who's fragmented response we're acknowledging.

len: number

Length in bytes constituting the remainder of this message: number of bytes that follow this len.

opcode: bytes

Operation code.

application/octet-stream

RESPONSE #/responses/WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

code == 200

Woof: connection is live.

code == 429 #/responses/429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.


Authorization WSS

Response definitions

206

A fragment of the full response. Payload byte-stream to reconstitute--in-order--into the aggregate as described by the 200 response code.

Subsequent 206 responses may follow--in-order for reconstituting the response byte stream--until the aggregate response is finalized with a 200 response code.

Every 206 response must be acknowledged by the client before the broker will send subsequent fragments.

246

Inconclusive - check other broker for newer data.

The 246 status code has the same structure as a 200/OK and indicates success, but requires caller to second-guess this result.

It is always returned by getter calls on:

passive hosts in cases where an active host would return a 200/OK.
pour-active-stewardship hosts when request is for data in a segment-key that hasn't been explicitly written to via data or backchannel APIs. Once a segment-key is written to by one of these APIs--since the broker was put into pour-active-stewardship mode for an identity--the pour-active-steward will return a 200/OK.

Once both complimentary hosts--reported by broker-lookup--respond with a value and a status code, consult the following decision matrix as to which broker's value to use :

	200/OK from ACTIVE (pour)	246/Inconclusive from ACTIVE (pour)	422/Unprocessable from ACTIVE (pour)	246/Inconclusive from PASSIVE (drain)	ERROR from PASSIVE (drain)	PASSIVE (drain) not set
200/OK from ACTIVE (pour)	X	X	X	use ACTIVE's value	use ACTIVE's value	use ACTIVE's value
246/Inconclusive from ACTIVE (pour)	X	X	X	use PASSIVE's value	use ACTIVE's value	use ACTIVE's value
422/Unprocessable from ACTIVE (pour)	X	X	X	use PASSIVE's value	ERROR	ERROR
246/Inconclusive from PASSIVE (drain)	use ACTIVE's value	use PASSIVE's value	use PASSIVE's value	X	X	X
ERROR from PASSIVE (drain)	use ACTIVE's value	use ACTIVE's value	ERROR	X	X	X
PASSIVE (drain) not set	use ACTIVE's value	use ACTIVE's value	ERROR	X	X	X

The decision which broker's value to use as source of truth depends on their returned status codes.

401

For an endpoint protected with the token security definition, an "Authorization" header was not provided a valid token--as returned from the authenticate endpoint.

403

There is an access violation for this valid and authenticated identity against this valid datastore-key.

The authenticated identity has insufficient access rights to this valid datastore-key for the operation. Review the access rights as manipulated with the settings endpoints.
The API request would exceed rates and limits as set out within the authorities at the current subscription plan or datastore-key entry-fee.

Errors equally apply to "inviee" identities.

Results in one or more of the following error message strings:

no write access
no publish access
storage limit exceeded
read-rate exceeded
write-rate exceeded

The message enum might be extended by broker system.

Broker systems might not throw up this response when read and write rates are exceeded. Instead a broker system might start throttling responses or responding at a lower-priority.

405

Method not allowed.

The broker-lookup subsystem is not provided/enabled by this broker.

409

Setter encountered a conflict. Consult error message:

write-conflict:

Occurs when a data set operation includes a write-gate parameter that has a SHA256 value which does not match the SHA256 hash of the current (in-datastore) value of a segment-key.

A data write is requested on a segment-key that has an unexpected value in the datastore. Implies there is a concurrent write issue.
datastore-key conflict:

Datastore-key ownership conflict; segment-key @ identity already reserved.

422

Unprocessable - not filled yet, check draining host for data.

Upon receipt of a 422 status code as a response to a getter call the client must attempt the getter call with the complementary draining passive broker as reported by broker-lookup--if any.

Refer to write-up on the 246 status code for a decision matrix as to what the client should do.

429

Client is calling the API too frequently.

Conditions for this response to occur are broker system dependant.

502

Cannot reach data.

WIRE

WebSocket Requests may have one or more response events (this). Each response event from the overhide broker is a byte-stream in the following format:

syntax	bytes	value
req-id	8
len	8	length(response) + 6
total-fragments	4
code	2
response	*

req-id: number

Request ID of the request this response/subscription event corresponds to.

len: number

Length in bytes of this response message: length(response) + 6 bytes.

total-fragments: number

Total number of messages constituting all fragments for this response.

For unfragmented responses this value is 1.

For fragment responses (code 206 followed by a code 200) this value may be useful to gauge progress of receiving the full response: tally of already received versus this value.

code: number

One of the WIRE protocol response codes.

They roughly match HTTP response codes.

Refer to the RESPONSES section of each particular WIRE event for a description of possible code values in this corresponding response event.

response: bytes

For most error codes this is a UTF-8 encoded string with error text.

For codes 200, 206, 222, 246, and 413, this is a response byte-stream.

Each WIRE event's RESPONSES section details which response codes apply; specifying the syntax and semantics of this response byte-stream descriptor.

Codes 200 and 206

For code 206 the response is a non-final fragment of an aggregate response. A code 206 event from the broker needs to be acknowledged by the client.

Code 246

Under certain conditions code 246 will be returned instead of code 200. Both code 200 and code 246 signify successful completion of a response.

See section on code 246 for the decision matrix of when the code is returned instead of code 200.

404-datastore-key

Invalid datastore-key requested; segment-key or identity mismatch.

404-cannot-resolve

Cannot resolve address.

409-identity-conflict

Go play a lottery: the generated identity conflicts with some other identity or ended up being a restricted number <10000.

Try a different secret-phrase.

Schema definitions

Authorities: object

read-rate: integer

Maximum amount of data allowed to be read per unit time for the provided identity: in bytes/hour.

If client's read-rate is reached within an hour, reads are throttled. Throttling is broker implementation specific.

If negative, the rate is unlimited.

write-rate: integer

Maximum amount of data allowed to be written per unit time for the provided identity: in bytes/hour.

If client's write-rate is reached within an hour, writes are throttled. Throttling is broker implementation specific.

If negative, the rate is unlimited.

storage-used: integer

Amount of data in bytes stored by this identity on this broker system.

storage-limit: integer

Maximum amoun tof data in bytes that can be stored by this identity on this broker system at the current subscription level.

If negative, storage is unlimited.

active-until: string

Date-time until when this identity has an 'active' subscription at the currently authorized level.

It's possible once this subscription level expires the identity continues to hava a subscription at a reduced level. A subscription level expiry indicates some remuneration provider transaction to the broker has lapsed. The remuneration provider might indicate other transactions to the broker that haven't expired.

The date-time is a string in ISO 8601/RFC3339 format.

A 'null' value indicates no expiry of current subscription level.

available-until: string

Date-time until when data belonging to this identity will be retained within the broker system.

The date-time is a string in ISO 8601/RFC3339 format.

A 'null' value indicates no expiry; data retained indefinitely.

DatastoreKeySettings: object

allow-write: string , x ∈ { self , signed , invitee }

Indicate who is allowed to write to the datastore-key. The "self" value is default and means only owner of segment-key has write rights.

Value of "signed" indicates allowed-writers property must necessairly list identities allowed to write into this segment-key.
Other users using this broker system attempting to write to this segment-key have their authentication token checked against the identities in allowed-writers list. These could be real authenticated broker identities or invitee identities.

Value of "invitee" indicates an invitee of this identity is allowed to write, see the guest credentials endpoint: no allowed-writers check.

allowed-writers: object[]

If allow-write is "self" this parameter is ignored.

If allow-write is "signed", this parameter is a list of identities to identify users allowed to write data to this datastore-key (segment-key @ identity). These could be real authenticated broker identities or invitee identities.

Other users using this broker system attempting to write to this segment-key have their authentication token checked against the identities in this list.

object

identity: string: identity identifying user allowed to write data.

allow-publish: string , x ∈ { self , any , signed , invitee }

Indicate who is allowed to publish messages to the datastore-key's backchannel'. The "self" value is default and means only owner of segment-key has publish rights.

Value of "signed" indicates allowed-publishers property must necessairly list identities allowed to publish messages into this segment-key.
Other users using this broker system attempting to publish to this segment-key have their authentication token checked against the identities in allowed-publishers list. These could be real authenticated broker identities or invitee identities.

Value of "invitee" indicates an invitee of this identity is allowed to publish, see the guest credentials endpoint.

allowed-publishers: object[]

if allow-publish is "self" or "any" this parameter is ignored.

If allow-publish is "signed", this parameter is a list of identities to identify users allowed to publish messages to this datastore-key (segment-key @ identity). These could be real authenticated broker identities or invitee identities.

Other users using this broker system attempting to publish to this segment-key have their authentication token checked against the identities in this list.

object

identity: string: identity identifying user allowed to write data.

allow-delegation: string , x ∈ { none , any , signed , invitee }

Indicate who is allowed to write data to this segment-key as a delegate and who's allowed to work with delegate-qualified backchannels on this segment-key: it's the same group.

Value of "signed" indicates allowed-delegates property must necessairly list identities allowed to act as delegates for this segment-key. Delegates attempting to use this segment-key have their identity checked against the allowed-delegates list.

Value of "invitee" indicates an invitee of this identity are allowed to be delegates, see the guest credentials endpoint.

allowed-delegates: object[]

if allow-delegation is "none" or "any" this parameter is ignored.

If allow-delegation is "signed", this parameter is a list of identities to identify users allowed to be delegates for this datastore-key (segment-key @ identity). These could be real authenticated broker identities or invitee identities.

Delegates attempting to use this segment-key have their authentication token checked against the identities in this list.

object

identity: string: identity identifying user allowed to become delegates.

allow-others-publish-all-delegates: boolean

If true backchannel message posting allows messages publishing to all delegates by non-owner--the glob * value for the event's delegate parameter can be used by all allowed-publishers.

allow-others-read-all-delegates: boolean

If true allows non-owners to use the "get all delegate values" event.

entry-fee: object[]

The entry-fee condition applies if allow-publish, allow-write, or allow-delegation is "any", "signed", or "invitee": anytime someone other than "self" is allowed some access.

For every segment-key gated with an entry-fee the accessing user's payments to the segment-key's owner have to be verified. These are cached by the broker such that subsequent access to segment-keys with the same entry-fee value are accessed quickly without performing the same check. However, it is prudent to limit the number of different valued entry-fees: ensure you limit the number of different entry-fee values to a handful.

It may be prudent to not opt-in this segment-key into distributed persistence: distributed persistence may make the value available regardless of entry-fee established.

It may be prudent to keep the number of segment-keys with an entry-fee down to a managable number--perhaps only one per critical path of an authorization tier in your service's (app's) functional flow. The entry-fee amounts may need to change as per business needs; keeping the number of such configuration points managable may be important.

If a transaction is made by the accessing user to the owning user, the accessing user must re-authorize to have the new transaction considered.

object

value: number

Amount of currency--as per remuneration-key required to access this segment-key.

A 0-value implies at least one transaction of any value (perhaps just the ledger transaction fees) must be present.

within-seconds: number

A 0-value means for all-time.

remuneration-key: string

One of the remuneration provider keys from /capabilities/remuneration-providers

The provided address corresponds to one of the remuneration providers, define it.

duplicate-delegate-policy: string

If a delegate is a visitor, the delegate might provide a different invitee-secret-phrase for the same invitee-user-address. To prevent the same invitee-user-address from using multiples of a datastore-key's delegate allotment, this policy may be enforced.

Note: enforcement of this policy is dependant on a broker-specific hash of the invitee-user-address being available in the visitor's authentication token. This hashed invitee-user-address is not stored off outside the broker's metadata (i.e. on the distributed persistence network).

What should the system do if a visitor delegate attempts to use the same invitee-user-address with a different visitor identity? Allowed values:

key	description
"replace-identity"	replace the previous identity associated with invitee-user-address by this new currently-used one
"keep-all"	allow delegate storage for all identities of the same invitee-user-address

Note that this policy is a complement to the delegate-data-ttl-seconds configuration point.

limit-bytes: number

Maximum number of bytes of total content allowed for this segment-key (if not delegated) or per delegate of this segment-key (if delegated). This includes the written value as well as all published messages. If the segment-key has delegates, the value is per delegate: the actual limit is multiplied by the number of delegates.

overlimit-publish-action: string

What should the system do if limit-bytes is exceeded on a message publish? Allowed values:

key	description
"reject"	reject the message publish with error
"drop-newest"	publish the message but drop newest messages to make space
"drop-oldest"	publish the message but drop oldest messages to make space

limit-others-read-rate: number

Maximum rate of bytes/hour each user, other than the owner,is allowed to read at from this segment-key.

Once reached by a user, reads might drop in priority, be throttled, or be denied with a 403 response code

limit-others-write-rate: number

Maximum rate of bytes/hour each user, other than the owner,is allowed to write or publish at to this segment-key.

Once reached by a user, writes might drop in priority, be throttled, or be denied with a 403 response code

limit-delegates: number

Number of delegates allowed for the segment-key.

delegate-data-ttl-seconds: number

Time-to-live--in seconds--of delegate data before it is elegible for cleanup. Refreshed on any activity on the segment-key qualified by the delegate.

opt-in: boolean

Opt-in this segment-key to be stored on this broker's decentralized persistence.

GUID: object

Globally Unique ID -- An identifier globally unique on a particular network: identifies a user's data on the persistence network.

type-key: string , x ∈ { ipns-ri }

Identifies the network this GUID is for.

Type	Notes
ipns-ri	An overhide reference implementation GUID as per using IPNS. `guid` value will be in the format `<IPNS name>:<private-key>`, where `<IPNS name>` is the public hash visible to all, `<private-key>` must not be shared, it's included to share with other brokers to enable their custody of identities data.

guid: string

The identifier for given network.

ImportExportPayload: object

settings: object[]

object

Settings for datastore-key to transfer.

segment-key: string

See glossary.

identity: string

Optional identity. If provided, must be one of public restricted identities: 0 .. 9999. If not provided, identity is that of token owner.

See glossary.

settings: DatastoreKeySettings

values: object[]

object

Datastore values to transfer.

segment-key: string

See glossary.

identity: string

Optional identity. If provided, must be one of public restricted identities: 0 .. 9999. If not provided, identity is that of token owner.

See glossary.

delegate: string

If value is for a delegate of this segment-key, this is the delegate's identity.

bytes: string

The data byte stream base64 encoded.

messages: object[]

object

All messages from the backchannel at the givent datastore-key

Messages enqueued at datastore-key (segment-key @ identity) ordered by increasing non-unique unixtime-millis.

Messages returned may not have unique unixtime-millis--more than one message may have the same unixtime-millis.

The broker guarantees that the messages in the payload comprise all unacknowledged message with a unixtime-millis up-to and including the highest unixtime-millis.

segment-key: string

See glossary.

identity: string

Optional identity. If provided, must be one of public restricted identities: 0 .. 9999. If not provided, identity is that of token owner.

See glossary.

delegate: string

If messages are for a delegate of this segment-key, this is the delegate's identity.

messages: object[]

Message

Message: object

unixtime-millis: integer: Non-unique UNIX Epoch timestamp (milliseconds) of the message.
message: string: The message byte stream base64 encoded.

Metrics: object

last-change-unix-time: number: Unix-time (seconds since January 1, 1970 UTC) of last modification of any kind.
value-storage-bytes: number: Size in bytes of the data area; sans backchannel or delegates.
value-read-count: number: Count of data area read operations; sans backchannel or delegates.
value-write-count: number: Count of data area write operations; sans backchannel or delegates.
messages-storage-bytes: number: Size in bytes of the backchannel messages; sans delegates.
messages-count: number: Count of backchannel messages; sans delegates.
messages-acknowledged: number: Count of acknowledged backchannel messages; sans delegates.
delegates-count: number: Count of delegate identities using storage in any way.
delegate-values-storage-bytes: number: Size in bytes of the delegate data area; sans backchannel.
delegate-values-read-count: number: Count of delegate data area read operations; sans backchannel.
delegate-values-write-count: number: Count of delegate data area write operations; sans backchannel.
delegate-messages-storage-bytes: number: Size in bytes of the delegate backchannel messages.
delegate-messages-count: number: Count of delegate backchannel messages.
delegate-messages-acknowledged: number: Count of acknowledged backchannel messagess.

PersistenceStatus: object

working-memory: string: SHA256 content hash as '0x' prefixed upper-case hex string of the value in the broker's volatile memory.
permanent-memory: string: SHA256 content hash as '0x' prefixed upper-case hex string of the value in the broker's volatile memory.
shared-memory: string: SHA256 content hash as '0x' prefixed upper-case hex string of the value in the broker's volatile memory.

RemunerationKey: string

Tag representing a ledger network on which all addresses operate: user-address, broker-address, service-address, and invitee/visitor addresses.

In the overhide system, ledger networks are abstracted via an API from remuneration providers. This list is the list of standard remuneration providers (ledgers) supported by overhide.

Brokers may support a subset of this list or other remuneration providers altogether; however, it's best for the ecosystem to keep this list exhaustive. Some functionality is designed to support just the remuneration providers listed: e.g. broker-lookup functionality.

Accepted Values:

Remuneration Key	Network	Notes
ETH	Ethereum mainnet	API link
RINKEBY	Ethereum rinkeby testnet	API link
OH-LEDGER	overhide-ledger	API link
OH-LEDGER-TEST	overhide-ledger test network	API link

RemunerationProvider: object

Link between a broker-address and a remuneration provider identified by a unique remuneration-key.

key: string: Remuneration provider identifying key string.
broker-address: string: This broker's specific public payment address with the reumneration provider. This is the public address to which a subscription payment needs to be made from a user identity.
description-md: string: Description Markdown formatted text for this remuneration provider. Can have links and other markdown directing user to more information about this remuneration provider.

RemunerationTier: object

key: string: Remuneration provider's tier identifying key string.
description-md: string: Description Markdown formatted text for this remuneration tier. Can have links and other markdown directing user to more information about this remuneration provider tier.

Transaction: object

transaction-value: number

Value of the transaction.

transaction-date: string

Date-time timestamp of the transaction.

The date-time is a string in ISO 8601/RFC3339 format.