API Reference

Introduction

The Grapiture API is based on REST. All endpoints that accept data expect the format to be encoded in JSON and return JSON encoded responses. Standard HTTP status codes, authentication and methods are used.

  
  BASE URL: https://grapiture.com/api/v1
  

Whether you are using the free or pro tier usage credits are refreshed at UTC day start.

Authentication

If using the pro tier, set the HTTP Authorization header with your JWT encoded API key obtained from the dashboard on every request.

  
  Authorization: Bearer <API - Key>
  

Chart endpoint

  
  POST /chart
  

The chart endpoint provides the functionality to post a chart message to the provided Slack webhook. Chart messages are based on Chart.js charts of which we currently support: "line", "bar", "pie" & "doughnut" types and an additional Grapiture "panel" type (discussed below).

Request body

  
  {
   "webhook": "<Slack Webhook>",
   "message": "<Optional message to include with the chart>",
   "chart": {
       "type": "< line or bar or pie or doughnut or panel>",
       "dataset": [],
       "options": {}
   }
  }
  

Example response

HTTP status code 202
  
 No response body.
  

We currently support the following Chart.js charts: "line", "bar", "pie" & "doughnut". You can follow the Chart.js documentation here and when setting the chart property in JSON set it to the JSON encoded Chart.js object.


We also support the datalabels plugin see documentation here.

  
  {
    ...
   "chart": {
       "type": ...,
       "dataset": ...,
       "options": {
           "plugins": {
               "datalabels": {
                   "color": "blue"
               }
           }
       }
   }
  }
  

The panel type allows for the representation of a value that doesn't need a chart. A single panel type message can represent from 1 to 4 values with titles. The data property takes from 1 to 4 objects containing a required value and optional label and style properties.

The following styles are currently available: Light Dark Success Warning Danger

  
{
    "webhook": ...,
    "chart": {
        "type": "panel",
        "data": [{
        	"value":"200",
        	"label":"Active Users",
        	"style": "success" 	
        }]
    }
}
  

Single value panel example:

Two value panel example:

Three value panel example:

Four value panel example:


Limit endpoint

  
  GET /limit
  

The limit endpoint returns the number of API credits that have been used and the upper limit. Calling this API endpoint does not use additional API credits. Under the free plan set the body with your Slack webhook (same as chart endpoint), under the pro tier simply set the authorization header with your API key.

Example response

HTTP status code 200
  
  {
   "used": 1,
   "limit": 5
  }
  

Errors

In the event of an error the API will return in the following format. For HTTP status codes of 500 and above we advise not relying on the error body, it may or may not be present. The status field of the response will match the HTTP status code returned.

Error responses

HTTP status codes Reasons you may get this response
400 (Bad request) Request body syntax is not in the correct format (Note webhooks have to match Slack webhook format).

Sending to Slack failed, may need to check webhook is valid.

401 (Unauthorized) API key invalid.
403 (Forbidden) Plan limit reached.
Limit information not found.
429 (Too many requests) The API is rate limited and hitting the API too quickly will cause this error. No response body will be present.
500+ (Internal server errors) Something failed our end.
  
  {
   "status": 400,
   "details": "Short string detailing the error"
  }