Introduction

Welcome to the Chronicled API! This API was designed to be RESTful, so URLs relate to resources which our services expose and the HTTP verb identifies the operation being performed on a given resource. All responses are encoded in a JSON format and you can find these endpoints below. Most endpoints require the presence of an Authorization header to grant access so please ensure you obtain this information by either registering a new user within our system through the onboarding endpoints or logging in with an already registered account

Authentication

Description

The Authentication methods which the Chronicled platform provides will succesfully award clients with a JSON Web Token (JWT), which should then be included in all subsequent requests that require user authorization. There are two ways to authenticate yourself within the system.

1.) Login with your registered email/password credentials via the oauth/token endpoint

2.) Initiate the passwordless authentication flow by sending a one-time code to either your phone or your email account. If the email or phone number is new, a “guest” JWT is awarded which can then be used by the client to create a user account with password crendetials for subsequent authentication attempts

Request code

Allows a client to request a one-time login code be sent to the phone number or email they supply.

HTTP Request

Example Usage for phone number

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/passwordless/start \
--header 'Content-Type: application/json' \
--data '{
   "send": "code",
   "connection": "sms",
   "phone_number": "+14155551234"
 }'

Example Usage for email

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/passwordless/start \
--header 'Content-Type: application/json' \
--data '{
   "send": "code",
   "connection": "email",
   "email": "example@test.com"
 }'

POST /api/2.0/passwordless/start

Permission Groups: anon

Parameters

Name	Type	Description
send	String	Use “code” to send a code to the user
connection	String	Specifies the method used to send the code
phone_number optional	String	Required if the connection specified is “sms”
email optional	String	Required if the connection specified is “email”

Request ID Token

Allows a user who has registered in the system to request an ID Token for API Access

HTTP Request

Example Password Grant Usage

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/oauth/token \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{"username": "chronicled_user", "password": "barbaz"}'

Example Refresh Grant Usage

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/oauth/token \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{"grant_type": "refresh_token", "refresh_token": "abE1643WQijr26ieQtrjrteisp13xpZLEWJIOEW0712"}

POST /api/2.0/oauth/token

Permission Groups: anon

Parameters

Name	Type	Description
grant_type	String	The method used for granting a token. Can be either “password” or “refresh_token”
password optional	String	The password of the account
email optional	String	The email address of the user. Must be provided if not using a username
username optional	String	The username of the user. Mut be provided if not using an email
refresh_token optional	String	Used for “refresh_token” grant type

Success Fields

Successful Response via Password Grant

{
  "_id": "bWHjFgF",
  "username": "chronicled_user",
  "id_token": "iJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik9FTTN16UkZORVl6UXpWR01EWkVRVVJGUmtORFJUZzRNUSJ9.b2xlcyI6WJ1c2VyWQiOiJiTjM3SG44IiwidXNlcm5hbWUiOiJjaHJvbmljbGVkX3VzZXIiLCJlbWFpbCI6ImRldmxvcGVyK2Nocm9uaWNsZWQrdXNlckBjaHJvbmljbGVkLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiaXNzIjoiaHR0cHM6Ly9jaHJvbmljbGVkLXByb2QuYXV0aDAuY29tLyIsInN1YiI6ImF1dGgwfDU4ZDk0NDc1YmNjZTJlNTA3MTk0MGQzYSIsImF1ZCI6Inlqa3Y5Z1UwQVA1elB0RjB4VGlxVk0weHdMSWljWUR3IiwiZXhwIjoxNTI4NTE1NzM4LCJpYXQiOjE0OTY5NTgxMzh9.p9t_sy-oE0JnyLxFXKOJgFbVMYHhOX9wP_wTl_oiy5y-KWqdB5CSJ-0keeSNgpcOojHsGY5sYN_3d9jg7ND_sxC0FmMilzFxZThKy6dP_AcZCy-Q8wNbUTLkyrZU5Eo20FmHhkriq-3-lY5RKZ1vbBsYgb-g70SzheeIHalQgvdzCndbbzGb4NVLxPeNbqY1n6GsVervZxThhFlKOxohUODQileGIfSnYQuVhkGJALH4eaeDT4utHavkaqiqCK49yp3aHkqktOE3pyvHSkZHdYY7tmpHss86YNiAKa1IzjgggulvhWIG0F4JTHrCGXptn47h5YHozkMemKwrJ0eGFg",
  "refresh_token": "abE1643WQijr26ieQtrjrteisp13xpZLEWJIOEW0712",
  "created_at": "2017-06-08T21:42:19.013Z",
  "firebase_token": "0keeSNgpcOojHsGY5sYN_3d9jg7ND_sxC0FmMilzFxZThKy6dP_AcZCy.Q8wNbUTLkyrZU5Eo20FmHhkriq.p9t_sy-oE0JnyLxFXKOJgFbVMYHhOX9wP_wTl_oiy5y-KWqdB5CSJ-0keeSNgpcOojHsGY5sYN_3d9jg7ND_sxC0FmMilzFxZThKy6dP_AcZCy-b2xlcyI6WJ1c2VyWQiOiJiTjM3SG44IiwidXNlcm5hbWUiOiJjaHJvbmljbGVkX3VzZXIiLCJlbWFpbCI6ImRldmxvcGVyK2Nocm9uaWNsZWQrdXNlckBjaHJvbmljbGVkLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiaXNzIjoiaHR0cHM6Ly9jaHJvbmljbGVkLXByb2QuYXV0aDAuY29tLyIsInN1YiI6ImF1dGgwfDU4ZDk0NDc1YmNjZTJlNTA3MTk0MGQzYSIsImF1ZCI6Inlqa3Y5Z1UwQVA1elB0RjB4VGlxVk0weHdMSWljWUR3IiwiZXhwIjoxNTI4NTE1NzM4LCJpYXQiOjE0OTY5NTgxMzh9Q8wNbUTLkyrZU5Eo20FmHhkriq-3-lY5RKZ1vbBsYgb-iJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik9FTTN16UkZORVl6UXpWR01EWkVRVVJGUmtORFJUZzRNUSJ9",
}

Successful Response via Refresh Token Grant

{
  "_id": "bWHjFgF",
  "id_token": "iJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik9FTTN16UkZORVl6UXpWR01EWkVRVVJGUmtORFJUZzRNUSJ9.b2xlcyI6WJ1c2VyWQiOiJiTjM3SG44IiwidXNlcm5hbWUiOiJjaHJvbmljbGVkX3VzZXIiLCJlbWFpbCI6ImRldmxvcGVyK2Nocm9uaWNsZWQrdXNlckBjaHJvbmljbGVkLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiaXNzIjoiaHR0cHM6Ly9jaHJvbmljbGVkLXByb2QuYXV0aDAuY29tLyIsInN1YiI6ImF1dGgwfDU4ZDk0NDc1YmNjZTJlNTA3MTk0MGQzYSIsImF1ZCI6Inlqa3Y5Z1UwQVA1elB0RjB4VGlxVk0weHdMSWljWUR3IiwiZXhwIjoxNTI4NTE1NzM4LCJpYXQiOjE0OTY5NTgxMzh9.p9t_sy-oE0JnyLxFXKOJgFbVMYHhOX9wP_wTl_oiy5y-KWqdB5CSJ-0keeSNgpcOojHsGY5sYN_3d9jg7ND_sxC0FmMilzFxZThKy6dP_AcZCy-Q8wNbUTLkyrZU5Eo20FmHhkriq-3-lY5RKZ1vbBsYgb-g70SzheeIHalQgvdzCndbbzGb4NVLxPeNbqY1n6GsVervZxThhFlKOxohUODQileGIfSnYQuVhkGJALH4eaeDT4utHavkaqiqCK49yp3aHkqktOE3pyvHSkZHdYY7tmpHss86YNiAKa1IzjgggulvhWIG0F4JTHrCGXptn47h5YHozkMemKwrJ0eGFg",
  "created_at": "2017-06-08T21:42:19.013Z"
}

Name	Type	Description
id_token	String	The id_token that the user should use in their Authorization header to gain access to protected resources
refresh_token optional	String	The refresh_token the user can store to obtain a new ID token when their session ends
email optional	String	The email address of the user.
username optional	String	The username of the user.

Verify code

Allows a client to verify the one-time code that was sent to their cell phone or email.

HTTP Request

Example Usage

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/oauth/ro \
--header 'Content-Type: application/json' \
--data '{
   "connection": "sms",
   "phone_number": "+14155551234",
   "code": "123456"
}'

POST /api/2.0/oauth/ro

Permission Groups: anon

Parameters

Name	Type	Description
code	String	The one-time verification code sent to the user.
connection	String	The method that was used to send the code.
phone_number optional	String	The phone number to which the code was sent. Required if connection is ‘sms’
email optional	String	The email to which the code was sent. Required if connection is ‘email’

Success Fields

Name	Type	Description
phone_number optional	String	See Parameter description.
email optional	String	See Parameter description.
code	String	See Parameter description.
id_token	String	The JWT to return to the user for subsequent requests.

User

Description

The User endpoints within this section allow “guests” who have gone through the passwordless authentication flow to create their own user accounts and allow existing users to fetch their profile information within the Chronicled Platform.

Accept User Invitation

Allows a user to accept an invitation he has been sent for an Organization

HTTP Request

Example Usage

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/user/bRhqVzt/invitation/bZn39Mt \
-H 'Authorization: Bearer $JWT' \

POST /api/2.0/user/:user_id/invitation/:invitation_id

Permission Groups: user, admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
user_id	String	The user id of the invitation recipient
invitation_id	String	The id of the invitation being accepted

Success Fields

Successful Response

{
   "_id": "bXaaXcz",
   "created_at": "2017-06-23T19:27:44.507Z",
   "invitation_id": "bb0K2iy",
   "organization_id": "bbBgJDD",
   "organization": {
     "name": "Test Email Org",
     "admin_ids": [],
     "user_ids": [
       "bZn39Mt"
     ],
     "invited_members": []
   },
   "added_user": {
     "user_id": "bRhqVzt",
     "email": "testuser@chronicled.com"
   },
}

Name	Type	Description
organization	Object	An object containing information about the Organization that the user joinded
added_user	Object	An object containing information about the user that has been added to the Organization

Delete User Invitation

HTTP Request

