Navbar
Chronicled logo
shell

Introduction

Welcome to the Chronicled API! This API was designed to be RESTful, so URLs relate to resouces 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 loging 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”

Login as a user

Allows a user who has registered in the systemto login with their password and obtain their ID Token

HTTP Request

Example 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"}'

POST /api/2.0/oauth/token

Permission Groups: anon

Parameters

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

Success Fields

Successful Response

{
  "_id": "bWHjFgF",
  "username": "chronicled_user",
  "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

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

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 to use for the new organization.

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/1.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/1.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/1.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/spec \
-H 'Authorization: Bearer $JWT' \

GET /api/2.0/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/1.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/spec/a31Ahz \
-H 'Authorization: Bearer $JWT' \

Example Usage for all info of Spec

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

GET /api/2.0/spec/:spec_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
spec_id String

The internal id of the Spec

Success Fields

Successful response for Schema of Spec

{
  "id": "https://discovery.chronicled.com/api/1.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/1.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

Read a Spec by its Organization

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/1.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/1.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/spec \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{
   "label": "Product",
   "name": "product-1",
   "organization_id": "bheq3Z",
   "json_schema": {
     "type": "object",
     "properties": {
       "title": {"type": "string"},
       "subtitle": {"type": "string"}
     }
   }
}'

POST /api/2.0/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/1.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": {
     "product": {
       "title": "Nike Shoes 1",
       "subtitle": "Cool Shoes"
     }
   }
 },
 "spec": {
   "name": "product_chronicled"
   "json_schema": {
     "id": "http://api.chronicled.com/api/1.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": {
     "product": {
       "title": "Nike Shoes 1",
       "subtitle": "Cool Shoes"
     }
   }
 },
 "spec": {
   "name": "product_chronicled"
   "json_schema": {
     "id": "http://api.chronicled.com/api/1.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

Event Configurations

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

Temperature Event Configs

Name Type Description
type String

The name for the type of the event

protocol String

The protocol used to decode the raw data

interval optional Number

The interval for temperature recording

max optional Number

The max possible value for a range that’s considered acceptable when monitoring the temperature

min optional Number

The min possible value for a range that’s considered acceptable when monitoring the temperature

scale String

The scale used for temperature recording

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: 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 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 String[]

A list of phone numbers to send sms notifications to when an alert is triggered

requires_linked_items Boolean

A flag indicating whether or not a device configured with this template should also provide a list of linked items to the device

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

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

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’

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

Get 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
-H 'Authorization: Bearer $JWT' \

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

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”

Success Fields

Get analytics

HTTP/1.1 200 OK
[
  {
    "organization_id": "bUcARLa"
    "thing": {
     "properties": {
       "lot_id": "bZ5ewcu"
     },
    "spec_name": "ice-cream",
    "spec_organization_id": "bUcARLa",
    "urn_identities": ["sn:1.0:def123"]
    },
    "event_logs": {
     "temperature_event": {
       "numberOfRecordings": 5,
       "lowerLimit": 0,
       "upperLimit": 20,
       "interval": 300,
       "minimum": 1.1,
       "maximum": 18.6,
       "intact": true,
       "urn_identities": ["nhs3xxx:1.0:96d801880ce28a4c0000000000000007"]
      }
    }
  }
]
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",
      "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 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": [
      "pbk:ec:secp256r1:abcdefghi"
    ],
    "organization_id": "aHzrJtu",
    "device": {
      "urn_identities": [ "pbk:ec:secp256r1" ],
      "name": "A normal temperature logger",
      "permissions": "member_user",
      "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": [
      "pbk:ec:secp256r1:abcdefghi"
    ],
    "organization_id": "aHzrJtu",
    "device": {
      "urn_identities": [ "pbk:ec:secp256r1" ],
      "name": "A normal temperature logger",
      "permissions": "member_user",
      "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

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

Example Usage

curl --request POST \
--url http://discovery.chronicled.com/api/2.0/organization/aHzrJtu/device/pbk:ec:secp256r1:abcdefghi/event \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $JWT' \
--data '{
   "type": "temperature-event",
   "raw_data": "0xl2jr48ufdshdskjlasdfew890ewrhjfdhlvsasdhasdf",
}'

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

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.