API Reference

Methods: InitSetupAccount, InitConvertGoogleUser, InitCompleteAccount, Deinit, AccountSetPassword, AccountGetPaymentPlan, AccountLogin, Probe, AuthorityCreate, AuthoritySet, AuthorityGet, AuthorityList, AuthorityDestroy, SpaceCreate, SpaceGenerateKey, SpaceGet, SpaceSet, SpaceRedeployKick, SpaceSetRxhtml, SpaceGetRxhtml, SpaceSetPolicy, SpaceGetPolicy, SpaceMetrics, SpaceDelete, SpaceSetRole, SpaceListDevelopers, SpaceReflect, SpaceList, PushRegister, DomainMap, DomainReflect, DomainMapDocument, DomainList, DomainListBySpace, DomainGetVapidPublicKey, DomainUnmap, DomainGet, DocumentAuthorize, DocumentAuthorizeDomain, DocumentAuthorizeWithReset, DocumentAuthorizeDomainWithReset, DocumentCreate, DocumentDelete, DocumentList, MessageDirectSend, MessageDirectSendOnce, ConnectionCreate, ConnectionCreateViaDomain, ConnectionSend, ConnectionPassword, ConnectionSendOnce, ConnectionCanAttach, ConnectionAttach, ConnectionUpdate, ConnectionEnd, DocumentsHashPassword, BillingConnectionCreate, ConfigureMakeOrGetAssetKey, AttachmentStart, AttachmentStartByDomain, AttachmentAppend, AttachmentFinish

Method: InitSetupAccount

This initiates developer machine via email verification.

Parameters

namerequiredtypedocumentation
emailyesStringThe email of an Adama developer.

Template