Example Usage

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/user/bRhqVzt/invitation/bZn39Mt \
-H 'Authorization: Bearer $JWT' \

DELETE /api/2.0/user/:user_id/invitation/:invitation_id

Permission Groups: user, admin, superuser

Parameters

Name	Type	Description
user_id		The ID identifying the recipient of the invitation
invitation_id		The ID identifying the invitation to be deleted

Find User Invitations

Allows clients to view basic information about all Invitations they have within the Chronicled system.

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/user/bRhqVzt/invitation \
-H 'Authorization: Bearer $JWT' \

GET /api/2.0/user/:user_id/invitation

Permission Groups: user, admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
user_id	String	The id of the user who is the recipient of the invitations

Success Fields

Success-Response:

 HTTP/1.1 200 OK
[
  {
    "_id": "bXhgwqz",
    "updated_at": "2017-06-22T08:25:44.979Z",
    "__t": "Directory_InvitationView",
    "created_at": "2017-06-21T22:45:23.390Z",
    "__v": 0,
    "invitation_id": "bZn39Mt",
    "email": "testuser@chronicled.com",
    "user_id": "bRhqVzt",
    "organization_id": "bX3TM6P",
    "invitation": {
      "email": "testuser@chronicled.com",
      "name": "Test User",
      "organization_id": "bX3TM6P",
      "expires_at": "2017-06-25T08:25:44.914Z"
    },
    "organization": {
      "name": "Test Organization"
    },
    "user": {
      "name": "Test User",
      "email": "testuser@chronicled.com",
      "user_id": "bRhqVzt"
    }
  }
]

Name	Type	Description
-	Object[]	List of Invitations
-.invitation	Object	Information about the invitation that belongs to the user
-.organization	Object	Information about the Organization the user is being invited to
-.user	Object	Information about the user that was sent the invitation

Get User Profile

Allows clients to get the information of a specific User

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/user \
-H 'Authorization: Bearer $JWT' \

GET /api/2.0/user/:id

Permission Groups: user, admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
id optional	Number	the internal id of the user. If not provided, it will be assumed to be the id of the client making the request

Success Fields

Name	Type	Description
user_id	String
username	String
email	String	An email address for the user
picture	String	An id that maps to a picture of the user
name	String	The name of the user
first_name	String	The first name of the user
last_name	String	The last name of the user
website	String	The website of the user
seenSuggested	Boolean
bio	String	The biography of the user
phone	String	The phone number of the user
zip	String	The zip code of the use
organization_ids	String[]	An array whose values are the internal_ids of the organization it belongs to.
organizations	Object	An object whose keys are the internal ids of an organization and whose values are objects with the name of the associated organization and the role the user occupies in that organization

Change Password

Allows a client to reset their password .

HTTP Request

Example Usage

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/user/change-password \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{"password": "new_password"}'

POST /api/2.0/user/change-password

Permission Groups: user, admin, superuser

Parameters

Name	Type	Description
password	String	The new password that will be set for the user

Read User Invitation

Allows clients to view basic information about an invitation

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/user/bRhqVzt/invitation/bZn39Mt \
-H 'Authorization: Bearer $JWT' \

GET /api/2.0/user/:user_id/invitation/:invitation_id

Permission Groups: user, admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
user_id	String	The id of the user who is the recipient of the invitations
invitation_id	String	Internal id for the invitation

Success Fields

Success-Response:

HTTP/1.1 200 OK
 {
   "_id": "bXhgwqz",
   "updated_at": "2017-06-22T08:25:44.979Z",
   "__t": "Directory_InvitationView",
   "created_at": "2017-06-21T22:45:23.390Z",
   "__v": 0,
   "invitation_id": "bZn39Mt",
   "email": "testuser@chronicled.com",
   "organization_id": "bX3TM6P",
   "user_id": "bRhqVzt",
   "invitation": {
     "email": "testuser@chronicled.com",
     "name": "Test User",
     "organization_id": "bX3TM6P",
     "expires_at": "2017-06-25T08:25:44.914Z"
   },
   "organization": {
     "name": "Test Organization"
   },
   "user": {
     "name": "Test User",
     "email": "testuser@chronicled.com",
     "user_id": "bRhqVzt"
   }
 }

Name	Type	Description
invitation	Object	Information about the invitation that belongs to the user
organization	Object	Information about the Organization the user is being invited to
user	Object	Information about the user that was sent the invitation

Register user

Allows a client to register a User account within the Chronicled Platform

HTTP Request

Example Usage

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/user \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{"username": "foosername", "password": "barbaz", "email": "fooser@bar.com"}'

POST /api/2.0/user

Permission Groups: guest, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
password	String	Password for the user
email optional	String	An email address to register with the user. Not needed if it is contained in the User’s JWT
name optional	String	The name of the user to register

Success Fields

Name	Type	Description
email	String	See Parameter description.
id_token	String	The id_token of the newly registered user

Organization

Description

An organization is used to describe a specific account that has been registered to create Specs and Things across Chronicled’s differnt blockchain adapters. An organization consists of a group of users and admins who have authorization to act on the organization’s behalf. Once an organization has been created, it is used to setup a Registrant for each blockchain adapter, allowing an Organization to easily deploy things across different blockchain implementions via its associated Registrant

Assign an Admin

Allows an admin of an organization to promote another user to the role of admin with that organization

HTTP Request

Example Usage

curl --request POST \
--url http://api.chronicled.com/api/2.0/organization/aHzrTu/admin \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{
   "user_id": "ABC123",
}'

POST /api/2.0/organization/:organization_id/admin

Permission Groups: admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
organization_id	String	The organization the selected user will administer
user_id	String	The id of the user to promote to admin

Find Organizations

Allows clients to view basic information about all Organizations within the Chronicled system.

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/organization \
-H 'Authorization: Bearer $JWT' \

GET /api/2.0/organization

Permission Groups: anon, user, admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
blockchain_id optional	String	Used to find Organizations that have Registrants on a specific blockchain

Success Fields

Success-Response:

HTTP/1.1 200 OK
[
  {
    "organization_id": "a39Gh",
    "name": "Apple",
    "blockchain_addresses": [
      "0x048875e897b5877e5cdbec601a0ec3069880fe9f"
    ],
    "blockchain_ids": ["ethereum-mainnet"],
    "organization": {
      "user_ids": [],
      "admin_ids": [],
      "name": "Apple",
      "website": "apple.com",
      "registrant": {
        "organization_id": "a39Gh",
        "destination_blockchains": [{
          "blockchain_id": "ethereum-mainnet",
          "address": "0x048875e897b5877e5cdbec601a0ec3069880fe9f",
          "is_multi_access": true,
          "co_owner_addresses": [
            "0xc257274276a4e539741ca11b590b9447b26a8051"
          ]
        }]
      }
    }
  }
]

Name	Type	Description
-	Object[]	List of Organizations
-.organization_id	String	internal id of the Organization
-.name	String	name of the Organization
-.organization	Object	The field that contains more organization information

Fetch Organization Members

Allows users to view the members of organizations they belong to

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/organization/a39Gh/user \
-H 'Authorization: Bearer $JWT' \

GET /api/2.0/organization/:organization_id/user

Permission Groups: user, admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
id	String	The internal id of the Organization

Success Fields

Success-Response:

HTTP/1.1 200 OK
{
  "organization_id": "a39Gh",
  "name": "Apple",
  "organization": {
   "users": [{
     "username": "susy_sue",
     "email": "susy@example.com"
   }],
   "admins": [],
   "invited_members": [],
   "username": "apple",
   "website": "apple.com",
  }
}

Name	Type	Description
organization_id	String	internal id of the Organization
name	String	name of the Organization
organization	Object	The field that contains more organization information
organization.users	Object[]	A list of objects that display users in the organization
organization.users.username	String	The username of the user
organization.users.email	String	The email of the user
organization.admins	Object[]	A list of objects that display admins in the organization
organization.admins.username	String	The username of the admin
organization.admins.email	String	The email of the admin
organization.invited_members	Object[]	A list of objects that display invited members in the organization
organization.website	String	the website of the organization
organization.contact	String	the contact of the organization
organization.description	String	the description of the organization

Create an Organization

Allows a user who is not registered under an Organization to create one. He or She is then made an admin of that organization.

HTTP Request

Example Usage

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/organization \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{
   "name": "Organization1"
}'

POST /api/2.0/organization

Permission Groups: superuser, user

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
user_ids	String[]	The ids of the users registered within the organization
admin_ids	String[]	The ids of the admins registered within the organization
name	String	The name of the organization
description optional	String	A description about the organization
contact optional	String	The email listed as the main source of contact for the organization
legalName optional	String	The legal name of the Organization
legalAddress optional	Object	The address of the Organization representated as a JSON Object
legalAddress.street_1 optional	Object	The primary street address listed in the Organization’s address
legalAddress.street_2 optional	String	The secondary street address listed in the Organization’s address
legalAddress.city optional	String	The city listed in the Organization’s address
legalAddress.state optional	String	The state listed in the Organization’s address
legalAddress.zip optional	String	The zip listed in the Organization’s address
legalAddress.country optional	String	The country listed in the Organization’s address
registrant_initialization optional	Boolean	A flag which indicates whether or not the Organization should be provided with a default Registrant

Success Fields

Successful Response

{
  "__v":0,
  "updated_at":"2016-08-05T20:39:33.236Z",
  "__t":"OrganizationCreation",
  "_id":"avkMAvS",
  "created_at":"2016-08-05T20:39:33.234Z",
  "organization": {
    "_id": "123aHz",
    "name": "Organization1"
  }
}

Name	Type	Description
organization	Object	Field which contains the newly created organization that was submitted by the client

Update an Organization

Allows a superuser or admin of an organization to update an existing organization

HTTP Request

Example Usage

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/organization/aHzrTu \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{
   "description": "description1"
}'

POST /api/2.0/organization/:organization_id

