API reference

Basics

API endpoint

Depending on the Pryv.io setup or distribution, the root endpoint can have the following formats:

Pryv Lab: https://{username}.pryv.me Own Domain: https://{username}.{domain} DNS-less (Open): https://{hostname}/{username}

Each user account has a dedicated root API endpoint as it is potentially served from a different location. The API endpoint format may vary, so check your platform’s service information if needed.

You can adapt the examples with “API” selector in the top navigation bar.

Call with HTTP

The API serves regular REST-like HTTP requests, with the usual verbs for reading and manipulating data:

  • GET (parameters: query string)
    for reading resources
  • POST (parameters: request body)
    for creating new resources and other methods modifying data
  • PUT (parameters: request body)
    for modifying resources
  • DELETE (parameters: query string)
    for removing resources; logical deletion (trashing) is supported for some resources such as events and streams

Alternative HTTP request method

For those having trouble with HTTP access control (CORS) rules, the API allows web apps to fake POST, PUT and DELETE requests through application/x-www-form-urlencoded POST requests with the following fields (all optional):

_method

The HTTP override method to use (usually PUT or DELETE; POST is used if not set).

_auth

The Authorization header value (alternative to sending the header itself).

_json

Considered as the JSON request body if set (overriding all other body content, if any).

Call with websockets

The API supports real-time interaction by accepting websocket connections via Socket.io 2.0

For API versions prior to 1.5.8, use Socket.io 0.9.

Connecting

First, load the right Socket.IO client library.

Then initialize the connection with the URL:

Pryv Lab:

https://{username}.pryv.me/{username}?auth={accessToken}

Own Domain:

https://{username}.{domain}/{username}?auth={accessToken}

DNS-less:

https://host.your-domain.io/{username}/{username}?auth={accessToken}

Yes, the username is quoted 2 times…

For API versions prior to 1.5.8, append &resource={username}.

Call methods

You call API methods by sending a corresponding Socket.IO {method-id} message, passing a parameters object and a callback:

// javascript
socket.emit('{method-id}', {/*parameters*/}, function (error, result) {
  // handle result
});

See methods ids

Specific errors

invalid-method
HTTP404

The given method id is invalid.

Subscribe to changes

Get notified when data changes by subscribing to messages. Available messages are:

  • eventsChanged
  • streamsChanged
  • accessesChanged
  • systemBoot (webhooks only)

Messages do not include the content of the changes, but they describe what type of resource has been changed (created, updated or deleted). They inform the server that it needs to fetch new or updated data through the API by doing a HTTP GET request with a valid access token. The systemBoot message is executed when the notifications system is started in order to query possibly missed data changes.

With websockets

Get notified of data changes in a web application using websockets.

With webhooks

Get notified of data changes in a web service using webhooks.

Method ids

Pryv.io API methods have ids that are available at each method’s doc. For example, the id of the Get events method is events.get. This id is useful in the following:

Service info

Service information provides a unified way for third party services to access the necessary information related to a Pryv.io platform as this route is served by any Pryv.io API endpoint.

For many applications, the first step is to authenticate a user. For this you need to know the path to access which is usually set to https://access.{domain}/ or https://{hostname}/access/. Fetching the path /service/info on any valid URL endpoint will return you a list of useful informations, such as access, containing the URL to access.

See Auto-Configuration in the guide App Guidelines.

Parameters

Result

HTTP200 OK
register
string

The URL of the register service.

access
string

The URL to perform authentication requests.

api
string

The API endpoint format.

name
string

The platform name.

home
string

The URL of the platform’s home page.

support
string

The email or URL of the support page.

terms
string

The terms and conditions, in plain text or the URL displaying them.

eventTypes
string

The URL of the list of validated event types.

version
string

The API version.

Data format

The API exchanges data with clients in JSON (MIME type application/json), except when uploading/downloading attached files.

As input, the API accepts JSON payloads of maximum 10MB.

Authorization

All requests for retrieving and manipulating activity data must carry a valid access token. The preferred method is to use the HTTP Authorization header.

Access tokens are obtained via the app authentication or from sharing.

Alternative methods:

  1. Pryv.io supports the Basic HTTP Authorization Scheme This allows to present a Pryv.io endpoint as a single URL without exposing the token in query parameters:

    curl https://{token}@{username}.pryv.me/access-info

    This method is not supported by modern browsers but by tools such as cURL, the Node.js library superagent or Postman. These tools implicitly translate the ${token}@ part of the URL to the Authorization header in basic auth format. Please use the main authorization method for tools that do not operate this translation, such as Grafana.

    Note that Pryv.io does not require a username, so only the token should be Base64 encoded. For more information see RFC671.

  2. The access token can be provided in the query string’s auth parameter, for example during the Socket.IO handshake or for a direct HTTP GET call in a browser:

    curl https://{username}.pryv.me/access-info?auth={token}

Trusted apps verification

Trusted apps only 

These API methods require that the appId parameter and Origin (or Referer) header are trusted.

Only Apps that need to use a Personal token are be registered as “Trusted Apps”.

These are usually:

  1. The web app for the Authentication and Consent process such as app-web-auth3
  2. An admin panel for the end-user to manage Access Tokens and Profile.

Trusted app api methods are tagged with T

This setting can be adapted in the Pryv.io service configuration. By default, any valid appId works and the Origin (or Referer) header must be in the form https://*.{domain}, ex.: https://login.{domain}.

Authenticate your app

To authenticate users in your app, and thus for users to grant your app access to their data, you must:

  1. Choose an app identifier (min. length 6 chars)

  2. Fetch the service information

  3. Send an auth request to the URL exposed by the access parameter of the service information

  4. Open the authUrl field of the HTTP response in a browser or webframe. The web page will prompt the user to sign in using her Pryv.io credentials (or to create an account if she doesn’t have one).

  5. The result of the sign-in process: an authenticated Pryv API endpoint or a refusal can be obtained in two ways:

    • by polling the URL obtained in the poll field of the HTTP response to the auth request (preferred method)
    • by being redirected to the returnURL provided in the auth request with the result in query parameters

Generate token app

The Access token generator is a simple web application that allows its user to enter the parameters of the Auth request and performs it. It is accessible at the following URL:

https://api.pryv.com/app-web-access/?pryvServiceInfoUrl=${pryvServiceInfoUrl}

For example:

https://api.pryv.com/app-web-access/?pryvServiceInfoUrl=https://reg.pryv.me/service/info

Auth request

idauth-requestHTTP-onlyPOST to {serviceInfo.access}

The API endpoint to use is given by the service information’s access property.

Parameters

requestingAppId
string

Your app’s identifier.