connection.InitSetupAccount(email, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: InitConvertGoogleUser

The converts and validates a google token into an Adama token.

Parameters

namerequiredtypedocumentation
access-tokenyesStringA token from a third party authorization service.

Template

connection.InitConvertGoogleUser(access-token, {
  success: function(response) {
    // response.identity
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
identityStringA private token used to authenticate to Adama.

Method: InitCompleteAccount

This establishes a developer machine via email verification.

Copy the code from the email into this request.

The server will generate a key-pair and send the secret to the client to stash within their config, and the public key will be stored to validate future requests made by this developer machine.

A public key will be held onto for 30 days.

Parameters

namerequiredtypedocumentation
emailyesStringThe email of an Adama developer.
revokenoBooleanA flag to indicate wiping out previously granted tokens.
codeyesStringA randomly (secure) generated code to validate a user via 2FA auth (via email).

Template

connection.InitCompleteAccount(email, revoke, code, {
  success: function(response) {
    // response.identity
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
identityStringA private token used to authenticate to Adama.

Method: Deinit

This will destroy a developer account. We require all spaces to be deleted along with all authorities.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.

Template

connection.Deinit(identity, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: AccountSetPassword

Set the password for an Adama developer.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
passwordyesStringThe password for your account or a document

Template

connection.AccountSetPassword(identity, password, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: AccountGetPaymentPlan

Get the payment plan information for the developer.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.

Template

connection.AccountGetPaymentPlan(identity, {
  success: function(response) {
    // response.paymentPlan
    // response.publishableKey
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
payment-planStringPayment plan name. The current default is "none" which can be upgraded to "public".
publishable-keyStringThe public key from the merchant provider.

Method: AccountLogin

Sign an Adama developer in with an email and password pair.

Parameters

namerequiredtypedocumentation
emailyesStringThe email of an Adama developer.
passwordyesStringThe password for your account or a document

Template

connection.AccountLogin(email, password, {
  success: function(response) {
    // response.identity
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
identityStringA private token used to authenticate to Adama.

Method: Probe

This is useful to validate an identity without executing anything.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.

Template

connection.Probe(identity, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: AuthorityCreate

Create an authority. See Authentication for more details.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.

Template

connection.AuthorityCreate(identity, {
  success: function(response) {
    // response.authority
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
authorityStringAn authority is collection of third party users authenticated via a public keystore.

Method: AuthoritySet

Set the public keystore for the authority.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
authorityyesStringAn authority is collection of users held together via a key store.
key-storeyesObjectNodeA collection of public keys used to validate an identity within an authority.

Template

connection.AuthoritySet(identity, authority, key-store, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: AuthorityGet

Get the public keystore for the authority.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
authorityyesStringAn authority is collection of users held together via a key store.

Template

connection.AuthorityGet(identity, authority, {
  success: function(response) {
    // response.keystore
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
keystoreObjectNodeA bunch of public keys to validate tokens for an authority.

Method: AuthorityList

List authorities for the given developer.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.

Template

connection.AuthorityList(identity, {
  next: function(payload) {
    // payload.authority
  },
  complete: function() {
  },
  failure: function(reason) {
  }
});

Streaming payload fields

nametypedocumentation
authorityStringAn authority is collection of third party users authenticated via a public keystore.

Method: AuthorityDestroy

Destroy an authority.

This is exceptionally dangerous as it will break authentication for any users that have tokens based on that authority.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
authorityyesStringAn authority is collection of users held together via a key store.

Template

connection.AuthorityDestroy(identity, authority, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: SpaceCreate

Create a space.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'
templatenoStringWhen creating a space, the template is a known special identifier for how to bootstrap the defaults. Examples: none (default when template parameter not present).

Template

connection.SpaceCreate(identity, space, template, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: SpaceGenerateKey

Generate a secret key for a space.

First party and third party services require secrets such as api tokens or credentials.

These credentials must be encrypted within the Adama document using a public-private key, and the secret is derived via a key exchange. Here, the server will generate a public/private key pair and store the private key securely and give the developer a public key. The developer then generates a public/private key, encrypts the token with the private key, throws away the private key, and then embeds the key id, the developer's public key, and the encrypted credential within the adama source code.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'

Template

connection.SpaceGenerateKey(identity, space, {
  success: function(response) {
    // response.keyId
    // response.publicKey
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
key-idIntegerUnique id of the private-key used for a secret.
public-keyStringA public key to decrypt a secret with key arrangement.

Method: SpaceGet

Get the deployment plan for a space.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'

Template

connection.SpaceGet(identity, space, {
  success: function(response) {
    // response.plan
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
planObjectNodeA plan is a predictable mapping of keys to implementations. The core reason for having multiple concurrent implementations is to have a smooth and orderly deployment. See deployment plans for more information.

Method: SpaceSet

Set the deployment plan for a space.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'
planyesObjectNodeThis 'plan' parameter contains multiple Adama scripts all gated on various rules. These rules allow for a migration to happen slowly on your schedule. Note: this value will validated such that the scripts are valid, compile, and will not have any major regressions during role out.

Template

connection.SpaceSet(identity, space, plan, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: SpaceRedeployKick

A diagnostic call to optimistically to refresh a space's deployment

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'

Template

connection.SpaceRedeployKick(identity, space, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: SpaceSetRxhtml

Set the RxHTML forest for the space when viewed via a domain name.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'
rxhtmlyesStringA RxHTML forest which provides simplified web hosting.

Template

connection.SpaceSetRxhtml(identity, space, rxhtml, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: SpaceGetRxhtml

Get the RxHTML forest for the space when viewed via a domain name.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'

Template

connection.SpaceGetRxhtml(identity, space, {
  success: function(response) {
    // response.rxhtml
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
rxhtmlStringThe RxHTML forest for a space.

Method: SpaceSetPolicy

Set the access control policy for a space

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'
access-policyyesObjectNodeA policy to control who can do what against a space.

Template

connection.SpaceSetPolicy(identity, space, access-policy, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: SpaceGetPolicy

returns the

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'

Template

connection.SpaceGetPolicy(identity, space, {
  success: function(response) {
    // response.accessPolicy
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
access-policyObjectNodeA policy to control who can do what against a space.

Method: SpaceMetrics

For regional proxies to emit metrics for a document

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'
prefixnoStringA prefix of a key used to filter results in a listing or computation
metric-querynoObjectNodeA metric query to override the behavior on aggregation for specific fields

Template

connection.SpaceMetrics(identity, space, prefix, metric-query, {
  success: function(response) {
    // response.metrics
    // response.count
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
metricsObjectNodeA metrics object is a bunch of counters/event-tally
countIntegerThe number of items considered/available.

Method: SpaceDelete

Delete a space.

This requires no documents to be within the space, and this removes the space from use until garbage collection ensures no documents were created for that space after deletion. A space may be reserved for 90 minutes until the system is absolutely sure no documents will leak.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'

Template

connection.SpaceDelete(identity, space, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: SpaceSetRole

Set the role of an Adama developer for a particular space.

Spaces can be shared among Adama developers.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'
emailyesStringThe email of an Adama developer.
roleyesStringThe role of a user may determine their capabilities to perform actions.

Template

connection.SpaceSetRole(identity, space, email, role, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: SpaceListDevelopers

List the developers with access to this space

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'

Template

connection.SpaceListDevelopers(identity, space, {
  next: function(payload) {
    // payload.email
    // payload.role
  },
  complete: function() {
  },
  failure: function(reason) {
  }
});

Streaming payload fields

nametypedocumentation
emailStringA developer email
roleStringEach developer has a role to a document.

Method: SpaceReflect

Get a schema for the space.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'
keyyesStringWithin a space, documents are organized within a map and the 'key' parameter will uniquely identify documents. Keys are lower case ASCII using the regex [a-z0-9._-]* for validation

Template

connection.SpaceReflect(identity, space, key, {
  success: function(response) {
    // response.reflection
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
reflectionObjectNodeSchema of a document.

Method: SpaceList

List the spaces available to the user.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
markernoStringA key to skip ahead a listing. When iterating, values will be returned that are after marker. To paginate an entire list, pick the last key or name returned and use it as the next marker.
limitnoIntegerMaximum number of items to return during a streaming list.

Template

connection.SpaceList(identity, marker, limit, {
  next: function(payload) {
    // payload.space
    // payload.role
    // payload.created
    // payload.enabled
    // payload.storageBytes
  },
  complete: function() {
  },
  failure: function(reason) {
  }
});

Streaming payload fields

nametypedocumentation
spaceStringA space which is a collection of documents with a common Adama schema.
roleStringEach developer has a role to a document.
createdStringWhen the item was created.
enabledBooleanIs the item in question enabled.
storage-bytesLongThe storage used.

Method: PushRegister

Register a device for push notifications

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
domainyesStringA domain name.
subscriptionyesObjectNodeA push subscription which is an abstract package for push notifications
device-infoyesObjectNodeInformation about a device

Template

connection.PushRegister(identity, domain, subscription, device-info, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: DomainMap

Map a domain to a space.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
domainyesStringA domain name.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'
certificatenoStringA TLS/SSL Certificate encoded as json.

Template

connection.DomainMap(identity, domain, space, certificate, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: DomainReflect

Get a schema for the domain

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
domainyesStringA domain name.

Template

connection.DomainReflect(identity, domain, {
  success: function(response) {
    // response.reflection
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
reflectionObjectNodeSchema of a document.

Method: DomainMapDocument

Map a domain to a space.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
domainyesStringA domain name.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'
keyyesStringWithin a space, documents are organized within a map and the 'key' parameter will uniquely identify documents. Keys are lower case ASCII using the regex [a-z0-9._-]* for validation
routenoBooleanA domain can route to the space or to a document's handler
certificatenoStringA TLS/SSL Certificate encoded as json.

Template

connection.DomainMapDocument(identity, domain, space, key, route, certificate, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: DomainList

List the domains for the given developer

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.

Template

connection.DomainList(identity, {
  next: function(payload) {
    // payload.domain
    // payload.space
    // payload.key
    // payload.route
  },
  complete: function() {
  },
  failure: function(reason) {
  }
});

Streaming payload fields

nametypedocumentation
domainStringA domain name.
spaceStringA space which is a collection of documents with a common Adama schema.
keyStringThe key.
routeBooleanDoes the domain route GET to the document or the space.

Method: DomainListBySpace

List the domains for the given developer

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'

Template

connection.DomainListBySpace(identity, space, {
  next: function(payload) {
    // payload.domain
    // payload.space
    // payload.key
    // payload.route
  },
  complete: function() {
  },
  failure: function(reason) {
  }
});

Streaming payload fields

nametypedocumentation
domainStringA domain name.
spaceStringA space which is a collection of documents with a common Adama schema.
keyStringThe key.
routeBooleanDoes the domain route GET to the document or the space.

Method: DomainGetVapidPublicKey

Get the public key for the VAPID

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
domainyesStringA domain name.

Template

connection.DomainGetVapidPublicKey(identity, domain, {
  success: function(response) {
    // response.publicKey
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
public-keyStringA public key to decrypt a secret with key arrangement.

Method: DomainUnmap

Unmap a domain

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
domainyesStringA domain name.

Template

connection.DomainUnmap(identity, domain, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: DomainGet

Get the domain mapping

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
domainyesStringA domain name.

Template

connection.DomainGet(identity, domain, {
  success: function(response) {
    // response.space
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
spaceStringA space which is a collection of documents with a common Adama schema.

Method: DocumentAuthorize

Authorize a username and password against a document.

Parameters

namerequiredtypedocumentation
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'
keyyesStringWithin a space, documents are organized within a map and the 'key' parameter will uniquely identify documents. Keys are lower case ASCII using the regex [a-z0-9._-]* for validation
usernameyesStringThe username for a document authorization
passwordyesStringThe password for your account or a document

Template

connection.DocumentAuthorize(space, key, username, password, {
  success: function(response) {
    // response.identity
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
identityStringA private token used to authenticate to Adama.

Method: DocumentAuthorizeDomain

Authorize a username and password against a document via a domain

Parameters

namerequiredtypedocumentation
domainyesStringA domain name.
usernameyesStringThe username for a document authorization
passwordyesStringThe password for your account or a document

Template

connection.DocumentAuthorizeDomain(domain, username, password, {
  success: function(response) {
    // response.identity
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
identityStringA private token used to authenticate to Adama.

Method: DocumentAuthorizeWithReset

Authorize a username and password against a document, and set a new password

Parameters

namerequiredtypedocumentation
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'
keyyesStringWithin a space, documents are organized within a map and the 'key' parameter will uniquely identify documents. Keys are lower case ASCII using the regex [a-z0-9._-]* for validation
usernameyesStringThe username for a document authorization
passwordyesStringThe password for your account or a document
new_passwordyesStringThe new password for your account or document

Template

connection.DocumentAuthorizeWithReset(space, key, username, password, new_password, {
  success: function(response) {
    // response.identity
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
identityStringA private token used to authenticate to Adama.

Method: DocumentAuthorizeDomainWithReset

Authorize a username and password against a document, and set a new password

Parameters

namerequiredtypedocumentation
domainyesStringA domain name.
usernameyesStringThe username for a document authorization
passwordyesStringThe password for your account or a document
new_passwordyesStringThe new password for your account or document

Template

connection.DocumentAuthorizeDomainWithReset(domain, username, password, new_password, {
  success: function(response) {
    // response.identity
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
identityStringA private token used to authenticate to Adama.

Method: DocumentCreate

Create a document.

The entropy allows the randomization of the document to be fixed at construction time.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'
keyyesStringWithin a space, documents are organized within a map and the 'key' parameter will uniquely identify documents. Keys are lower case ASCII using the regex [a-z0-9._-]* for validation
entropynoStringEach document has a random number generator. When 'entropy' is present, it will seed the random number generate such that the randomness is now deterministic at the start.
argyesObjectNodeThe parameter for a document's @construct event.

Template

connection.DocumentCreate(identity, space, key, entropy, arg, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: DocumentDelete

Delete a document (invokes the @delete document policy).

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'
keyyesStringWithin a space, documents are organized within a map and the 'key' parameter will uniquely identify documents. Keys are lower case ASCII using the regex [a-z0-9._-]* for validation

Template

connection.DocumentDelete(identity, space, key, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: DocumentList

List documents within a space which are after the given marker.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'
markernoStringA key to skip ahead a listing. When iterating, values will be returned that are after marker. To paginate an entire list, pick the last key or name returned and use it as the next marker.
limitnoIntegerMaximum number of items to return during a streaming list.

Template

connection.DocumentList(identity, space, marker, limit, {
  next: function(payload) {
    // payload.key
    // payload.created
    // payload.updated
    // payload.seq
  },
  complete: function() {
  },
  failure: function(reason) {
  }
});

Streaming payload fields

nametypedocumentation
keyStringThe key.
createdStringWhen the item was created.
updatedStringWhen the item was last updated.
seqIntegerThe sequencer for the item.

Method: MessageDirectSend

Send a message to a document without a connection

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'
keyyesStringWithin a space, documents are organized within a map and the 'key' parameter will uniquely identify documents. Keys are lower case ASCII using the regex [a-z0-9._-]* for validation
channelyesStringEach document has multiple channels available to send messages too.
messageyesJsonNodeThe object sent to a document which will be the parameter for a channel handler.

Template

connection.MessageDirectSend(identity, space, key, channel, message, {
  success: function(response) {
    // response.seq
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
seqIntegerThe sequencer for the item.

Method: MessageDirectSendOnce

Send a message to a document without a connection

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'
keyyesStringWithin a space, documents are organized within a map and the 'key' parameter will uniquely identify documents. Keys are lower case ASCII using the regex [a-z0-9._-]* for validation
dedupenoStringA key used to dedupe request such that at-most once processing is used.
channelyesStringEach document has multiple channels available to send messages too.
messageyesJsonNodeThe object sent to a document which will be the parameter for a channel handler.

Template

connection.MessageDirectSendOnce(identity, space, key, dedupe, channel, message, {
  success: function(response) {
    // response.seq
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
seqIntegerThe sequencer for the item.

Method: ConnectionCreate

Create a connection to a document.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'
keyyesStringWithin a space, documents are organized within a map and the 'key' parameter will uniquely identify documents. Keys are lower case ASCII using the regex [a-z0-9._-]* for validation
viewer-statenoObjectNodeA connection to a document has a side-channel for passing information about the client's view into the evaluation of bubbles. This allows for developers to implement real-time queries and pagination.

Template

connection.ConnectionCreate(identity, space, key, viewer-state, {
  next: function(payload) {
    // payload.delta
  },
  complete: function() {
  },
  failure: function(reason) {
  }
});

Streaming payload fields

nametypedocumentation
deltaObjectNodeA json delta representing a change of data. See the delta format for more information.

Method: ConnectionCreateViaDomain

Create a connection to a document via a domain name.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
domainyesStringA domain name.
viewer-statenoObjectNodeA connection to a document has a side-channel for passing information about the client's view into the evaluation of bubbles. This allows for developers to implement real-time queries and pagination.

Template

connection.ConnectionCreateViaDomain(identity, domain, viewer-state, {
  next: function(payload) {
    // payload.delta
  },
  complete: function() {
  },
  failure: function(reason) {
  }
});

Streaming payload fields

nametypedocumentation
deltaObjectNodeA json delta representing a change of data. See the delta format for more information.

Method: ConnectionSend

Send a message to the document on the given channel.

Parameters

namerequiredtypedocumentation
channelyesStringEach document has multiple channels available to send messages too.
messageyesJsonNodeThe object sent to a document which will be the parameter for a channel handler.

Template

stream.Send(channel, message, {
  success: function(response) {
    // response.seq
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
seqIntegerThe sequencer for the item.

Method: ConnectionPassword

Set the viewer's password to the document; requires their old password.

Parameters

namerequiredtypedocumentation
usernameyesStringThe username for a document authorization
passwordyesStringThe password for your account or a document
new_passwordyesStringThe new password for your account or document

Template

stream.Password(username, password, new_password, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: ConnectionSendOnce

Send a message to the document on the given channel with a dedupe key such that sending happens at most once.

Parameters

namerequiredtypedocumentation
channelyesStringEach document has multiple channels available to send messages too.
dedupenoStringA key used to dedupe request such that at-most once processing is used.
messageyesJsonNodeThe object sent to a document which will be the parameter for a channel handler.

Template

stream.SendOnce(channel, dedupe, message, {
  success: function(response) {
    // response.seq
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
seqIntegerThe sequencer for the item.

Method: ConnectionCanAttach

Ask whether the connection can have attachments attached.

Parameters

namerequiredtypedocumentation

Template

stream.CanAttach({
  success: function(response) {
    // response.yes
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
yesBooleanThe result of a boolean question.

Method: ConnectionAttach

This is an internal API used only by Adama for multi-region support.

Start an upload for the given document with the given filename and content type.

Parameters

namerequiredtypedocumentation
asset-idyesStringThe id of an asset.
filenameyesStringA filename is a nice description of the asset being uploaded.
content-typeyesStringThe MIME type like text/json or video/mp4.
sizeyesLongThe size of an attachment.
digest-md5yesStringThe MD5 of an attachment.
digest-sha384yesStringThe SHA384 of an attachment.

Template

stream.Attach(asset-id, filename, content-type, size, digest-md5, digest-sha384, {
  success: function(response) {
    // response.seq
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
seqIntegerThe sequencer for the item.

Method: ConnectionUpdate

Update the viewer state of the document.

The viewer state is accessible to bubbles to provide view restriction and filtering. For example, the viewer state is how a document can provide real-time search or pagination.

Parameters

namerequiredtypedocumentation
viewer-statenoObjectNodeA connection to a document has a side-channel for passing information about the client's view into the evaluation of bubbles. This allows for developers to implement real-time queries and pagination.

Template

stream.Update(viewer-state, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: ConnectionEnd

Disconnect from the document.

Parameters

namerequiredtypedocumentation

Template

stream.End({
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: DocumentsHashPassword

For documents that want to hold secrets, then these secrets should not be stored plaintext.

This method provides the client the ability to hash a password for plain text transmission.

Parameters

namerequiredtypedocumentation
passwordyesStringThe password for your account or a document

Template

connection.DocumentsHashPassword(password, {
  success: function(response) {
    // response.passwordHash
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
password-hashStringThe hash of a password.

Method: BillingConnectionCreate

Create a connection to the billing document of the given identity.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.

Template

connection.BillingConnectionCreate(identity, {
  next: function(payload) {
    // payload.delta
  },
  complete: function() {
  },
  failure: function(reason) {
  }
});

Streaming payload fields

nametypedocumentation
deltaObjectNodeA json delta representing a change of data. See the delta format for more information.

Method: ConfigureMakeOrGetAssetKey

Here, we ask if the connection if it has an asset key already. If not, then it will generate one and send it along. Otherwise, it will return the key bound to the connection.

This is allows anyone to have access to assets which are not exposed directly via a web handler should they see the asset within their document view. This method has no parameters.

Template

connection.ConfigureMakeOrGetAssetKey({
  success: function(response) {
    // response.assetKey
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
asset-keyStringA key used to connect the dots from the connection to assets to a browser. This is a session-based encryption scheme to protect assets from leaking outside the browser.

Method: AttachmentStart

Start an upload for the given document with the given filename and content type.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
spaceyesStringA 'space' is a collection of documents with the same schema and logic, and the 'space' parameter is used to denote the name of that collection. Spaces are lower case ASCII using the regex a-z[a-z0-9-]* to validation with a minimum length of three characters. The space name must also not contain a '--'
keyyesStringWithin a space, documents are organized within a map and the 'key' parameter will uniquely identify documents. Keys are lower case ASCII using the regex [a-z0-9._-]* for validation
filenameyesStringA filename is a nice description of the asset being uploaded.
content-typeyesStringThe MIME type like text/json or video/mp4.

Template

connection.AttachmentStart(identity, space, key, filename, content-type, {
  next: function(payload) {
    // payload.chunk_request_size
  },
  complete: function() {
  },
  failure: function(reason) {
  }
});

Streaming payload fields

nametypedocumentation
chunk_request_sizeIntegerThe attachment uploader is asking for a chunk size. Using the WebSocket leverages a flow control based uploader such that contention on the WebSocket is minimized.

Method: AttachmentStartByDomain

Start an upload for the given document with the given filename and content type.

Parameters

namerequiredtypedocumentation
identityyesStringIdentity is a token to authenticate a user.
domainyesStringA domain name.
filenameyesStringA filename is a nice description of the asset being uploaded.
content-typeyesStringThe MIME type like text/json or video/mp4.

Template

connection.AttachmentStartByDomain(identity, domain, filename, content-type, {
  next: function(payload) {
    // payload.chunk_request_size
  },
  complete: function() {
  },
  failure: function(reason) {
  }
});

Streaming payload fields

nametypedocumentation
chunk_request_sizeIntegerThe attachment uploader is asking for a chunk size. Using the WebSocket leverages a flow control based uploader such that contention on the WebSocket is minimized.

Method: AttachmentAppend

Append a chunk with an MD5 to ensure data integrity.

Parameters

namerequiredtypedocumentation
chunk-md5yesStringA md5 hash of a chunk being uploaded. This provides uploads with end-to-end data-integrity.
base64-bytesyesStringBytes encoded in base64.

Template

stream.Append(chunk-md5, base64-bytes, {
  success: function() {
  },
  failure: function(reason) {
  }
});

This method simply returns void.

Method: AttachmentFinish

Finishing uploading the attachment upload.

Parameters

namerequiredtypedocumentation

Template

stream.Finish({
  success: function(response) {
    // response.assetId
  },
  failure: function(reason) {
  }
});

Request response fields

nametypedocumentation
asset-idStringThe id of an uploaded asset.