Permission Groups: admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
organization_id	String	The id of the organization that is being updated
user_ids	String[]	The ids of the users registered within the organization
admin_ids	String[]	The ids of the admins registered within the organization
name	String	The name of the organization
description optional	String	A description about the organization
contact optional	String	The email listed as the main source of contact for the organization
legalName optional	String	The legal name of the Organization
legalAddress optional	Object	The address of the Organization representated as a JSON Object
legalAddress.street_1 optional	Object	The primary street address listed in the Organization’s address
legalAddress.street_2 optional	String	The secondary street address listed in the Organization’s address
legalAddress.city optional	String	The city listed in the Organization’s address
legalAddress.state optional	String	The state listed in the Organization’s address
legalAddress.zip optional	String	The zip listed in the Organization’s address
legalAddress.country optional	String	The country listed in the Organization’s address

Success Fields

Successful Response

{
  "__v":0,
  "updated_at":"2016-08-05T20:39:33.236Z",
  "__t":"OrganizationUpdate",
  "_id":"avkMAvS",
  "created_at":"2016-08-05T20:39:33.234Z",
  "organization": {
    "_id": "123aHz",
    "name": "Organization1",
    "user_ids": ["12aZr"]
  }
}

Name	Type	Description
organization	Object	Field which contains the newly updated organization that was submitted by the client

Read an Organization

Allows clients to view basic information about a specific organizations

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/organization/a39Gh \
-H 'Authorization: Bearer $JWT' \

GET /api/2.0/organization/:id

Permission Groups: anon, user, admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
id	String	Internal Organization id or Blockchain address that is used to identify an organization

Success Fields

Success-Response:

HTTP/1.1 200 OK
{
  "organization_id": "a39Gh",
  "name": "Apple",
  "blockchain_addresses": [
    "0x048875e897b5877e5cdbec601a0ec3069880fe9f"
  ],
  "blockchain_ids": ["ethereum-mainnet"],
  "organization": {
    "user_ids": [],
    "admin_ids": [],
    "name": "Apple",
    "website": "apple.com",
    "registrant": {
      "organization_id": "a39Gh",
      "destination_blockchains": [{
        "blockchain_id": "ethereum-mainnet",
        "address": "0x048875e897b5877e5cdbec601a0ec3069880fe9f",
        "is_multi_access": true,
        "co_owner_addresses": [
          "0xc257274276a4e539741ca11b590b9447b26a8051"
        ]
      }]
    }
  }
}

Name	Type	Description
organization_id	String	internal id of the Organization
name	String	name of the Organization
organization	Object	The field that contains more organization information

Invite a User

Allows an organization admin to invite a new member to the organization.

HTTP Request

Example Usage

curl --request POST \
--url http://api.chronicled.com/api/2.0/organization/aZhR2t/user \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{
   "name": "Suzy Sue",
   "email": "suzy@example.com",
   "organization_id": "456DEF"
}'

POST /api/2.0/organization/:organization_id/user

Permission Groups: admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
organization_id	String	The organization the user should join
name	String	The name of the user to invite
email	String	The email address of the user to invite

Remove a Member

Allows an organization admin to remove a user from the organization.

HTTP Request

Example Usage

curl --request DELETE \
--url http://api.chronicled.com/api/2.0/organization/aH2qrT/user/bhQ3T \
-H 'Authorization: Bearer $JWT' \

DELETE /api/2.0/organization/:organization_id/user/:user_id

Permission Groups: admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
organization_id	String	The organization from which to remove the user
user_id	String	The id of the user to remove from the organization

Registrant

Description

A registrant is an entity that is used to create Things within the blockchain adapters on behalf of an Organization. It contains the relevant information for interacting with the Blockchchain code and each Registrant can only be associated to one Organization.

Spec

Description

The Spec resource is used to validate data that is being registered on a specific blockchain. Before creating a Thing, a client must create a Spec for the Thing’s validation. A Spec’s json_schema field contains a JSON Schema (conforming to JSON Schema draft 4) which will then be used to verify the shape and content of the properties that are submitted when a thing is created. All Specs are local to an Organization and can be read outside of the Organization. A Spec also contains a name field which is unique within that organization.

Find Specs

Allows a user to view all the Specs they have access to

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/organization/bheq3z/spec \
-H 'Authorization: Bearer $JWT' \

GET /api/2.0/organization/:organization_id/spec

Permission Groups: user, admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Success Fields

Success-Response:

HTTP/1.1 200 OK
[
 {
   "spec_id": "a31Ahz",
   "name": "product",
   "oganization_id": "bheq3z",
   "json_schema": {
     "id": "https://discovery.chronicled.com/api/2.0/organization/bheq3Z/spec/product",
     "type": "object"
     "properties": {
       "title": {"type": "string"},
       "subtitle": {"type": "string"}
     },
   },
   "organization": {
     "name": "Chronicled Community account"
   }
 }
]

Name	Type	Description
-	Object[]	List of Specs
-.spec_id	String	The internal ID of the Spec.
-.name	String	The name of the Spec registered (must be unique within your organization)
-.organization_id	String	The ID of the organization that the Spec belongs to
-.json_schema	Object	The JSON schema that identifies the properties that Things adhering to this Spec possess
-.organization	Object	Field which contains the Organization information that the Spec belongs to
-.sync optional	Object	An object which identifies which properties in the Spec json_schema will be synchronized with a blockchain
-.sync.ethereum optional	Object	An object for identifying properties on the specs that will be synchronized with ethereum. Each key in this object identifies the property in the Spec json_schema that is registered and the type represents that type of value it will be registered as

Read a Spec

Allows a user to read a Spec they have access to

HTTP Request

Example Usage for Schema of Spec

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/organization/bheq3z/spec/product \
-H 'Authorization: Bearer $JWT' \

Example Usage for all info of Spec

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/organization/bheq3z/spec/product?all_info=true \
-H 'Authorization: Bearer $JWT' \

GET /api/2.0/organization/:organization_id/spec/:name

Permission Groups: user, admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
organization_id	String	The ID of the Organization that the Spec is registered with
name	String	The name of the spec

Success Fields

Successful response for Schema of Spec

{
  "id": "https://discovery.chronicled.com/api/2.0/organization/bheq3Z/product",
  "meta_schema" : "https://github.com/epoberezkin/ajv/blob/master/lib/refs/json-schema-v5.json",
  "type" : "object",
  "properties" : {
    "name" : { "type" : "string"},
    "description" : { "type" : "string"}
  },
  "required" : [ "name", "description" ]
}

Successful response for all info of Spec

{
  "spec_id": "a31Ahz",
  "name": "product",
  "oganization_id": "bheq3z",
  "json_schema":  {
    "id": "https://discovery.chronicled.com/api/2.0/organization/bheq3Z/spec/product",
    "meta_schema" : "https://github.com/epoberezkin/ajv/blob/master/lib/refs/json-schema-v5.json",
    "type" : "object",
    "properties" : {
      "name" : { "type" : "string"},
      "description" : { "type" : "string"}
    },
    "required" : [ "name", "description" ]
  },
  "organization": {
    "name": "Chronicled Community account"
  }
}

Name	Type	Description
spec_id	String	The internal ID of the spec
name	String	The name of the Spec registered (must be unique within your organization)
organization_id	String	The ID of the organization that the Spec belongs to
json_schema	Object	The JSON schema that identifies the properties that Things adhering to this spec possess
organization	Object	Field which contains the Organization information that the Spec belongs to
sync optional	Object	An object which identifies which properties in the Spec json_schema will be synchronized with a blockchain
sync.ethereum optional	Object	An object for identifying properties on the specs that will be synchronized with ethereum. Each key in this object identifies the property in the Spec json_schema that is registered and the type represents that type of value it will be registered as

Create Spec

Allows a user to create a Spec for an organization they have access to

HTTP Request

Example Usage for creating a Spec

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/organization/bheq3Z/spec \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{
   "label": "Product",
   "name": "product-1",
   "json_schema": {
     "type": "object",
     "properties": {
       "title": {"type": "string"},
       "subtitle": {"type": "string"}
     }
   }
}'

POST /api/2.0/organization/:organization_id/spec

Permission Groups: user,admin,superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
name	String	The name of the Spec registered (must be unique within your organization)
label	String	A label to use when displaying the Spec
organization_id	String	The internal ID of the organization that the Spec belongs to
json_schema	Object	The JSON schema that identifies the properties that Things adhering to this Spec possess

Success Fields

Successful Response for creating a Spec

{
  "__v":0,
  "updated_at":"2016-08-05T20:39:33.236Z",
  "__t":"SpecCreation",
  "_id":"avkMAvS",
  "created_at":"2016-08-05T20:39:33.234Z",
  "spec": {
    "_id": "a31Ahz",
    "name": "product",
    "organization_id": "bheq3Z",
    "json_schema": {
      "id": "https://discovery.chronicled.com/api/2.0/organization/bheq3Z/spec/product",
      "type": "object",
        "title": {"type": "string"},
        "subtitle": {"type": "string"}
      }
    }
  }
}

Name	Type	Description
spec	Object	Field which contains the newly created Spec

Thing

Description

A Thing is any object whose data has been packaged for blockchain deployment. Each Thing has a properties field, which is a set of key/value pairs that contain important data about the Thing. A Thing’s spec_organization_id and spec_name uniquely identifies the Spec which validates the data contained within properties. A Thing’s urn_identities field contains a set of unique identifiers which can be used to retrieve the Thing.

Find Things

This endpoint is used to find all Thing records that match a specific query

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/thing

GET /api/2.0/thing

Permission Groups: anon,user,admin,superuser

Success Fields

Success-Response:

HTTP/1.1 200 OK
[{
 "thing_id": "ayi21Z",
 "organization_id": "zjr13A",
 "urn_identities": ["urn:protocol:123"],
 "spec_name": "product_chronicled",
 "thing": {
   "urn_identities": ["urn:protocol:123"],
   "properties": {
     "title": "Nike Shoes 1",
     "subtitle": "Cool Shoes"
   }
 },
 "spec": {
   "name": "product_chronicled",
   "json_schema": {
     "id": "http://api.chronicled.com/api/2.0/product_chronicled",
     "type": "object",
     "properties": {
       "title": {"type": "string"},
       "subtitle": {"type": "string"}
     }
   }
 },
 "organization": {
   "name": "Chronicled Community Account
 },
 "blockchain_records": {
   "ethereum-mainnet": {
     "state": "pending",
     "state_description": "transaction: \"0xb79b7aba96e60d53fa324a5863cc14d9ee2fcdc3fb10bfe0d0195936b764e5c8\"",
     "transaction_hash": "0xb79b7aba96e60d53fa324a5863cc14d9ee2fcdc3fb10bfe0d0195936b764e5c8",
     "history": [
       {
         "state_description": "transaction: \"0xb79b7aba96e60d53fa324a5863cc14d9ee2fcdc3fb10bfe0d0195936b764e5c8\"",
         "state": "pending",
         "date": "2017-04-11T16:57:23.113Z",
         "transaction_hash": "0xb79b7aba96e60d53fa324a5863cc14d9ee2fcdc3fb10bfe0d0195936b764e5c8",
         "_id": "58ed0af30f49637f1eb120aa"
       }
     ],
     "explorer_thing_link": "http://explorer.chronicled.org/#/thing/urn:protocol:123",
     "explorer_transaction_link": "http://explorer.chronicled.org/#/transaction/0xb79b7aba96e60d53fa324a5863cc14d9ee2fcdc3fb10bfe0d0195936b764e5c8"
   }
 },
 "verified" true
}]