requestedPermissions
array of permission request objects

The requested permissions. Each permission request has properties:

streamId
identifier

The id of the requested stream.

level
read|contribute|manage

The required permission level.

defaultName
string

The name to create the stream if needed (in the language of the user).

languageCode
stringoptional

The two-letter ISO (639-1) code of the language in which to display user instructions, if possible. Default: en.

returnURL
stringoptional

The URL to redirect the user to after authentication completes. Required if you are not using polling to retrieve the authentication result (see Result below).

clientData
key-valueoptional

Additional client data that will be transmitted alongside the auth request (see Result below).

authUrl
stringoptional

Specify a custom url for the authentication process. The authUrl’s beginning must match with one of the trusted URLs set in the Register’s configuration.

serviceInfo
objectoptional

Overrides the default service information object that will be transmitted in the polling responses.

deviceName
stringoptional

See access data structure

expireAfter
numberoptional

See access data structure

referer
stringoptional

Used when creating a user in the process of authentication. See Create user method.

Result: need sign-in

HTTP200
status
NEED_SIGNIN

Authentication in progress.

url
string

(DEPRECATED) Please use the authUrl parameter.

The URL of the authentication page to show the user from your app as popup or webframe.

authUrl
string

The URL of the authentication page to show the user from your app as popup or webframe.

key
string

The key used to identify the auth request. It is also part of the poll URL described just below.

poll
string

The poll URL to use for retrieving the auth result via an HTTP GET request. Responses to polling requests are the same as those from the auth request.

poll_rate_ms
number

The rate at which the poll URL can be polled, in milliseconds.

requestingAppId
string

The app identifier provided during the auth request.

requestedPermissions
string

The permissions provided during the auth request.

lang
stringoptional

The language code provided during the auth request.

returnURL
stringoptional

The return URL provided during the auth request.

clientData
key-valueoptional

The client data provided during the auth request.

serviceInfo
stringoptional

The service information.

Poll request

idpoll-requestHTTP-onlyGET {needSignInResponse.poll}

The polling URL is given by the poll parameter in the result the Auth Request or a Poll request.

Result: need sign-in

HTTP200

indentical to RESULT: SIGN-IN from Auth Request

Result: accepted

HTTP200
status
ACCEPTED

Authentication successful.

username
string

(DEPRECATED) Please use the apiEndpoint parameter.

The authenticated user’s username.

token
string

(DEPRECATED) Please use the apiEndpoint parameter.

Your app’s API access token.

apiEndpoint
string

The API endpoint containing the authorization token. See app guidelines.

serviceInfo
objectoptional

The service information.

Result: refused

HTTP403
status
REFUSED

Authentication failed.

reasonID
string

A code indicating the reason for the failure.

message
string

A message indicating the reason for the failure.

serviceInfo
objectoptional

The service information.

Common metadata

General API and server information.

In HTTP headers

Every HTTP response has header:

API-Version

The version of the API in the form {major}.{minor}.{revision}. Mirrored in method results as meta.apiVersion.

Pryv-Access-Id
optional

The id of the Access used for the API call. Only present if a valid access token has been provided.

In method results

Every JSON method result has properties:

meta.apiVersion

The version of the API in the form {major}.{minor}.{revision}. Mirrored in HTTP header API-Version.

meta.serverTime

The current server time as a timestamp. Keeping track of server time is necessary to properly handle time in API calls.

meta.serial

The serial will change every time the core or register is updated. If you compare it with the serial of a previous response and notice a difference, you should reload the service information.

Errors

