MetaPulse API v2

MetaPulse provides a simple API for you to list, read, create, update and destroy graph values

Mikel Lindsaar avatar
Written by Mikel Lindsaar
Updated over a week ago

MetaPulse has a simple API that is available for your use, any feedback is welcome. 

This document represents version 2 of the API. You can find all versions listed in our help article:

You can use the API to programatically list, read, create, update and destroy data points against your graphs.  There are rate limits and API usage limits on the MetaPulse API that you can read more about in our help article:

Setup

To begin, you will need the email you use to sign into MetaPulse along with the API key from your MetaPulse User Profile page.  

If you will be doing a lot of API calls, it is best practice to create an API user in MetaPulse and give this user profile the permissions needed to access the necessary graphs.  
​ 
While you can use your own email and API key, a dedicated API user account is recommended.

Testing Authentication

The first test you should do is make sure you can authenticate with the server. MetaPulse uses header based authentication, so you need to set two headers in your request: API-EMAIL  and API-KEY . The email is your user email, the API key is from your profile page. 

You can check authentication is working by doing the following command using the curl system utility:

curl -i \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     https://envisage.io/api/v2/authentication

Which should give you a 200 OK with an empty body looking something like:

HTTP/2 200 
date: Mon, 07 Jan 2019 02:35:35 GMT
content-type: text/html
...

This 200 OK means you have successfully connected to the server.

Using the Data Point API

Note all following date formats are YYYY-MM-DD 

You can find the graph ID (token) on the graphs page under the info button.

List All Data Points

To list all data points for a single graph, you can do:

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X GET \
     -d '{"graph_id":"<GRAPH_TOKEN>"}' \
     https://envisage.io/api/v2/data_points

So for example, if your API_EMAIL  was user@example.com  and your API_KEY  was sdlexamplekfj  and you wanted the data points for a weekly graph with the week ending on Thursday which had the graph token gra2example3 then the full command would be:

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: user@example.com" \
     -H "api-key: sdlexamplekfj" \
     -X GET \
     -d '{"graph_id":"gra2example3"}' \
     https://envisage.io/api/v2/data_points

Which would return a JSON array looking something like this:

[
  {
    "graphToken": "gra2example3",
    "majorEvent": false,
    "note": null,
    "periodEnd": "2018-11-9",
    "periodStart": "2018-11-15",
    "value": "2.0"
  },
  {
    "graphToken": "gra2example3",
    "majorEvent": false,
    "note": "We launched the product this week!",
    "periodEnd": "2018-11-16",
    "periodStart": "2018-11-22",
    "value": "4.0"
  },
  {
    "graphToken": "gra2example3",
    "majorEvent": false,
    "note": null,
    "periodEnd": "2018-11-23",
    "periodStart": "2018-11-29",
    "value": "5.0"
  },
  ...
]

Create a Data Point

To create a data point for the 28th of November, 2018 with the value of 12, you would run the following command:

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X POST \
     -d '{"graph_id":"<GRAPH_TOKEN>", \
          "period":"2018-11-28", \
          "value":"12"}' \
     https://envisage.io/api/v2/data_points

This would give the sample output:

{
  "graphToken": "<GRAPH_TOKEN>",
  "majorEvent": false,
  "note": null,
  "periodEnd": "2018-11-28",
  "periodStart": "2018-11-28",
  "value": "12.0"

Show a Data Point

To show the data point for a specific date: 

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X GET \
     -d '{"graph_id":"<GRAPH_TOKEN>"}' \
     https://envisage.io/api/v2/data_points/2018-11-28

Which would provide the response:

{
  "graphToken": "<GRAPH_TOKEN>",
  "majorEvent": false,
  "note": null,
  "periodEnd": "2018-11-28",
  "periodStart": "2018-11-28",
  "value": "12.0"

Update a Data Point

To change an existing data point for the 28th of November, 2018 to equal 15, you would run the following command: 

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X PATCH \
     -d '{"graph_id":"<GRAPH_TOKEN>", \
          "value":"15"}' \
     https://envisage.io/api/v2/data_points/2018-11-28

Which would give you in response:

{
  "graphToken": "<GRAPH_TOKEN>",
  "majorEvent": false,
  "note": null,
  "periodEnd": "2018-11-28",
  "periodStart": "2018-11-28",
  "value": "15.0"
}


Delete a Data Point

To delete the data point at the 28th of November, 2018, you would run the following command:

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X DELETE \
     -d '{"graph_id":"<GRAPH_TOKEN>"}' \
     https://envisage.io/api/v2/data_points/2018-11-28

Which should return 200 OK with an empty response:

HTTP/2 200 
date: Mon, 07 Jan 2019 03:04:49 GMT
content-type: application/json
...

Debugging

Getting APIs to work can be a real pain sometimes, especially if you don't have direct access to send requests out.

A good tool to figure out if you are sending the API request correctly is beeceptor.com which is a free service to show you what your application is actually sending to MetaPulse.

To use it, just make a new end point in BeeCeptor (call it whatever you want, we'll use envisage-test in this example), and then click the "Turn off rules" button, then send something like:

curl -i -H "api-key: API_KEY" \
        -H "api-email: bob@example.com" \
     https://test-envisage.free.beeceptor.com/authentication

After sending this you'll get something back like:

HTTP/1.1 200 OK
Date: Tue, 05 Feb 2019 12:23:29 GMT
Content-Type: text/plain
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Vary: Accept-Encoding


Hey ya! Great to see you here. Btw, nothing is configured for this request path. Create a rule and start building a mock API.

Which shows you BeeCeptor got your message.

Going to https://beeceptor.com/console/test-envisage will then show you a request, whcih you can click and then view the headers of and see something like:

Which looks good!
​ 

Questions / Comments

If you have any questions or comments, please contact us via support.

Did this answer your question?