Name	Type	Description
-	Object[]	list of Thing objects in response
_.thing_id	String	index value used for storing thing
_.spec_name	String	The name of the Spec this Thing adheres to
_.organization_id	String	the internal id of the organization the Thing belongs to
_.urn_identities	String	array of of urns that identify the thing
_.thing	Object	field that contains more information about the the Thing
_.organization	Object	field that contains information about the Organization the Spec belongs to
_.spec	Object	field that contains information about the Spec the Thing belongs to
_.[blockchain_records]	Object	object that contains the blockchain metadata for the Thing
_.[blockchain_records.ethereum-mainnet]	Object	object that contains the blockchain metadata for the Thing
_.[blockchain_records.quorum-local]	Object	object that contains the blockchain metadata for the Thing

Get a Challenge for a Thing

Used to request a challenge for a Thing which can be identified by any of its URNs, provided the Thing uses a protocol that supports challenging.

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/thing/nfc:1.0:AFE204250/challenge \

GET /api/2.0/thing/nfc:1.0:AFE204250/challenge

Permission Groups: anon,user,admin,superuser

Parameters

Name	Type	Description
urn_identity	String	The urn that identifies the Thing to be challenged

Success Fields

Successful Response

{
  "__v":0,
  "updated_at":"2016-08-05T20:39:33.236Z",
  "__t":"ChallengeCreation",
  "_id":"avkMAvS",
  "created_at":"2016-08-05T20:39:33.234Z" ,
  "challenge": {
    "user_id": "12zaHe",
    "urn_identity": "pbk:ec:secp256r1:thingpublickey",
    "challenge": "randomchallengestring",
    "challenge_expiration": "2016-08-05T20:44:33.236Z"
  }
}

Name	Type	Description
challenge	Object	A string of random bytes for the tag to encrypt.

Read a Thing

This endpoint is used to request all the information available about a Thing by supplying one of the Thing’s identifying URN’s as the id parameter

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/thing/nfc:1.0:AFE204250

GET /api/2.0/thing/:id

Permission Groups: anon,user,admin,superuser

Parameters

Name	Type	Description
id	Number	the internal id or any urn_identity that maps to one recorded Thing

Success Fields

Success-Response:

HTTP/1.1 200 OK
{
 "thing_id": "ayi21Z",
 "organization_id": "zjr13A",
 "urn_identities": ["urn:protocol:123"],
 "spec_name": "product_chronicled",
 "thing": {
   "urn_identities": ["urn:protocol:123"],
   "properties": {
     "title": "Nike Shoes 1",
     "subtitle": "Cool Shoes"
   }
 },
 "spec": {
   "name": "product_chronicled",
   "json_schema": {
     "id": "http://api.chronicled.com/api/2.0/product_chronicled",
     "type": "object",
     "properties": {
       "title": {"type": "string"},
       "subtitle": {"type": "string"}
     }
   }
 },
 "blockchain_records": {
   "ethereum-mainnet": {
     "state": "pending",
     "state_description": "transaction: \"0xb79b7aba96e60d53fa324a5863cc14d9ee2fcdc3fb10bfe0d0195936b764e5c8\"",
     "transaction_hash": "0xb79b7aba96e60d53fa324a5863cc14d9ee2fcdc3fb10bfe0d0195936b764e5c8",
     "history": [
       {
         "state_description": "transaction: \"0xb79b7aba96e60d53fa324a5863cc14d9ee2fcdc3fb10bfe0d0195936b764e5c8\"",
         "state": "pending",
         "date": "2017-04-11T16:57:23.113Z",
         "transaction_hash": "0xb79b7aba96e60d53fa324a5863cc14d9ee2fcdc3fb10bfe0d0195936b764e5c8",
         "_id": "58ed0af30f49637f1eb120aa"
       }
     ],
     "explorer_thing_link": "http://explorer.chronicled.org/#/thing/urn:protocol:123",
     "explorer_transaction_link": "http://explorer.chronicled.org/#/transaction/0xb79b7aba96e60d53fa324a5863cc14d9ee2fcdc3fb10bfe0d0195936b764e5c8"
   }
 },
 "organization": {
   "name": "Chronicled Community Account
 },
 "verified" true
}

Name	Type	Description
thing_id	String	index value used for storing thing
spec_name	String	The name of the Spec this Thing adheres to
organization_id	String	the internal id of the organization the Thing belongs to
urn_identities	String	array of of urns that identify the thing
thing	Object	field that contains more information about the the Thing
organization	Object	field that contains information about the Organization the Spec belongs to
spec	Object	field that contains information about the Spec the Thing belongs to
blockchain_records optional	Object	object that contains the blockchain metadata for the Thing

Create Things

Allows an user with access to an Organization to create a Thing or multiple Things for that Organization.

HTTP Request

Example Usage for Single Thing

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/thing \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{
   "urn_identities": ["urn:protocol:123"],
   "spec_organization_id": "chronicled-system",
   "spec_name": "product",
   "organization_id": "zjr13A",
   "properties": {
     "product": {
       "title": "Nike Shoes 1",
       "subtitle": "Cool Shoes"
     },
     "brand": {
       "name": "Nike"
     }
   }
}'

Example Usage for Multiple Things

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/thing \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{
   "multiple": true,
   "urn_identities": [
     ["ble:1.0:abc", "pbk:ec:secp256r1:abc"],
     ["ble:1.0:def", "pbk:ec:secp256r1:def"]
     ["ble:1.0:efg", "pbk:ec:secp256r1:efg"]
   ],
   "spec_organization_id": "chronicled-system",
   "spec_name": "product_chronicled",
   "organization_id": "zjr13A",
   "properties": {
     "product": {
       "title": "Nike Shoes 1",
       "subtitle": "Cool Shoes"
     },
     "brand": {
       "name": "Nike"
     }
   },
}'

POST /api/2.0/thing

Permission Groups: user,admin,superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
multiple	Boolean	Flag that specifies whether multiple things should be created or just one
urn_identities	String[]	An Array of URNS which uniquely identify this thing. Must be unique across all Things
spec_organization_id	String	The organization_id of the Spec which this Thing adheres to
spec_name	String	The field which references the Spec that this thing is registered under
organization_id	String	The internal id of the organization that this Category belongs to
properties	Object	An object that contains the property and value pairs for the Thing

Success Fields

Successful Response for Single Thing

{
  "__v":0,
  "updated_at":"2016-08-05T20:39:33.236Z",
  "__t":"NewThingCreation",
  "_id":"avkMAvS",
  "created_at":"2016-08-05T20:39:33.234Z",
  "things": [{
    "_id": "ayi21Z",
    "urn_identities": ["urn:protocol:123"],
    "organization_id": "zjr13A",
    "spec_organization_id": "chronicled-system",
    "spec_name": "product_chronicled",
    "properties": {
      "product": {
        "title": "Nike Shoes 1",
        "subtitle": "Cool Shoes"
      },
      "brand": {
        "name": "Nike"
      }
    }
  }],
  "failed_things": []
}

Successful Response for Multiple Things

{
  "__v":0,
  "updated_at":"2016-08-05T20:39:33.236Z",
  "__t":"ThingCreation",
  "_id":"avkMAvS",
  "created_at":"2016-08-05T20:39:33.234Z",
  "things": [{
    "_id": "ByI23Z",
    "urn_identities": ["ble:1.0:abc", "pbck:ec:secp256r1:abc"],
    "spec_organization_id": "chronicled-system",
    "spec_name": "product_chronicled",
    "organization_id": "zjr13A",
    "properties": {
      "product": {
        "title": "Nike Shoes 1",
        "subtitle": "Cool Shoes"
      },
      "brand": {
        "name": "Nike"
      }
    },
  }, {
    "_id": "ZyU71b",
    "urn_identities": ["ble:1.0:def", "pbk:ec:secp256r1:def"]
    "spec_organization_id": "chronicled-system",
    "spec_name": "product_chronicled",
    "organization_id": "zjr13A",
    "properties": {
      "product": {
        "title": "Nike Shoes 1",
        "subtitle": "Cool Shoes"
      },
      "brand": {
        "name": "Nike"
      }
    },
  }],
  "failed_things": [{
    "urn_identities": ["ble:1.0:efg", "pbk:ec:secp256r1:efg"],
    "reason_for_failure": "The urns provided are in use by another existing thing"
  }]
}

Name	Type	Description
things	Object[]	Field which contains the newly created Things that were submitted by the client
failed_things	Object[]	Field which contains the the list of Things that failed to be created, with their urns and reason_for_failure provided

Verify a Thing

This endpoint is used to verifies the authenticity of a Thing

HTTP Request

Example With Challenge And Signature

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/thing/nfc:1.0:AFE204250/challenge
--header 'Content-Type: application/json' \
--data '{
   "challenge": "examplechallenge",
   "signature": "examplesignature"
}'

POST /api/2.0/thing/nfc:1.0:AFE204250/challenge

Permission Groups: anon, user, admin, superuser

Parameters

Name	Type	Description
urn_identity	String	An identifying URN for the Thing being verified
challenge	String	If the Thing being verified supports challenging, you must supply this field and the signature field
signature	String	If the Thing being verified supports challenging, you must supply this field and the challenge field

Success Fields

Successful Response