When an error occurs, the API returns a response with an error object (see error detailing the cause. (Over HTTP, the response status is set to 4xx or 5xx.) In this documentation, errors are identified by their id.

Usual errors

See also error data structure.

invalid-request-structure
HTTP400

The request’s structure is not that expected; for example: invalid JSON syntax, unexpected multipart structure when uploading file attachments.

invalid-parameters-format
HTTP400

The request’s parameters do not follow the expected format. The error’s data contains an array of validation errors.

unknown-referenced-resource
HTTP400

One or more referenced resource(s) can’t be found. The error’s data.{method-parameter-key} (e.g. data.streamId) contains the unknown reference(s).

invalid-access-token
HTTP401

The access token is missing or invalid.

forbidden
HTTP403

The given access token does not grant permission for this operation. See accesses for more details about accesses and permissions.

unknown-resource
HTTP404

The resource can’t be found.

removed-method
HTTP410

The resource or method has been removed from the API.

too-many-results
HTTP413

The events.get method in batch or websocket call yielded too many results. Call the API method directly, narrow the request scope or page the request.

user-account-relocated
HTTP301

The user has relocated her account to another server. Both the Location header and the error’s data contain the equivalent URL pointing to the physical server now hosting the user’s account. This error can only occur between the moment the account is relocated and the moment your DNS is updated to point to the new server. So we’re stretching the HTTP convention a little, in that the returned URL should not be used permanently (only until {username}.pryv.me points to the correct server again). It’s up to you to decide whether to keep it for the duration of the session (if you use sessions), for a given time, etc.

user-intervention-required
HTTP402

The request cannot be served temporarily because the user’s account has exceeded its limits. The user must log into her account and fix the issue.

API methods

Registration

Method for user registration. This documentation has been moved to System reference.

Authentication

Trusted apps only 

Methods for trusted apps to login/logout users.

Login user

Tidauth.loginHTTP-onlyPOST /auth/login

Authenticates the user against the provided credentials, opening a personal access session. By default, the session is valid for 14 days after the last token usage. This duration is configurable in the platform parameters. This is one of the only API methods that do not expect an auth parameter. This method requires that the appId and Origin (or Referer) header comply with the trusted app verification.

Parameters

username
string

The user’s username.

password
string

The user’s password.

appId
string

Your app’s unique identifier.

Result

HTTP200 OK
apiEndpoint
string

The API endpoint containing the authorization token. See app guidelines.

token
string

The personal access token to use for further API calls.

preferredLanguage
string

The user’s preferred language as a 2-letter ISO language code.

passwordExpires
timestamp

If password maximum age rule is enabled: The time the password will expire, according to platform setting PASSWORD_AGE_MAX_DAYS.

passwordCanBeChanged
timestamp

If password minimum age rule is enabled: The time after which the password can be changed, according to platform setting PASSWORD_AGE_MIN_DAYS. Can be in the past.

Logout user

Tidauth.logoutHTTP-onlyPOST /auth/logout

Terminates a personal access session by invalidating its access token (the user will have to login again). Simply provide the Authorization token in own of the supported ways, no request body is required.

Result

HTTP200 OK

Multi-factor authentication

Trusted apps only Entreprise license only 

Methods for handling multi-factor authentication (MFA) on top of the usual Login method.

Login with MFA

TYidmfa.loginHTTP-onlyPOST /auth/login

Proxied Login call that initiates MFA authentication, when MFA is activated for the current user.

Parameters

Similar to the usual Login parameters.

Result

HTTP302 Found
mfaToken
string

An expiring MFA session token to be used all along the MFA flow (challenge, verification).

Activate MFA

TYidmfa.activateHTTP-onlyPOST /mfa/activate

Initiates the MFA activation flow for a given Pryv.io user, triggering the MFA challenge.

Requires a personal token as authorization, which should be obtained during a prior Login call.

Parameters

The parameters depend entirely on the chosen MFA method and will be forwarded as-is to the service generating the challenge. Make sure to URL encode parameters if they appear in query parameters.

Result

HTTP302 Found
mfaToken
string

An expiring MFA session token to be used all along the MFA flow (challenge, verification).

Confirm MFA activation

TYidmfa.confirmHTTP-onlyPOST /mfa/confirm

Confirms the MFA activation by verifying the MFA challenge triggered by a prior MFA activation call.

Requires a MFA session token as authorization.

Parameters

The parameters depend entirely on the chosen MFA method and will be forwarded to the service verifying the challenge.

Result

HTTP200 OK
recoveryCodes
array of strings

An array of recovery codes that can be used for the MFA recover method.

Specific errors

forbidden
HTTP403

Invalid MFA session token.

Trigger MFA challenge

TYidmfa.challengeHTTPPOST /mfa/challenge

Triggers the MFA challenge, depending on the chosen MFA method (e.g. send a verification code by SMS).

Requires a MFA session token as authorization.

Result

HTTP200 OK
message
string

“Please verify the MFA challenge.”

Specific errors

forbidden
HTTP403

Invalid MFA session token.

Verify MFA challenge

TYidmfa.verifyHTTP-onlyPOST /mfa/verify

Verifies the MFA challenge triggered by a prior MFA challenge call.

Requires a MFA session token as authorization.

Parameters

The parameters depend entirely on the chosen MFA method and will be forwarded to the service verifying the challenge.

Result

HTTP200 OK
token
string

The personal access token to use for further API calls.

Specific errors

forbidden
HTTP403

Invalid MFA session token.

Deactivate MFA

TYidmfa.deactivateHTTP-onlyPOST /mfa/deactivate

Deactivate MFA for a given Pryv.io user.

Requires a personal token as authorization.

Result

HTTP200 OK
message
string

“MFA deactivated.”

Recover MFA

TYidmfa.recoverHTTPPOST /mfa/recover

Deactivate MFA for a given Pryv.io user using a MFA recovery code.

This is useful when Deactivate MFA can not be used (in case of 2nd factor loss). Instead, requires a MFA recovery code (obtained when confirming the MFA activation), as well as the usual Login parameters.

Parameters

Similar to the usual Login parameters, as well as:

recoveryCode
string

One MFA recovery code.

Result

HTTP200 OK
message
string

“MFA deactivated.”

Specific errors

missing-parameter
HTTP400

Missing parameter: recoveryCode.

invalid-parameter
HTTP400

Invalid recovery code.

Call batch

idcallBatchHTTPPOST /

Sends a batch of API methods calls in one go (e.g. for syncing offline changes when resuming connectivity).

Parameters

Array of method call objects, each defined as follows:

method
string

The method id.

params
object or array

The call parameters as required by the method.

Result

HTTP200 OK
results
array of call results

The results of each method call, in order.

Events

Methods to retrieve and manipulate events.

Get events

idevents.getHTTPGET /events

Queries accessible events.

Parameters

fromTime
timestampoptional

The start time of the timeframe you want to retrieve events for. Default is 24 hours before toTime if the latter is set; otherwise it is not taken into account.

toTime
timestampoptional

The end time of the timeframe you want to retrieve events for. Default is the current time if fromTime is set. We recommend to set both fromTime and toTime (for example by choosing a very small number for fromTime or a large one for toTime if you want to retrieve all events). Note: events are considered to be within a given timeframe based on their time and duration.

streams
array of stream identifiers or streams queryoptional

Array of streamIds: Events assigned to any of the specified streams or their children will be returned.

or

Streams query: Object used for filtering events by complex streamIds relations.

By default, all accessible events are returned regardless of their stream.

tags
array of stringsoptional

(DEPRECATED) Please use streams query instead.

If set, only events assigned to any of the listed tags will be returned.

types
array of stringsoptional

If set, only events of any of the listed types will be returned.

running
booleanoptional

If true, only running period events will be returned.

sortAscending
booleanoptional

If true, events will be sorted from oldest to newest. Default: false (sort descending).

skip
numberoptional

The number of items to skip in the results.

limit
numberoptional

The number of items to return in the results. A default value of 20 items is used if no other range limiting parameter is specified (fromTime, toTime).

state
default|trashed|alloptional

Indicates what items to return depending on their state. By default, only items that are not in the trash are returned; trashed returns only items in the trash, while all return all items regardless of their state.

modifiedSince
timestampoptional

If specified, only events modified since that time will be returned.

includeDeletions
booleanoptional

Whether to include event deletions since modifiedSince for sync purposes (only applies when modifiedSince is set). Defaults to false.

Result

HTTP200 OK
events
array of events

The accessible events ordered by time (see sortAscending above).

eventDeletions
array of item deletionsoptional

If requested by includeDeletions, the event deletions since modifiedSince, ordered by deletion time.

Get one event

idevents.getOneHTTPGET /events/{id}

Fetches a specific event. This request is mostly used to fetch an event’s version history, allowing to review all the modifications to an event’s data.

Parameters

includeHistory
booleanoptional

If true, the event’s history will be added to the response. Default: false (don’t include the history).

Result

HTTP200 OK
event
event

The event.

history
array of eventsoptional

If requested by includeHistory, the history of the event as an array of events, ordered by modification time.

Create event

idevents.createHTTPPOST /events

Records a new event, in addition to JSON, this request accepts standard multipart/form-data content to support the creation of event with attached files in a single request. When sending a multipart request, one content part must hold the JSON for the new event and all other content parts must be the attached files.

Parameters

The new event’s data: see Event.

Result

HTTP201 Created
event
event

The created event.

Specific errors

invalid-operation
HTTP400

The referenced stream is in the trash, and we prevent the recording of new events into trashed streams.

Update event

idevents.updateHTTPPUT /events/{id}

Modifies the event.

Parameters

id
identifierHTTPset in request path

The id of the event.

update
objectHTTPrequest body

New values for the event’s fields: see event. All fields are optional, and only modified values must be included.

Result

HTTP200 OK
event
event

The updated event.

Specific errors

Add attachment(s)

idevents.addAttachmentHTTP-onlyPOST /events/{id}

Adds one or more file attachments to the event. This request expects standard multipart/form-data content, with all content parts being the attached files.

Result

HTTP200 OK
event
event

The updated event.

Get attachment

idevents.getAttachmentHTTP-onlyGET /events/{id}/{fileId}[/{fileName}]

Gets the attached file. Accepts an arbitrary filename path suffix (ignored) for easier link readability. For this function using the auth query parameter is not accepted. You can either use the access token in the Authorization header or provide the readToken as query parameter.

Parameters

readToken
stringHTTPset in request path

Required if not using the Authorization HTTP header. The file read token to authentify the request. See event.attachments[].readToken for more info.

Result

HTTP200 OK

The file’s content, with a Digest header with SHA-256 hash of the file, encoded in base64, SHA-256=.... to check file integrity see RFC3230 and RFC5843

Delete attachment

idevents.deleteAttachmentHTTPDELETE /events/{id}/{fileId}

Irreversibly deletes the attached file.

Parameters

id
identifierHTTPset in request path

The id of the event.

fileId
identifierHTTPset in request path

The id of the attached file.

Result

HTTP200 OK
event
event

The updated event.

Delete event

idevents.deleteHTTPDELETE /events/{id}

Trashes or deletes the specified event, depending on its current state:

  • If the event is not already in the trash, it will be moved to the trash (i.e. flagged as trashed)
  • If the event is already in the trash, it will be irreversibly deleted (including all its attached files, if any).

Parameters

id
identifierHTTPset in request path

The id of the event.

Result: trashed

HTTP200 OK
event
event

The trashed event.

Result: deleted

HTTP200 OK
eventDeletion
item deletion

The event deletion record.

HF events

Entreprise license only 

Methods to manipulate high-frequency data through HF events and HF series.

Create HF event

Yidhfs.createHTTPPOST /events

Creates a new event that will be holding HF series.

Parameters

The new event’s data: see Event.

The content of HF events is read-only, so you should not provide any content. However, the event type should correspond to the type of the data points in the series, prefixed with series:. For example, to store HF series of mass/kg data points, the type of the holder event should be series:mass/kg.

Result

HTTP201 Created
event
event

The created event.

Specific errors

invalid-operation
HTTP400

The referenced stream is in the trash, and we prevent the recording of new events into trashed streams.

invalid-parameters-format
HTTP400

The event content’s format is invalid. Events of type High-frequency have a read-only content.

Get HF series data points

Yidhfs.getHTTP-onlyGET /events/{id}/series

Retrieves HF series data points from a HF event. Returns data in order of ascending deltaTime between “fromTime” and “toTime”. Data is returned as input, no sampling or aggregation is performed.

Parameters

fromDeltaTime
timestampoptional

Only returns data points later than this deltaTime. If no value is given the query will return data starting at the earliest deltaTime in the series.

toDeltaTime
timestampoptional

Only returns data points earlier than this deltaTime. If no value is given the server will return only data that is in the past.

Result

HTTP200 OK

The HF series data points.

Add HF series data points

Yidhfs.addHTTP-onlyPOST /events/{id}/series

Adds new HF series data points to a HF event.

The HF series data will only store one set of values for any given deltaTime. This means you can update existing data points by ‘adding’ new data with the original deltaTime.

Parameters

The new HF series data point(s), see HF series.

Result

HTTP200 OK
status
string

The string “ok”.

Specific errors

invalid-operation
HTTP400

The event is not a HF event.

invalid-operation
HTTP400

The referenced HF event is in the trash, and we prevent the recording of new data points into trashed events.

Add HF series batch

Yidhfs.addBatchHTTP-onlyPOST /series/batch

Adds data to multiple HF series (stored in multiple HF events) in a single atomic operation. This is the fastest way to append data to Pryv; it allows transferring many data points in a single request.

For this operation to be successful, all of the following conditions must be fulfilled:

  • The access token needs write permissions to all series identified by “eventId”.
  • All events referred to must be HF events (type starts with the string “series:”).
  • Fields identified in each individual message must match those specified by the type of the HF event; there must be no duplicates.
  • All the values in every data point must conform to the type specification.

If any part of the batch message is invalid, the entire batch is aborted and the returned result body identifies the error.

Parameters

format
string

The format string “seriesBatch”.

data
array

Array of batch entries. Each batch entry is defined as follows:

eventId
string

The id of the HF event.

data
object

HF series data to add to the HF event.

Result

HTTP201 Created
status
string

The string “ok”.

Specific errors

invalid-request-structure
HTTP400

The request was malformed and could not be executed. The entire operation was aborted.

Update HF event

Yidhfs.updateHTTPPUT /events/{id}

Similar to the standard Update event method.

You may update all non read-only fields, except content which is read-only for HF events.

Specific errors

invalid-parameters-format
HTTP400

The event content’s format is invalid. Events of type High-frequency have a read-only content.

Delete HF event

Yidhfs.deleteHTTPDELETE /events/{id}

Similar to the standard Delete event method.

Streams

Methods to retrieve and manipulate streams.

Get streams

idstreams.getHTTPGET /streams

Gets the accessible streams hierarchy.

Parameters

parentId
identifieroptional

The id of the parent stream from which to retrieve streams. Default: null (returns all accessible streams from the root level).

state
default|alloptional

By default, only items that are not in the trash are returned; all return all items regardless of their state.

includeDeletionsSince
timestampoptional

Whether to include stream deletions since that time for sync purposes.

Result

HTTP200 OK
streams
array of streams

The tree of the accessible streams, sorted by name.

streamDeletions
array of item deletionsoptional

If requested by includeDeletionsSince, the stream deletions since then, ordered by deletion time.

Create stream

idstreams.createHTTPPOST /streams

Creates a new stream.

Parameters

The new stream’s data: see stream.

Result

HTTP201 Created
stream
stream

The created stream.

Specific errors

item-already-exists
HTTP409

A similar stream already exists. The error’s data contains the conflicting properties.

invalid-item-id
HTTP400

The specified id is invalid (e.g. it’s a reserved word such as null).

Update stream

idstreams.updateHTTPPUT /streams/{id}

Modifies the stream.

Parameters

id
identifierHTTPset in request path

The id of the stream.

update
objectHTTPrequest body

New values for the stream’s fields: see stream. All fields are optional, and only modified values must be included.

Result

HTTP200 OK
stream
stream

The updated stream (without child streams).

Specific errors

item-already-exists
HTTP409

A similar stream already exists. The error’s data contains the conflicting properties.

Delete stream

idstreams.deleteHTTPDELETE /streams/{id}

Trashes or deletes the specified stream, depending on its current state:

  • If the stream is not already in the trash, it will be moved to the trash (i.e. flagged as trashed)
  • If the stream is already in the trash, it will be irreversibly deleted with its descendants (if any). If events exist that refer to the deleted item(s), you must indicate how to handle them with the parameter mergeEventsWithParent.

Parameters

id
identifierHTTPset in request path

The id of the stream.

mergeEventsWithParent
boolean

Required if actually deleting the item and if it (or any of its descendants) has linked events, ignored otherwise. If true, the linked events will be assigned to the parent of the deleted item; if false, the linked events will be deleted.

Result: trashed

HTTP200 OK
stream
stream

The trashed stream.

Result: deleted

HTTP200 OK
streamDeletion
item deletion

The stream deletion record.

Accesses

Methods to retrieve and manipulate accesses, e.g. for sharing. Any app token can manage shared accesses it created. Full access management is available to personal tokens.

Get accesses

idaccesses.getHTTPGET /accesses

Gets accesses that were created by your access token, unless you’re using a personal token then it returns all accesses. Only returns accesses that are active when making the request. To include accesses that have expired or were deleted, use the includeExpired or includeDeletions parameters respectively.

Parameters

includeExpired
booleanoptional

If true, also includes expired accesses. Defaults to false.

includeDeletions
booleanoptional

If true, also includes deleted accesses. Defaults to false.

Result

HTTP200 OK
accesses
array of accesses

All manageable accesses in the user’s account, ordered by name.

accessDeletions
array of deleted accesses

If requested by includeDeletions, the access deletions, ordered by deletion time.

Create access

idaccesses.createHTTPPOST /accesses

Creates a new access. You can only create accesses whose permissions are a subset of those granted to your own access token.

Parameters

An object with the new access’s data: see access.

Result

HTTP201 Created
access
access

The created access.

Specific errors

invalid-item-id
HTTP400

The specified token is invalid (e.g. it’s a reserved word such as null).

Delete access

idaccesses.deleteHTTPDELETE /accesses/{id}

Deletes the specified access. Personal accesses can delete any access. App accesses can delete shared accesses they created. Deleting an app access deletes the shared ones it created. All accesses can also perform a self-delete unless a forbidden selfRevoke permission has been set.

Parameters

id
identifierHTTPset in request path

The id of the access.

Result

HTTP200 OK
accessDeletion
item deletion

The deletion record.

relatedDeletions
array of item deletionsoptional

The deletion records of all the shared accesses that were generated from this app token when deleting it

Check app authorization

idaccesses.checkAppHTTPPOST /accesses/check-appTrusted apps only 

For the app authorization process. Checks if the app requesting authorization already has access with the same permissions (and on the same device, if applicable), and returns details of the requested permissions’ streams (for display) if not.

Parameters

requestingAppId
string

The id of the app requesting authorization.

deviceName
stringoptional

The name of the device running the app requesting authorization, if applicable.

requestedPermissions
array of permission request objects

An array of permission request objects, which are identical to stream permission objects of accesses except that each stream permission object must have a defaultName property specifying the name the stream should be created with later if missing.

Result

HTTP200 OK
checkedPermissions
array of permission request objects

Set if no matching access already exists. A updated copy of the requestedPermissions parameter, with the defaultName property of stream permissions replaced by name for each existing stream (set to the actual name of the item). (For missing streams the defaultName property is left untouched.) If streams already exist with the same name but a different id, defaultName is updated with a valid alternative proposal (in such cases the result also has an error property to signal the issue).

mismatchingAccess
access

Set if an access already exists for the requesting app, but with different permissions than those requested.

matchingAccess
access

Set if an access already exists for the requesting app with matching permissions. The existing access.

Access Info

idgetAccessInfoHTTPGET /access-info

Retrieves information about the access in use.

Result

HTTP200 OK

The current Access properties, as well as:

calls
key-value

A map of API methods and the number of time each of them was called using the current access.

user
key-value

A map of user account properties.

Audit

Entreprise license only 

Methods to retrieve Audit logs.

Get audit logs

Yidaudit.getHTTP-onlyGET /audit/logs

(DEPRECATED) Please use the Get events method instead.

Fetches accessible audit logs. By default, only returns logs that involve the access corresponding to the provided authorization token (self-auditing).

Parameters

accessId
identifieroptional

The id of a specific access to audit. When specified, it fetches the audit logs that involve the matching access instead of the one used to authorize this call. It has to correspond to a sub-access (expired and deleted included) in regards to the provided authorization token.

fromTime
timestampoptional

The start time of the timeframe you want to retrieve audit logs for. Timestamps are considered with a day precision.

toTime
timestampoptional

The end time of the timeframe you want to retrieve audit logs for. Timestamps are considered with a day precision.

status
numberoptional

Filters audit logs by HTTP response status, a 3-digits number. It is possible to provide only the first digit, in which case the two unspecified digits will be wildcarded. For example, status=4 will return all logs with status between 400 and 499.

ip
stringoptional

Filters audit logs by client IP address present in the forwardedFor property.

httpVerb
stringoptional

Filters audit logs by HTTP verb present in the action property.

resource
stringoptional

Filters audit logs by API resource present in the action property.

errorId
stringoptional

Filters audit logs by error id.

Result

HTTP200 OK
auditLogs
array of Audit logs

The accessible audit logs.

Specific errors

forbidden
HTTP403

Authorization token is not authorized to audit the given access.

When providing a specific access id, if the result of Get Accesses using the provided Authorization token does not contain the given access, then it is not auditable.

Webhooks

Entreprise license only 

Methods to retrieve and manipulate webhooks. These methods are only allowed for app and personal accesses.

Get webhooks

Yidwebhooks.getHTTPGET /webhooks

Gets manageable webhooks. Only returns webhooks that were created by the access, unless you are using a personal access which returns all existing webhooks in the user’s account.

Parameters

Result

HTTP200 OK
webhooks
array of webhooks

All manageable webhooks by the given access, ordered by modified date.

Get one webhook

Yidwebhooks.getOneHTTPGET /webhooks/{id}

Fetches a specific webhook. Only returns a webhook if it was created by the access, unless you are using a personal access which is allowed to fetch any existing webhook in the user’s account.

Parameters

id
identifierHTTPset in request path

The id of the webhook.

Result

HTTP200 OK
webhook
webhook

The webhook.

Create webhook

Yidwebhooks.createHTTPPOST /webhooks

Creates a new webhook. You can only create webhooks with app and shared accesses.

Parameters

An object with the new webhook’s data: see webhook.

Result

HTTP201 Created
webhook
webhook

The created webhook.

Specific errors

Update webhook

Yidwebhooks.updateHTTPPUT /webhooks/{id}

Modifies the webhook. You can only modify webhooks with the access that was used to create them, unless you are using a personal token. Updating the state to active resets the currentRetries counter.

Parameters

id
identifierHTTPset in request path

The id of the webhook.

update
objectHTTPrequest body

New values for the webhook’s fields: see webhook. All fields are optional, and only modified values must be included.

Result

HTTP200 OK
webhook
webhook

The updated webhook.

Specific errors

item-already-exists
HTTP409

There is already a webhook for this URL created by the given access.

Delete webhook

Yidwebhooks.deleteHTTPDELETE /webhooks/{id}

Deletes the specified webhook. You can only delete webhooks with the access that was used to create them, unless you are using a personal token.

Parameters

id
identifierHTTPset in request path

The id of the webhook.

Result

HTTP200 OK
webhookDeletion
item deletion

The deletion record.

Test webhook

Yidwebhooks.testHTTPPOST /webhooks/{id}/test

Sends a post request containing a message called test to the URL of the specified webhook’s url. You can only test webhooks with the access that was used to create them, unless you are using a personal token.

Parameters

id
identifierHTTPset in request path

The id of the webhook.

Result

HTTP200 OK
webhook
webhook

The webhook.

Specific errors

unknown-referenced-resource
HTTP400

The webhook’s url is either unreachable or responds with a 4xx/5xx status.

Followed slices

Trusted apps only 

Methods to retrieve and manipulate followed slices.

Get followed slices

TidfollowedSlices.getHTTPGET /followed-slices

Gets followed slices.

Result

HTTP200 OK
followedSlices
array of followed slices

All followed slices in the user’s account, ordered by name.

Create followed slice

TidfollowedSlices.createHTTPPOST /followed-slices

Creates a new followed slice.

Parameters

An object with the new followed slice’s data: see followed slice.

Result

HTTP201 Created
followedSlice
followed slice

The created followed slice.

Update followed slice

TidfollowedSlices.updateHTTPPUT /followed-slices/{id}

Modifies the specified followed slice.

Parameters

id
identifierHTTPset in request path

The id of the followed slice.

update
objectHTTPrequest body

New values for the followed slice’s fields: see followed slice. All fields are optional, and only modified values must be included.

Result

HTTP200 OK
followedSlice
followed slice

The updated followed slice.

Delete followed slice

TidfollowedSlices.deleteHTTPDELETE /followed-slices/{id}

Deletes the specified followed slice.

Parameters

id
identifierHTTPset in request path

The id of the followed slice.

Result

HTTP200 OK
followedSliceDeletion
item deletion

The deletion record.

Profile sets

Methods to read and write profile sets. Profile sets are plain key-value stores of user-level settings.

Get app profile

idprofile.getAppHTTPGET /profile/app

Gets the app’s dedicated profile set, which contains app-level settings for the user. Available to app accesses.

Result

HTTP200 OK
profile
object

The app profile set. (Empty if the app never defined any setting.)

Update app profile

idprofile.updateAppHTTPPUT /profile/app

Adds, updates or delete app profile keys. Available to app accesses.

  • To add or update a key, just set its value
  • To delete a key, set its value to null

Existing keys not included in the update are left untouched.

Parameters

update
objectHTTPrequest body

An object with the desired key changes (see above).

Result

HTTP200 OK
profile
object

The updated app profile set.

Get public profile

idprofile.getPublicHTTPGET /profile/public

Gets the public profile set, which contains the information the user makes publicly available (e.g. avatar image). Available to all accesses.

Result

HTTP200 OK
profile
object

The public profile set.

Update public profile

idprofile.updatePublicHTTPPUT /profile/public

Adds, updates or delete public profile keys. Available to personal accesses.

  • To add or update a key, just set its value
  • To delete a key, set its value to null

Existing keys not included in the update are left untouched.

Parameters

update
objectHTTPrequest body

An object with the desired key changes (see above).

Result

HTTP200 OK
profile
object

The updated public profile set.

Get private profile

idprofile.getPrivateHTTPGET /profile/private

Gets the private profile set. Available to personal accesses.

Result

HTTP200 OK
profile
object

The private profile set.

Update private profile

idprofile.updatePrivateHTTPPUT /profile/private

Adds, updates or delete private profile keys. Available to personal accesses.

  • To add or update a key, just set its value
  • To delete a key, set its value to null

Existing keys not included in the update are left untouched.

Result

HTTP200 OK
profile
object

The updated private profile set.

Account management

Trusted apps only 

Methods to manage the user’s account.

Get account information

Tidaccount.getHTTPGET /account

(DEPRECATED) Please use events methods instead.

Retrieves the user’s account information.

Result

HTTP200 OK
account
account information

The user’s account information.

Update account information

Tidaccount.updateHTTPPUT /account

(DEPRECATED) Please use events methods instead.

Modifies the user’s account information.

Parameters

update
objectHTTPrequest body

New values for the account information’s fields: see account information. All fields are optional, and only modified values must be included.

Result

HTTP200 OK
account
account information

The updated account information.

Change password

Tidaccount.changePasswordHTTPPOST /account/change-password

Modifies the user’s password. Enforces password complexity, reuse and minimum age rules if enabled (set via the corresponding platform settings).

Parameters

oldPassword
string

The current password.

newPassword
string

The new password.

Result

HTTP200 OK

Specific errors

invalid-operation
HTTP400

The given password does not match, cannot be changed at this time (if password minimum age rule enabled) or the new password was already used recently (if password reuse rule enabled).

invalid-parameters-format
HTTP400

The new password does not match password complexity rules (if enabled).

Request password reset

Tidaccount.requestPasswordResetHTTPPOST /account/request-password-reset

Requests the resetting of the user’s password. An e-mail containing an expiring reset token (e.g. in a link) will be sent to the user. This method requires that the appId and Origin (or Referer) header comply with the trusted app verification.

Parameters

appId
string

Your app’s unique identifier.

Result

HTTP200 OK

Reset password

Tidaccount.resetPasswordHTTPPOST /account/reset-password

Resets the user’s password, authorizing the request with the given reset token (see request password reset ). Enforces password complexity, reuse and minimum age rules if enabled (set via the corresponding platform settings). This method requires that the appId and Origin (or Referer) header comply with the trusted app verification.

Parameters

resetToken
string

The expiring reset token that was sent to the user after requesting the password reset.

newPassword
string

The new password.

appId
string

Your app’s unique identifier.

Result

HTTP200 OK

Specific errors

invalid-operation
HTTP400

The password cannot be changed at this time (if password minimum age rule enabled), or the new password was already used recently (if password reuse rule enabled).

invalid-parameters-format
HTTP400

The new password does not match password complexity rules (if enabled).

Data structure

Event

See also: core concepts.

id
identifieruniqueread-only (except at creation)

The identifier (collision-resistant cuid) for the event. Automatically generated if not set when creating the event.

streamIds
array of identifier

The ids of the belonging streams.

streamId
identifier

(DEPRECATED) Please use streamIds instead.

The id of the first element of the streamIds array.

time
timestamp

The event’s time. For period events, this is the time the event started. Automatically set to the server time if not provided when creating the event.

duration
timestampoptional

If present and non-zero, indicates that the event is a period event. Running period events have a duration set to null. A duration set to zero is equivalent to no duration.

type
string

The type of the event. See the event type directory for a list of standard types.

content
any typeoptional

The type-specific content of the event, if any.

tags
array of stringsoptional (always present in read items)

(DEPRECATED) Please use streamIds instead.

The tags associated with the event.

description
stringoptional

User description or comment for the event.

attachments
array of attachment objectsoptionalread-only

An array describing the files attached to the event. Each item has the following structure:

id
identifier

The file’s id. The attached file’s URL is obtained by appending this id to the event’s resource URL.

fileName
string

The file’s name as uploaded.

type
string

The MIME type of the file.

size
number

The size of the file, in bytes.

readToken
string

The auth token to pass in the query string when reading the file (instead of the regular auth parameter). The token is unique for the file and the access used to read it. This is a security measure in situations where it is impractical to use the Authorization HTTP header and/or where the file’s URL is likely to be exposed. See also events method get attachment.

integrity
integrityoptionalread-only

Integrity check for attachment object.

clientData
key-valueoptional

Additional client data for the event.

trashed
booleanoptional

true if the event is in the trash.

integrity
integrityoptionalread-only

Integrity check for event object.

created
timestampread-only

The time the event was created.

createdBy
identifierread-only

The id of the access used to create the event.

modified
timestampread-only

The time the event was last modified.

modifiedBy
identifierread-only

The id of the last access used to modify the event.

Stream

See also: core concepts.

id
identifieruniqueread-only (except at creation)

The identifier for the stream. Automatically generated if not set when creating the stream; slugified if necessary.

name
stringunique among siblings

A name identifying the stream for users. The name must be unique among the stream’s siblings in the streams tree structure.

parentId
identifieroptional

The identifier of the stream’s parent, if any. A value of null indicates that the stream has no parent (i.e. root stream).

clientData
key-valueoptional

Additional client data for the stream.

children
array of streamsread-only

The stream’s sub-streams, if any. This field cannot be set in requests creating a new streams: streams are created individually by design.

trashed
booleanoptional

true if the stream is in the trash.

created
timestampread-only

The time the stream was created.

createdBy
identifierread-only

The id of the access used to create the stream.

modified
timestampread-only

The time the stream was last modified.

modifiedBy
identifierread-only

The id of the last access used to modify the stream.

Access

See also: core concepts.

id
identifieruniqueread-only

The identifier for the access.

token
stringuniqueread-only (except at creation)

The token identifying the access. Automatically generated if not set when creating the access; slugified if necessary.

apiEndpoint
stringread-only

The API endpoint with the access’ authorization token. See app guidelines.

type
personal|app|sharedoptionalread-only (except at creation)

The type — or usage — of the access. Default: shared.

name
stringunique per type and deviceread-only (except at creation)

The name identifying the access for the user. (For personal and app access, the name is used as a technical identifier and not shown as-is to the user.)

deviceName
stringunique per type and nameoptionalread-only (except at creation)

For app accesses only. The name of the client device running the app, if applicable.

permissions
array of permission objectsread-only (except at creation)

Ignored for personal accesses. If permission levels conflict (e.g. stream set to “manage” and child stream set to “contribute”), the child stream level applies. Each permission object has the following structure:

streamId|tag
identifier | string

To be used with level property only. The id of the stream or the tag the permission applies to, or * for all streams/tags. Stream permissions are recursively applied to child streams.

level
read|contribute|manage|create-only

Used only with streamId or tag permissions. The level of access to the stream. With contribute, one can see and manipulate events for the stream/tag (and child streams for stream permissions); with manage, one can in addition create, modify and delete child streams.

The create-only level - only available for stream-based permissions - allows to read the stream and create events on it and its children.

feature
selfRevoke

To be used only with setting property. The only supported feature is selfRevoke

setting
forbidden

To be used only with feature permission. If given in the permission list, this will forbid this access to call accesses.delete {id} and perform a self revocation.

lastUsed
timestampoptionalread-only

The time the access was last used.

expireAfter
numberoptionalread-only (except at creation)

If set, controls access expiry in seconds. When given a number in this attribute (positive or zero), the access will expire (and not be usable anymore) after this many seconds.

expires
timestampoptionalread-only

If the access was set to expire: The timestamp after which the access will be deactivated.

deleted
timestampoptionalread-only

If the access has been deleted: The timestamp of the deletion.

clientData
key-valueoptionalread-only (except at creation)

Additional client data for the access.

integrity
integrityoptionalread-only

Integrity check for access object.

created
timestampread-only

The time the access was created.

createdBy
identifierread-only

The id of the access used to create the access.

modified
timestampread-only

The time the access was last modified.

modifiedBy
identifierread-only

The id of the last access used to modify the access.

Followed slice

Trusted apps only 

See also: core concepts.

id
identifieruniqueread-only

The server-assigned identifier for the followed slice.

name
stringunique

A name identifying the followed slice for the user.

url
URL

The URL of the API endpoint of the account hosting the slice. Not modifiable after creation.

accessToken
string

The token of the shared access itself. Not modifiable after creation.

Account information

Trusted apps only 

User account information.

username
stringuniqueread-only

The user’s username.

email
stringunique

The user’s contact e-mail address.

language
string

The user’s preferred language as a 2-letter ISO language code.

storageUsed
object

The current storage size used by the user account.

dbDocuments
number

Bytes used by documents (records) in the database.

attachedFiles
number

Bytes used by attached files.

Audit log

(DEPRECATED) Audit logs are available as events of type log/user-api and log/user-api-error through the Get events method.

Audit logs keep track of details about the actions performed by clients against Pryv.io accounts through the Pryv.io API. These logs can be fetched by presenting an authorization token, allowing to audit the actions that involved a given token.

id
identifierread-only

The identifier for the action that generated this log.

type
stringread-only

The type of log.

time
timestampread-only

The time the API call was executed.

forwardedFor
stringread-only

The IP address of the client who performed the audited action.

action
stringread-only

The audited action, typically an API method call, composed by the HTTP verb and the API resource.

query
stringread-only

The query string that accompanied the audited action, if any.

accessId
stringread-only

The identifier for the access used to perform the audited action.

status
numberread-only

The HTTP response status resulting from the audited action.

errorMessage
stringoptionalread-only

The error message resulting from the audited action, if any.

errorId
stringoptionalread-only

The identifier for the error resulting from the audited action, if any.

HF series

High-frequency series are collections of homogenous data points.

To store a HF series in Pryv.io, you must first create a HF event.

Series data is encoded in the “flatJSON” format:

  • Each data point in a series has a "deltaTime" field that indicates its time difference, since the holder event’s timestamp. If a "timestamp" field is instead provided, the corresponding "deltaTime" will be automatically computed from the holder event’s timestamp.
  • For types that store a single value (e.g. “mass/kg”), a single additional field named "value" is created.
  • Types that contain multiple properties (e.g. “position/wgs84”) will have many fields, whose names can be inferred from the type reference.
  • Optional fields can either be provided or not; omitted values will be set as null.
format
string

The data format (for now only “flatJSON” format is supported).

fields
Array of fields

The “fields” array lists all the fields that you will be providing in the “points” array, including the “deltaTime” field in first position. If the data type contains a single field (ex.: mass/kg), the second field is “value”, otherwise, it is the list of fields with the required ones first.

points
Array of data points

The “points” array contains the data points, each data point is represented by a simple array. This makes the bulk of the message (your data points) very space-efficient; values are encoded positionally. The first value corresponds to the first field, and so on.

Webhook

Webhooks provide push notifications to web servers using HTTP POST requests.

Once created, they will run, executing a HTTP POST request to the provided URL for each data change in the user account.

When the webhooks service is booted, it will send a webhooksServiceBoot message to all active webhooks. This allows to query the API for potentially missed notifications during its down time.

Only the app access used to create the webhook or a personal access can retrieve and modify it. This is meant to separate the responsibilities between the actor that sets the webhooks and the one(s) that consume the data following the webhook setup.

id
identifierread-only

The identifier of the Webhook.

accessId
identifierread-only

The identifier of the access that was used to create the Webhook.

url
stringunique per app accessread-only (except at creation)

The URL where the HTTP POST requests will be made. To identify the source of the webhook on your notifications server, you can use the url’s hostname, path or query parameters. For example:

{
  "url": "https://${username}.my-notifications.com/${my-secret}/?param1=value1&param2=value2"
}
minIntervalMs
numberread-only

The webhooks run rate is throttled by a minimum interval between HTTP calls in milliseconds, sending an array of changes that occured during this period. Its value is set by the platform admin.

maxRetries
numberread-only

In case of failure to send a request, the webhook will retry maxRetries times at a growing interval of time before becoming inactive after too many successive failures. Its value is set by the platform admin.

currentRetries
numberread-only

The number of retries iterations since the last failed HTTP call. This number is 0 if the last HTTP call was successful.

state
active|inactive

The current state of the Webhook. An inactive Webhook will not make any HTTP call when changes occur. It must be activated using the update webhook method.

runCount
numberread-only

The number of times the Webhook has been run, including failures.

failCount
numberread-only

The number of times the Webhook has failed HTTP calls. Failed runs are HTTP requests that received a response with a status outside of the 200-299 range or no response at all.

lastRun
Run objectread-only

Represents the last Webhook call, comprised of its HTTP response status and timestamp.

status
number

The HTTP response status of the call.

timestamp
timestamp

The time the call was started.

runs
array of Run objectsread-only

Array of Run objects in inverse chronological order (newest first) which allows to monitor a webhook’s health. Its length is set by the platform admin.

created
timestampread-only

The time the webhook was created.

createdBy
identifierread-only

The id of the access used to create the webhook.

modified
timestampread-only

The time the webhook was last modified.

modifiedBy
identifierread-only

The id of the last access used to modify the webhook.

Item deletion

A record of a deleted item for sync purposes.

id
identifier

The identifier of the deleted item.

deleted
timestampoptional

The time the item was deleted.

Key-value

An object (key-value map) for client apps to store additional data about the containing item (stream, event, etc.), such as a color, a reference to an associated icon, or other app-specific metadata.

Adding, updating and removing client data

When the containing item is updated, additional data fields can be added, updated and removed as follows:

  • To add or update a field, just set its value; for example: {"clientData": {"keyToAddOrUpdate": "value"}}
  • To delete a field, set its value to null; for example: {"clientData": {"keyToDelete": null}}

Fields you don’t specify in the update are left untouched.

Naming convention

The convention is that each app names the keys it uses with an {app-id}: prefix. For example, an app with id “riki” would store its data in fields such as "riki:key": "some value".

Error

id
string

Identifier for the error.

message
string

A human-readable description of the error.

data
any typeoptional

Additional machine-readable details (specified for each error if relevant).

subErrors
array of errorsoptional

Lists the detailed causes of the main error, if any.

streams query

The streams parameter for events.get query accepts an array of streamIds or a streams query for more complex requests.

Syntax:

The streams query must have at least one any property, with an optional not:

{ "any": ["streamA", "streamB"], "all": ["streamC"], "not": ["streamD"] }
  • any: any streamId must match
  • all: all streamIds must match
  • not: none of the streamIds must match

The returned events will be those matching all of the provided criteria.

Example:

To select all the events that are in activity or nutrition, tagged in health, but not in private:

{
  "any": ["activity", "nutrition"],
  "all": ["health"],
  "not": ["private"]
}

Format:

The JSON object representing the query must be sent stringified when passed as query parameter in a GET /events HTTP call. It can be sent as-is for batch and socket.io calls.

Item identifier

A string uniquely identifying an item for a given user. For some types of items (e.g. “structural” ones such as streams), the identifier can be optionally set by API clients; otherwise it is generated by the server. Event ids are always collision-resistant cuids.

Timestamp

A positive floating-point number representing a number of seconds since any reference date and time, independently from the time zone. Because date and time synchronization between server time and client time is done by the client simply comparing the current server timestamp with its own, the reference date and time does not actually matter (but we do use standard Unix epoch time).

Integrity

An integrity hash computed from the JSON object it is contained in. The hash is prefixed with the data structure it is computed for, as well as a representation version.