{
  "__v":0,
  "updated_at":"2016-08-05T20:39:33.236Z",
  "__t":"ThingVerification",
  "_id":"avkMAvS",
  "created_at":"2016-08-05T20:39:33.234Z",
  "verified": "true",
  "urn_identity": "nfc:1.0:AFE204250",
  "challenge": "examplechallenge",
  "signature": "examplesignature",
  "thing": {...},
  "spec": {...},
  "organization": {...},
  "blockchain_records": {...},
}

Name	Type	Description
verified	Boolean	The result of the Thing Verification Test
urn_identity	String	A urn that identifies the Thing that was verified
challenge	String	The challenge used in the verification process
signature	String	The signature used in the verification process
thing	Object	Contains more information about the Thing being verified
spec	Object	Contains information about the Spec associated with the Thing
organization	Object	Contains information about the Organization associated with the Thing
blockchain_records	Object	Contains information about the blockchain_records associated with the Thing (only Ethereum for now)

Update a Thing

Allows an user with access to an Organization to update a Thing for that Organization

HTTP Request

Example Usage

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/thing/urn:protocol:123 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{
   "properties": {
     "brand": {
       "name": "Adidas"
     }
   }
}'

POST /api/2.0/thing/:urn

Permission Groups: user,admin,superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
device_urn	String	One of the URNs which uniquely identify a Thing
properties	Object	The properties of the Object to be updated
partial_update	Boolean	Field which indicates whether or not the update performed should merge with existing properties (set to true) or completely reset the properties within the Thing (set to false)

Success Fields

Successful Response for Single Thing

{
  "__v":0,
  "updated_at":"2016-08-05T20:39:33.236Z",
  "__t":"ThingUpdate",
  "_id":"avkMAvS",
  "created_at":"2016-08-05T20:39:33.234Z",
  "partial_update": true,
  "thing": {
    "_id": "ayi21Z",
    "urn_identities": ["urn:protocol:123"],
    "organization_id": "zjr13A",
    "spec_organization_id": "chronicled-system",
    "spec_name": "product_chronicled",
    "properties": {
      "product": {
        "title": "Nike Shoes 1",
        "subtitle": "Cool Shoes"
      },
      "brand": {
        "name": "Adidas"
      }
    }
  }
}

Name	Type	Description
thing	Object	Field which contains the newly updated Thing that was submitted by the client

Ledger Transactions

Description

Transactions are used to track all operations and events that occur accross the different blockchain adaptors.

Find Transactions

Allows clients to get the information of a specific transaction

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/ledger-transaction

GET /api/2.0/ledger-transaction

Permission Groups: anon, user, admin, superuser

Success Fields

Name	Type	Description
-	Object[]	List of Transactions
-.blockchain_id	String	The id of the Blockchain the transaction is located within
-.hash	String	The hash of the transaction
-.blockHash	String	The hash of the Block the transaction is located on
-.blockNumber	Number	The number of the Block the transaction is located on
-.from	String	The address of the account which executed the transaction
-.gas	Number	The amount of gas used in the transaction
-.gasPrice	String	The price of the gas used in the transaction
-.input	String	The input data of the transaction
-.nonce	Number	The nonce used in the transaction
-.raw	String	The raw data of the transaction
-.to	String	The address the transaction was run against
-.transactionIndex	Number	The index of the transaction
-.value	String	The value of the transaction
-.gasUsed	Number	The amount of gas used in the transaction
-.logs	Object[]	Logs associated with the transaction
-.block	Object	block used in the transaction
-.chronicledMeta	Object	Object containing Chronicled-specific information
-.chronicledMeta.thingsCount	Number	The number of things in the transaction
-.chronicledMeta.date	Date	The date the transaction occured
-.chronicledMeta.registrant	String	Address of the registrant
-.urn_identities	String[]	An array of the urns of things that were involved in the transaction

Get Aggregated Transaction Information

Allows clients to view aggregated information about all Blockchain Transactions

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/ledger-transaction/summary

GET /api/2.0/ledger-transaction/summary

Permission Groups: anon, user, admin, superuser

Success Fields

Success-Response:

HTTP/1.1 200 OK
{
  "__v":0,
  "updated_at":"2016-08-05T20:39:33.236Z",
  "__t":"Blockchain_AggregatedDataView",
  "_id":"avkMAvS",
  "created_at":"2016-08-05T20:39:33.234Z" ,
  "things_registered_count": 17,
  "registrants_count": 9,
  "things_created_in_last_30_days": 5
  "transactions_in_last_30_days": [
    {
      "reportDate" : ISODate("2017-01-29T00:00:00.578Z"),
      "transactions" : 1
    }
  ]
  "transaction_count_for_last_30_days": 1,
}

Name	Type	Description
things_registered_count	String	Number of Things in the Blockchain
registrants_count	String	Number of Blockchain Registrants
things_created_in_last_30_days	String	Number of things created in the last 30 days
transactions_in_last_30_days	Object[]	List of transactions in the last 30 days
transaction_count_for_last_30_days	String	Count of the total number of transactions in the last 30 dyas

Read a Transaction

Allows clients to get the information of a specific transaction

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/ledger-transaction/0x6479701c0a5cd1b3f2da26c0e61a23d4a113e5284269d2bfc045272396a32341

GET /api/2.0/ledger-transaction/:id

Permission Groups: anon, user, admin, superuser

Parameters

Name	Type	Description
id	Number	the internal id or the transaction hash of the Transaction being fetched

Success Fields

Name	Type	Description
blockchain_id	String	The id of the Blockchain the transaction is located within
hash	String	The hash of the transaction
blockHash	String	The hash of the Block the transaction is located on
blockNumber	Number	The number of the Block the transaction is located on
from	String	The address of the account which executed the transaction
gas	Number	The amount of gas used in the transaction
gasPrice	String	The price of the gas used in the transaction
input	String	The input data of the transaction
nonce	Number	The nonce used in the transaction
raw	String	The raw data of the transaction
to	String	The address the transaction was run against
transactionIndex	Number	The index of the transaction
value	String	The value of the transaction
gasUsed	Number	The amount of gas used in the transaction
logs	Object[]	Logs associated with the transaction
block	Object	block used in the transaction
chronicledMeta	Object	Object containing Chronicled-specific information
chronicledMeta.thingsCount	Number	The number of things in the transaction
chronicledMeta.date	Date	The date the transaction occured
chronicledMeta.registrant	String	Address of the registrant
urn_identities	String[]	An array of the urns of things that were involved in the transaction

Template

Description

These are Template endpoints

Template Event Configurations

The following are the available Event Configurations that a device can register

NHS3100 Temperature Configs

Name	Type	Description
type	String	The name for the type of the event
protocol	String	The protocol used to decode the raw data
max	Number	The max possible value for a range that’s considered acceptable when monitoring the temperature
min	Number	The min possible value for a range that’s considered acceptable when monitoring the temperature
interval optional	Number	The interval for temperature recording
scale	String	The scale used for temperature recording
next_offset	Number	Number that keeps track of the next offset to use when fetching measurments
notification_alerts optional	Boolean	A boolean indicating whether or not alert notifications should be triggered

Find Templates

Allows a user who has access to an organization to find device templates from that organization

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/organization/aHzrJtu/template
-H 'Authorization: Bearer $JWT' \

GET /api/2.0/organization/:organization_id/template

Permission Groups: user, admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Success Fields

Success-Response:

HTTP/1.1 200 OK
[
  {
    "template_id"; "zvakMavS",
    "organization_id": "aHzrJtu",
    "name": "A normal temperature logger",
    "template": {
      "name": "A normal temperature logger",
      "permissions": "anon",
      "event_configurations": { 
        "temperature-event": {
          "type": "temperature-event",
          "protocol": "NHS3100",
          "interval": 1,
          "max": 53,
          "min": 23,
          "scale": "kelvin"
        }
      }
    },
    "organization": {
      "name": "A sample organization",
      "description": "A sample organization description"
    }
  }
]

Name	Type	Description
-	Object[]	List of Device Templates
-.template_id	string	the internal id of the template
-.organization_id	String	the organization_id of the template
-.name	String	the name of the template
-.template	Object	The template information
-.organization	Object	the organization information

Read a Template

Allows a user who has access to an organization to read a template from that organization

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/organization/aHzrJtu/template/zvakMavS
-H 'Authorization: Bearer $JWT' \

GET api/2.0/organization/:organization_id/template/:template_id

Permission Groups: user, admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
organization_id	String	The internal id of the organization the template is associated with
template_id	String	The internal id of the template to be read

Success Fields

Success-Response:

HTTP/1.1 200 OK
  {
    "template_id"; "zvakMavS",
    "organization_id": "aHzrJtu",
    "name": "A normal temperature logger",
    "template": {
      "name": "A normal temperature logger",
      "permissions": "anon",
      "event_configurations": { 
        "temperature-event": {
          "type": "temperature-event",
          "protocol": "NHS3100",
          "interval": 1,
          "max": 53,
          "min": 23,
          "scale": "kelvin"
        }
      }
    },
    "organization": {
      "name": "A sample organization",
      "description": "A sample organization description"
    }
  }

Name	Type	Description
template_id	string	the internal id of the template
organization_id	String	the organization_id of the template
name	String	the name of the template
template	Object	The template information
organization	Object	the organization information

Create a Template

Allows a user who has access to an organization to create a template that will be used for creating devices

HTTP Request

Example Usage

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/organization/aHzrJtu/template \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{
   "name": "A normal temperature logger",
   "permissions": "anon",
   "event_configurations": {
     "temperature-event": {
       "type": "temperature-event",
       "protocol": "NHS3100",
       "interval": 123,
       "max": 653,
       "min": 123,
       "scale": "kelvin"
     }
   }
 }

POST /api/2.0/organization/:organization_id/template

Permission Groups: admin,superuser

Parameters

Name	Type	Description
organization_id	String	the internal id of the organization the template will be registered under
name	String	The name of the template
permissions	String	Declares the access rights for devices with this template.
event_configurations	Object	The types of events that devices with this template can log and their configuration values. See Event Configurations for more info. The key in this object must be the event type and the value should be the event type’s configurations values
notification_recipients optional	String[]	A list of phone numbers to send sms notifications to when an alert is triggered
requires_linked_items optional	Boolean	A flag indicating whether or not a device configured with this template should also provide a list of linked items to the device
seconds_until_start optional	Number	The number of seconds from the time of configuration until the device starts recording events

Success Fields

Successful Response

{
  "__v": 0,
  "updated_at": "2016-08-05T20:39:33.236Z",
  "__t": "TemplateCreation",
  "_id": "avkMAvS",
  "created_at": "2016-08-05T20:39:33.234Z",
  "template": {
    "template_id": "zvakMavS",
    "organization_id": "aHzrJtu",
    "name": "A normal temperature logger",
    "permissions": "anon",
    "event_configurations": {
      "temperature-event": {
        "type": "temperature-event",
        "protocol": "NHS3100",
        "interval": 1,
        "max": 53,
        "min": 23,
        "scale": "kelvin"
      }
    }
  }
}

Name	Type	Description
template	Object	Field which contains the newly created template that was submitted by the client

Deactivate a Template

Allows an admin who has access to an organization to deactivate a Published Template in that organization

HTTP Request

Example Usage

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/organization/aHzrJtu/template/zvakMavS/deactivate \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{
   "password": "password"
   }
 }

POST /api/2.0/organization/:organization_id/template/:template_id/deactivate

Permission Groups: admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
organization_id	String	The internal id of the organization the template is registered under
template_id	String	The internal id of the template
password	String	The password of the account that is signing

Success Fields

Successful Response

{
  "__v":0,
  "updated_at":"2016-08-05T20:39:33.236Z",
  "__t":"TemplateDeactivation",
  "_id":"avkMAvS",
  "created_at":"2016-08-05T20:39:33.234Z",
  "chronicled_id": "aZhrQax",
  "template": {
    "status": "Deactivated",
    "template_id": "zvakMavS",
    "organization_id": "aHzrJtu",
    "name": "A normal temperature logger",
    "permissions": "anon",
    "event_configurations": {
      "temperature-event": {
        "type": "temperature-event",
        "protocol": "NHS3100",
        "interval": 1,
        "max": 53,
        "min": 23,
        "scale": "kelvin"
      }
    },
    "signature": {
      "signed_by": "aZhrQax",
      "signed_at":"2016-08-05T20:39:33.234Z"
    },
    "deactivation": {
      "deactivated_by": "aZhrQax",
      "deactivated_at":"2016-08-06T20:39:33.234Z"
    }
  }
}

Name	Type	Description
template	Object	Field which contains the deactivated template
chronicled_id	Object	The ID of the account that deactivated the template

Delete a Template

Allows a user who has access to an organization to delete a Template record within that organization

HTTP Request

Example Usage

curl --request DELETE \
--url http://discovery.chronicled.com/api/2.0/organization/aHzrJtu/template/zvakMavS \
-H 'Authorization: Bearer $JWT' \

DELETE /api/2.0/organization/:organization_id/template/:template_id

Permission Groups: admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
template_id	String	The id of the Template that will be updated
organization_id	String	The id of the organization for the Template

Success Fields

Successful Response

{
  "__v": 0,
  "updated_at": "2016-08-05T20:39:33.236Z",
  "__t": "TemplateDelete",
  "_id": "avkMAvS",
  "created_at": "2016-08-05T20:39:33.234Z",
  "template": {
    "template_id": "zvakMavS",
    "status": "Draft",
    "name": "Template 1",
    "organization_id": "azLwlq",
    "permissions": "users",
    "notification_recipients": [],
    "event_configurations": {
      "temperature-event": {
        "min": 20,
        "max": 30,
        "protocol": "NHS3100",
        "scale": "celsius",
        "interval": 30
      }
    },
    "requires_linked_items": true
    "created_by": "ahrJeQz"
  }
}

Name	Type	Description
template	Object	Field which contains the deleted template

Sign a Template

Allows an admin who has access to an organization to sign a template in that organization, making it “Published”

HTTP Request

Example Usage

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/organization/aHzrJtu/template/zvakMavS/sign \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{
   "password": "password"
   }
 }

POST /api/2.0/organization/:organization_id/template/:template_id/sign

Permission Groups: admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
organization_id	String	The internal id of the organization the template is registered under
template_id	String	The internal id of the template
password	String	The password of the account that is signing

Success Fields

Successful Response

{
  "__v": 0,
  "updated_at": "2016-08-05T20:39:33.236Z",
  "__t": "TemplateSigning",
  "_id": "avkMAvS",
  "created_at": "2016-08-05T20:39:33.234Z",
  "chronicled_id": "aZhrQax",
  "template": {
    "status": "Published",
    "template_id": "zvakMavS",
    "organization_id": "aHzrJtu",
    "name": "A normal temperature logger",
    "permissions": "anon",
    "event_configurations": {
      "temperature-event": {
        "type": "temperature-event",
        "protocol": "NHS3100",
        "interval": 1,
        "max": 53,
        "min": 23,
        "scale": "kelvin"
      }
    },
    "signature": {
      "signed_by": "aZhrQax",
      "signed_at": "2016-08-05T20:39:33.234Z"
    }
  }
}

Name	Type	Description
template	Object	Field which contains the newly signed template
chronicled_id	Object	The ID of the account that signed the template

Update a Template

Allows a user who has access to an organization to update a Template record within that organization

HTTP Request

Example Usage

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/organization/aHzrJtu/template/zvakMavS \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{
   "requires_linked_items": true
   }
 }

POST /api/2.0/organization/:organization_id/template/:template_id

Permission Groups: admin, superuser

Parameters

Name	Type	Description
template_id	String	The id of the Template that will be updated
organization_id	String	The id of the organization for the Template
name optional	String	The name of the template
permissions optional	String	Declares the access rights for devices with this template.
event_configurations optional	Object	The types of events that devices with this template can log and their configuration values. See Event Configurations for more info. The key in this object must be the event type and the value should be the event type’s configurations values
notification_recipients optional	String[]	A list of phone numbers to send sms notifications to when an alert is triggered
requires_linked_items optional	Boolean	A flag indicating whether or not a device configured with this template should also provide a list of linked items to the device
seconds_until_start optional	Number	The number of seconds from the time of configuration until the device starts recording events

Success Fields

Successful Response

{
  "__v": 0,
  "updated_at": "2016-08-05T20:39:33.236Z",
  "__t": "TemplateDelete",
  "_id": "avkMAvS",
  "created_at": "2016-08-05T20:39:33.234Z",
  "template": {
    "template_id": "zvakMavS",
    "status": "Draft",
    "name": "Template 1",
    "organization_id": "azlWlq",
    "permissions": "users",
    "notification_recipients": [],
    "event_configurations": {
      "temperature-event": {
        "min": 20,
        "max": 30,
        "protocol": "NHS3100",
        "scale": "celsius",
        "interval": 30
      }
    },
    "requires_linked_items": true
    "created_by": "ahrJeQz"
  }
}

Name	Type	Description
template	Object	Field which contains the deleted template

Device

Description

These are Device endpoints

Configure a Device

Allows a user who has access to an organization to configure a Device for that organization

HTTP Request

Example Usage

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/device/pbk:ec:secp256r1:abcdefghi/configure \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{
   "template_id": "zvakMavS",
   "organization_id": "aHzrJtu",
   "linked_items": [ "thing:urn:123" ]
}'

POST /api/2.0/device/:device_urn/configure

Permission Groups: user, admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
template_id	String	The id of the template used to create the device.
organization_id optional	String	The id of the organization the device is registered under. Does not have to be specified if the device has already been configured under an organization
linked_items optional	String[]	URNs of items the device is linked to

Success Fields

Successful Response

{
  "_id": "avkMAvS",
  "created_by": "aTgQdRz",
  "device": {
    "__v": 0,
    "updated_at": "2016-08-05T20:39:33.236Z",
    "__t": "EventLogger_Device",
    "created_at": "2016-08-05T20:39:33.234Z",
    "urn_identities": [
      "pbk:ec:secp256r1:abcdefghi"
    ],
    "created_by": "aTgQdRz",
    "notification_recipients": [],
    "device_id": "bTgTdDr",
    "template_id": "zvakMavS",
    "organization_id": "aHzrJtu",
    "name": "A normal temperature logger",
    "permissions": "anon",
    "event_configurations": {
      "temperature-event": {
        "type": "temperature-event",
        "protocol": "NHS3100",
        "interval": 1,
        "max": 53,
        "min": 23,
        "scale": "kelvin",
        "notification_alerts": true
      }
    },
    "organization_id": "123",
    "linked_items": [
      "thing:urn:123"
    ]
  }
}

Name	Type	Description
device	Object	Field which contains the newly created device that was submitted by the client

Download Data for Devices

Allows a user to request an email to download a csv of data relating to a device

HTTP Request

Status check

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/analytics/download\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{
   "device_urns": ["nhs3xxx:1.0:2f1430880ce28a4c0000000000000000"],
}'

POST /api/2.0/analytics/download

Permission Groups: anon, user, admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
device_urns	String[]	The urn identities of the devices whose data are requested for download

Success Fields

Successful Response

{
  "_id": "avkMAvS",
  "created_by": "aTgQdRz",
  "device_urns": ["nhs3xxx:1.0:2f1430880ce28a4c0000000000000000"],
  "email": "testuser@chronicled.com",
  "created_at": "2016-08-05T20:39:33.234Z"
}

Name	Type	Description
device_urns	String[[	The urn identities of the devices whose data are requested for download
email optional	String	The recipient address for the data. Defaults to email of user Session if not provided

Sign a Device challenge

Request the signature of a challenge for a given Device.

HTTP Request

Example With Challenge And Signature

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/device/nfc:1.0:AFE204250/signature
--header 'Content-Type: application/json' \
--data '{
   "challenge": "examplechallenge"
}'

POST /api/2.0/device/nfc:1.0:AFE204250/signature

Permission Groups: anon, user, admin, superuser

Parameters

Name	Type	Description
urn_identity	String	The urn that identifies the Device to be challenged
challenge	String	The challenge to be signed

Success Fields

Successful Response

{
  "_id": "avkMAvS",
  "user_id": "12zaHe",
  "urn_identity": "pbk:ec:secp256r1:thingpublickey",
  "challenge": "randomchallengestring",
  "signature": "000102030405060708090a0b0c0d0e0f",
  "created_at": "2016-08-05T20:39:33.234Z"
}

Name	Type	Description
signature	String	The encryption of the supplied challenge using the Device’s server key.

Verify a Device

This endpoint is used to verifies the authenticity of a Device

HTTP Request

Example With Challenge And Signature

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/device/nfc:1.0:AFE204250/challenge
--header 'Content-Type: application/json' \
--data '{
   "challenge": "examplechallenge",
   "signature": "examplesignature"
}'

POST /api/2.0/device/nfc:1.0:AFE204250/challenge

Permission Groups: anon, user, admin, superuser

Parameters

Name	Type	Description
urn_identity	String	An identifying URN for the Device being verified
challenge	String	If the Device being verified supports challenging, you must supply this field and the signature field
signature	String	If the Device being verified supports challenging, you must supply this field and the challenge field

Success Fields

Successful Response

{
  "__v": 0,
  "updated_at": "2016-08-05T20:39:33.236Z",
  "__t": "DeviceVerification",
  "_id": "avkMAvS",
  "created_at": "2016-08-05T20:39:33.234Z",
  "verified": "true",
  "urn_identity": "nfc:1.0:AFE204250",
  "challenge": "examplechallenge",
  "signature": "examplesignature"
}

Name	Type	Description
verified	Boolean	The result of the Device Verification Test
urn_identity	String	A urn that identifies the Device that was verified
challenge	String	The challenge used in the verification process
signature	String	The signature used in the verification process

Event Logs

The following are the available Event Logs that a device can store

Temperature Event Logs

Name	Type	Description
type	String	The type of the event
status	String	The status of the event log
scale	String	The scale used for temperature reading
numberOfRecordings	Number	The total number of temperature recordings
recordings	Object[]	Tuples values in the format of (Date, Temperature Recording)
numberOfChecks	Number	The number of preservation checks that have been stored
preservationChecks	Object[]	Tuples values in the format of (Date, ‘intact’
startDate optional	Date-time	The timestamp that marks the start of the recordings for temperature event
endDate optional	Date-time	The timestamp that marks the end of the recordings for temperature event
upperLimit optional	Number	The upper limit for a range that’s considered acceptable when monitoring
lowerLimit optional	Number	The lower limit for a range that’s considered acceptable when monitoring
minimum optional	Number	The minimum temperature reading in the ‘recordings’ field
maximum optional	Number	The maximum temperature reading in the ‘recordings’ field
average optional	Number	The average temperature reading in the ‘recordings’ field

Find Device Analytics

Gathers temperature recordings for viewing in the Dashboard.

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/organization/abc123/analytics/device
-H 'Authorization: Bearer $JWT' \

GET /api/2.0/organization/:organization_id/analytics/device

Permission Groups: user

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Success Fields

Get analytics

HTTP/1.1 200 OK
[
 {
   "organization_id": "bUcARLa",
   "device_urn": "nhs3xxx:1.0:sampleurn1",
   "event_logs": {
     "temperature_event": {
       "numberOfRecordings": 5,
       "lowerLimit": 0,
       "upperLimit": 20,
       "interval": 300,
       "minimum": 1.1,
       "maximum": 18.6,
       "intact": true
     }
   },
   "linked_items": [
     "urn:protocol:samplethingurn"
   ]
 }
]

Name	Type	Description
-	[analytics]	List of analytics records

Get Devices within an organization

Allows a user who has access to an organization to find devices from that organization

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/organization/abc123/device \

GET /api/2.0/organization/:organization_id/device

Permission Groups: user, admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Success Fields

Success-Response:

HTTP/1.1 200 OK
[
  {
    "urn_identities": [
      "pbk:ec:secp256r1:abcdefghi"
    ],
    "organization_id": "aHzrJtu",
    "device": {
      "urn_identities": [ "pbk:ec:secp256r1" ],
      "name": "A normal temperature logger",
      "permissions": "member_user",
      "firmware": "Chronicled v1.0",
      "event_configurations": {
        "temperature-event": {
          "type": "temperature-event",
          "protocol": "NHS3100",
          "interval": 1,
          "max": 53,
          "min": 23,
          "scale": "kelvin"
        }
      }
    },
    "organization": {
      "name": "A sample organization",
      "description": "A sample organization description"
    }
    "event_logs": {
      "temperature-event": {
         "status": "Inactive",
         "numberOfReadings": 0,
         "upperLimit": 12,
         "values": [],
         "scale": "kelvin"
      }
    }
  }
]

Name	Type	Description
-	Object[]	List of Events
-.urn_identities	String[]	The urn_identities of the device
-.organization_id	String	the organization_id of the device
-.device	Object	The device information
-.organization	Object	the organization information
-.latest_event	Object	Object containing information about the last event logged on the device
-.latest_event.created_on	Date	The date of the latest created event
-.latest_event.type	String	The type of the latest created event
-.event_logs	Object	The event log information for the current device. The keys correspond to the type of event being logged and the value corresponds to an event log for that type. See Event Logs

Get a Challenge for a device

Used to request a challenge for a Thing which can be identified by any of its URNs, provided the Thing uses a protocol that supports challenging.

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/device/nfc:1.0:AFE204250/challenge \

GET /api/2.0/device/nfc:1.0:AFE204250/challenge

Permission Groups: anon, user, admin, superuser

Parameters

Name	Type	Description
urn_identity	String	The urn that identifies the Thing to be challenged

Success Fields

Successful Response

{
  "__v":0,
  "updated_at":"2016-08-05T20:39:33.236Z",
  "__t":"ChallengeCreation",
  "_id":"avkMAvS",
  "created_at":"2016-08-05T20:39:33.234Z" ,
  "challenge": {
    "user_id": "12zaHe",
    "urn_identity": "pbk:ec:secp256r1:thingpublickey",
    "challenge": "randomchallengestring",
    "challenge_expiration": "2016-08-05T20:44:33.236Z"
  }
}

Name	Type	Description
challenge	Object	A string of random bytes for the tag to encrypt.

Get a Session ID for a device

Request the creation of a session id for a given Device.

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/device/nfc:1.0:AFE204250/session-id \

GET /api/2.0/device/nfc:1.0:AFE204250/session-id

Permission Groups: anon, user, admin, superuser

Parameters

Name	Type	Description
urn_identity	String	The urn that identifies the Device to be challenged

Success Fields

Successful Response

{
  "_id": "avkMAvS",
  "user_id": "12zaHe",
  "device_urn": "nhs3xxx:1.0:0291008808e28a4c0000000000000000",
  "session_id": "f6b8ad81181f5cd4be43123ca5f7fba2bc75bfef7f45d8fea54659e6a5e4862b",
  "created_at": "2016-08-05T20:39:33.234Z"
}

Name	Type	Description
session_id	String	The string value which is used to identify the session

Read Device Analytics

Temperature analytics (one device) for viewing in the Dashboard.

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/organization/abc123/analytics/device/foorn
-H 'Authorization: Bearer $JWT' \

GET /api/2.0/organization/:organization_id/analytics

Permission Groups: user

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Success Fields

Read analytics for device

HTTP/1.1 200 OK
{
  "organization_id": "bUcARLa",
  "device_urn": "nhs3xxx:1.0:sampleurn1",
  "event_logs": {
    "temperature_event": {
      "numberOfRecordings": 5,
      "lowerLimit": 0,
      "upperLimit": 20,
      "interval": 300,
      "minimum": 1.1,
      "maximum": 18.6,
      "intact": true
    }
  },
  "linked_items": [
   "urn:protocol:samplethingurn"
  ]
}

Name	Type	Description
-	analytics	The analytics for a particular device.

Read Devices

Allows a user who has access to an organization to read a device from that organization

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/device/pbk:ec:secp256r1:abchedghi
-H 'Authorization: Bearer $JWT' \

GET /api/2.0/device/:device_urn

Permission Groups: anon, user, admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
device_urn	String	The urn of the device to be read

Success Fields

Configured Device:

HTTP/1.1 200 OK
  {
    "urn_identities": [
      "example:003"
      "sn:1.0:UBPVGREDARG2SOEB"
    ],
    "serial_number": "UBPVGREDARG2SOEB",
    "organization_id": "aHzrJtu",
    "device": {
      "serial_number": "UBPVGREDARG2SOEB",
      "urn_identities": [
        "example:003"
        "sn:1.0:UBPVGREDARG2SOEB"
      ],
      "name": "A normal temperature logger",
      "permissions": "member_user",
      "firmware": "Chronicled v1.0",
      "notification_recipients": [],
      "event_configurations": {
        "temperature-event": {
          "type": "temperature-event",
          "protocol": "NHS3100",
          "interval": 60,
          "max": 5,
          "min": 0,
          "scale": "celsius",
          "notification_alerts": true
        }
      }
    },
    "organization": {
      "name": "A sample organization",
      "description": "A sample organization description"
    },
    "event_logs": {
      "temperature-event": {
         "type": "temperature-event",
         "status": "Inactive",
         "scale": "celsius",
         "numberOfRecordings": 0,
         "numberOfChecks": 0,
         "recordings": [],
         "preservationChecks": [],
         "upperLimit": 5,
         "lowerLimit": 0,
         "interval": 60
      }
    }
  }

Configured Device with recordings:

HTTP/1.1 200 OK
  {
    "urn_identities": [
      "example:003"
      "sn:1.0:UBPVGREDARG2SOEB"
    ],
    "organization_id": "aHzrJtu",
    "serial_number": "UBPVGREDARG2SOEB",
    "device": {
      "serial_number": "UBPVGREDARG2SOEB",
      "urn_identities": [
        "example:003"
        "sn:1.0:UBPVGREDARG2SOEB"
      ],
      "name": "A normal temperature logger",
      "permissions": "member_user",
      "firmware": "Chronicled v1.0",
      "notification_recipients": [],
      "event_configurations": {
        "temperature-event": {
          "type": "temperature-event",
          "protocol": "NHS3100",
          "interval": 60,
          "max": 5,
          "min": 0,
          "scale": "celsius",
          "notification_alerts": true
        }
      }
    },
    "organization": {
      "name": "A sample organization",
      "description": "A sample organization description"
    },
    "event_logs": {
      "temperature-event": {
         "type": "temperature-event",
         "status": "Active",
         "scale": "celsius",
         "numberOfRecordings": 2,
         "numberOfChecks": 0,
         "recordings": [
           [
             "2017-03-28T21:40:49.003Z",
             3.1
           ],
           [
             "2017-03-28T21:40:49.004Z",
             4.1
           ]
         ],
         "preservationChecks": [],
         "upperLimit": 5,
         "lowerLimit": 0,
         "interval": 60,
         "startDate": "2017-03-28T21:40:49.003Z",
         "minimum": 3.1,
         "maximum": 4.1,
         "average": 3.5999999999999996
      }
    }
  }

Name	Type	Description
urn_identities	String[]	The urn_identities of the device
organization_id	String	the organization_id of the device
device	Object	The device information
organization	Object	the organization information
latest_event	Object	Object containing information about the last event logged on the device
latest_event.created_on	Date	The date of the latest created event
latest_event.type	String	The type of the latest created event
event_logs	Object	The event log information for the current device. The keys correspond to the type of event being logged and the value corresponds to an event log for that type. See Event Logs

Item

Description

These are Item endpoints

Find Item Analytics

Gathers information about items linked to active devices

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/organization/abc123/analytics/item
-H 'Authorization: Bearer $JWT' \

GET /api/2.0/organization/:organization_id/analytics/item

Permission Groups: user

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Success Fields

Get Items

    HTTP/1.1 200 OK

[
  {
    "_id": "bf95SKM",
    "objectID": "bf95SKM",
    "urn_identities": [
      "ble:1.0:f110af5bf50b"
    ],
    "organization_id": "bTwJw0Q",
    "spec_name": "chronicled_thing_spec_1.0",
    "spec_organization_id": "chronicled-system",
    "device_id": "bik0mJu",
    "thing": {
      "urn_identities": [
        "ble:1.0:f110af5bf50b"
      ],
      "properties": {
        "description": "Pokemon",
        "name": "Mewtwo"
      },
      "spec_name": "chronicled_thing_spec_1.0",
      "spec_organization_id": "chronicled-system"
    },
    "spec": {
      "json_schema": {
        "meta_schema": "https://github.com/epoberezkin/ajv/blob/master/lib/refs/json-schema-v5.json",
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "description"
        ],
       "id": "http://localhost:1337/api/2.0/organization/chronicled-system/spec/chronicled_thing_spec_1.0"
      }
    },
    "device": {
      "name": "testing new template",
      "organization_id": "bTwJw0Q",
      "permissions": "anon",
      "event_configurations": {
        "temperature-event": {
          "type": "temperature-event",
          "protocol": "NHS3100",
          "interval": 1,
          "max": 20,
          "min": 10,
          "scale": "celsius",
          "notification_alerts": false
        }
      },
      "notification_recipients": [],
      "urn_identities": [
        "fake:example:4"
      ],
      "linked_items": [
        "ble:1.0:f110af5bf50b"
      ]
    },
    "event_logs": {
      "temperature-event": {
        "interval": 1,
        "lowerLimit": 10,
        "upperLimit": 20,
        "preservationChecks": [],
        "recordings": [],
        "numberOfChecks": 0,
        "numberOfRecordings": 0,
        "intact": true,
        "scale": "celsius",
        "status": "Inactive",
        "type": "temperature-event"
      }
    },
  }
]

Name	Type	Description
-	[analytics]	List of item analytics records

Read Item Analytics

Information for one Item linked to a device

HTTP Request

Example Usage

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/organization/abc123/analytics/item/urn:example:1
-H 'Authorization: Bearer $JWT' \

GET /api/2.0/organization/:organization_id/analytics/item/:item_urn

Permission Groups: user

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Success Fields

Read analytics for item

HTTP/1.1 200 OK
{
  "_id": "bf95SKM",
  "objectID": "bf95SKM",
  "urn_identities": [
    "ble:1.0:f110af5bf50b"
  ],
  "organization_id": "bTwJw0Q",
  "spec_name": "chronicled_thing_spec_1.0",
  "spec_organization_id": "chronicled-system",
  "device_id": "bik0mJu",
  "thing": {
    "urn_identities": [
      "ble:1.0:f110af5bf50b"
    ],
    "properties": {
      "description": "Pokemon",
      "name": "Mewtwo"
    },
    "spec_name": "chronicled_thing_spec_1.0",
    "spec_organization_id": "chronicled-system"
  },
  "spec": {
    "json_schema": {
      "meta_schema": "https://github.com/epoberezkin/ajv/blob/master/lib/refs/json-schema-v5.json",
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "description": {
          "type": "string"
        }
      },
      "required": [
        "name",
        "description"
      ],
     "id": "http://localhost:1337/api/2.0/organization/chronicled-system/spec/chronicled_thing_spec_1.0"
    }
  },
  "device": {
    "name": "testing new template",
    "organization_id": "bTwJw0Q",
    "permissions": "anon",
    "event_configurations": {
      "temperature-event": {
        "type": "temperature-event",
        "protocol": "NHS3100",
        "interval": 1,
        "max": 20,
        "min": 10,
        "scale": "celsius",
        "notification_alerts": false
      }
    },
    "notification_recipients": [],
    "urn_identities": [
      "fake:example:4"
    ],
    "linked_items": [
      "ble:1.0:f110af5bf50b"
    ]
  },
  "event_logs": {
    "temperature-event": {
      "interval": 1,
      "lowerLimit": 10,
      "upperLimit": 20,
      "preservationChecks": [],
      "recordings": [],
      "numberOfChecks": 0,
      "numberOfRecordings": 0,
      "intact": true,
      "scale": "celsius",
      "status": "Inactive",
      "type": "temperature-event"
    }
  },
}

Name	Type	Description
-	analytics	The analytics for a particular item.

Events

Description

These are Event endpoints

Create an Event

Allows a user who has access to an organization to create an event record for a device in that organization

HTTP Request

Temperature recordings

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/organization/aHzrJtu/device/nhs3xxx:1.0:2f1430880ce28a4c0000000000000000/event \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{
   "type": "temperature-event",
   "raw_data": "[[1490737249009/-3.1],[1490737249010/15.1]]",
   "metadata": { "offset": 40 }
}'

Status check

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/organization/aHzrJtu/device/nhs3xxx:1.0:2f1430880ce28a4c0000000000000000/event \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{
   "type": "temperature-event",
   "raw_data": "preservation:broken"
}'

POST /api/2.0/device/:device_urn/event

Permission Groups: user,admin,superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
device_urn	String[]	One of the urn identities of the device
type	String	The type of the event being created. See Event Configurations for possible types that can be registered to a device
raw_data	String	The Raw data for the event

Success Fields

Successful Response

{
  "__v": 0,
  "updated_at": "2016-08-05T20:39:33.236Z",
  "__t": "EventCreation",
  "_id": "avkMAvS",
  "created_at": "2016-08-05T20:39:33.234Z",
  "event": {
    "created_at": "2016-08-05T20:39:33.234Z",
    "device_urn": "pbk:ec:secp256r1:abcdefghi"],
    "type": "temperature-event",
    "started_at": "1483401600",
    "raw_data": "0xl2jr48ufdshdskjlasdfew890ewrhjfdhlvsasdhasdf",
    "data": {
      "action": "record",
      "values": [[1483401600, 51], [1483488000, 49]],
      "units": "kelvin"
    }
  },
  "device": {...},
  "event_logs": {...},
}

Name	Type	Description
event	Object	Field which contains the newly created event that was submitted by the client
device	Object	Field which contains information about the device the event affects
event_logs	Object	Field which contains the current state of the event_logs for the device, before adding the new event

Find Device Events

Allows a user who has access to a device to read events from that device

HTTP Request

Get Temperature Events, sorted by creation time

curl --request GET \
--url http://discovery.chronicled.com/api/2.0/device/example:device:01/event?type=temperature-event&_sort=-created_at \
-H 'Authorization: Bearer $JWT'

GET /api/2.0/device/:device_urn/event

Permission Groups: user, admin, superuser

Headers

Name	Type	Description
Authorization	String	The authorization token for the request. Should be in the format of “Bearer $JWT”

Parameters

Name	Type	Description
type optional	String	The type of the events the client is looking for that are registered under a device
action optional	String	The action described for the event type (i.e. ‘record’ for temperature-events)
_sort optional	String	Field to sort the results by. Using a ‘+’ or ‘-’ prefix will arrange by increasing fields or decreasing fields respectively (i.e. sort=-created_at)
_perPage optional	Number	Limits the number of results that are seen per page

Success Fields

Get Temperature Events

   HTTP/1.1 200 OK
[
  {
    "_id": "bovtymL",
    "updated_at": "2017-10-16T21:54:03.610Z",
    "__t": "EventLogger_EventView",
    "event_id": "bpfqrVq",
    "device_urn": "example:device:01",
    "type": "temperature-event",
    "action": "record",
    "__v": 0,
    "event": {
      "device_urn": "test:offset:1",
      "type": "temperature-event",
      "raw_data": "[[1508186955040/-3.1],[1508186955043/15.1]]",
      "data": {
        "recordings": [
          [
            "2017-10-16T20:49:15.040Z",
            -3.1
          ],
          [
            "2017-10-16T20:49:15.043Z",
            15.1
          ]
        ],
        "scale": "celsius",
        "action": "record"
      },
      "metadata": {
        "next_offset": 12,
        "sequence_length": 2,
        "offset": 10
      },
      "created_by": "123"
    },
    "created_at": "2017-10-16T21:54:03.604Z"
  }
]

Name	Type	Description
-	Object[]	List of Events
-.device_urn	String	The urn of the device
-.type	String	the type of the event
-.raw_data	String	The raw data from the event
-.data	Object	The interpretated information about the event based on the event_type and raw_data
-.metadata	Object	Additional information about the data supplied

Errors

HTTP Status Codes

Chronicled uses the follwoing convential HTTP response codes for errors. In general, codes in the 4xx range indicate there was an error with the request sent from the client and codes in the 5xx range indicate there was an error with Chronicled’s Servers

Error Code	Meaning
400	Bad Request – A request query or body parameter was missing or is not properly formatted
401	Unauthorized – The Authuorization header provided did not give you access to the resource
404	Not Found – The specified route or instance could not be found
405	Method Not Allowed – You tried to access a resource with an invalid method
409	Conflict – Request conflicts with the state of the server (most likely a uniqueness constraint was broken)
500	Internal Server Error – We had a problem with our server. Try again later.