apiary.apib

FORMAT: 1A
HOST: http://blynk-cloud.com/

# Blynk HTTP RESTful API

Blynk HTTP RESTful API allows to easily read and write values to/from Pins in Blynk apps and Hardware (microcontrollers and microcomputers like Arduino, Raspberry Pi, ESP8266, Particle, etc.).

Every ```PUT``` request will update Pin's state both in apps and on the hardware.
Every ```GET``` request will return current state/value on the given Pin.
We also provide simplified API so you can do updates via GET requests.

## Get pin value [/{auth_token}/get/{pin}]

+ Parameters
    + auth_token (required, string, `4ae3851817194e2596cf1b7103603ef8`) ... authentification token.
    + pin (required, string, `D8`) ... pin you want to read.

### Get pin value [GET]

+ Response 200 (application/json)

        [
        ]

+ Response 200 (application/json)

        [
            "1"
        ]

+ Response 200 (application/json)

        [
            "1",
            "2"
        ]
        
+ Response 400 (plain/text)

        Invalid token.

+ Response 400 (plain/text)

        Wrong pin format.
        
+ Response 400 (plain/text)

        Requested pin not exists in app.


## Write pin value via GET [/{auth_token}/update/{pin}?value={value}]

+ Parameters
    + auth_token (required, string, `4ae3851817194e2596cf1b7103603ef8`) ... authentification token.
    + pin (required, string, `D8`) ... pin you want to write.
    + value (required, string, `1`) ... pin value you want to write.

### Write pin value via GET [GET]

+ Response 200

+ Response 400 (plain/text)

        Invalid token.

+ Response 400 (plain/text)

        Wrong pin format.

+ Response 400 (plain/text)

        Requested pin doesn't exist in the app.

+ Response 500 (plain/text)

        Unexpected content type. Expecting application/json.

## Write pin value via PUT [/{auth_token}/update/{pin}]

+ Parameters
    + auth_token (required, string, `4ae3851817194e2596cf1b7103603ef8`) ... authentification token.
    + pin (required, string, `D8`) ... pin you want to write.

### Write pin value via PUT [PUT]

+ Request (application/json)

        [
            "1"
        ]
        
+ Request (application/json)

        [
            "1",
            "2"
        ]

+ Response 200

+ Response 400 (plain/text)

        Invalid token.

+ Response 400 (plain/text)

        Wrong pin format.
        
+ Response 400 (plain/text)

        Requested pin not exists in app.
        
+ Response 500 (plain/text)

        Unexpected content type. Expecting application/json.

## Set Widget Property via GET [/{auth_token}/update/{pin}?{property}={value}]

+ Parameters
    + auth_token (required, string, `4ae3851817194e2596cf1b7103603ef8`) ... authentification token.
    + pin (required, string, `V0`) ... pin you want to write.
    + property (required, string, `label`) ... property you want to change `label`, `color`, etc. For reserved characters
    like space and '#' for color property you need to use appropriate encoding. For example `#23C48E` should be passed as
    `%2323C48E` where %23 is encoded '#' character.
    + value (required, string, `MyNewLabel`) ... property value.

### Set Widget Property via GET [GET]

+ Response 200

+ Response 400 (plain/text)

        Invalid token.

+ Response 400 (plain/text)

        Wrong pin format.

+ Response 400 (plain/text)

        Requested pin not exists in app.

+ Response 500 (plain/text)

        Unexpected content type. Expecting application/json.
        

## Hardware network status [/{auth_token}/isHardwareConnected]

+ Parameters
    + auth_token (required, string, `4ae3851817194e2596cf1b7103603ef8`) ... authentification token.

### Checks that hardware with provided token is online and connected to server [GET]

+ Response 200 (application/json)

        true
        
+ Response 200 (application/json)

        false
        
+ Response 400 (plain/text)

        Invalid token.

## Application network status [/{auth_token}/isAppConnected]

### Check that application is connected to server and has active project with provided token [GET]

+ Response 200 (application/json)

        true
        
+ Response 200 (application/json)

        false
        
+ Response 400 (plain/text)

        Invalid token.

## Send push notification [/{auth_token}/notify]

+ Parameters
    + auth_token (required, string, `4ae3851817194e2596cf1b7103603ef8`) ... authentification token.

### Notify [POST]

+ Request (application/json)

        {
            "body" : "message no less than 255 chars."
        }
        
+ Response 200

+ Response 400 (plain/text)

        Invalid token.

+ Response 400

        Body is empty or larger than 255 chars.
        
+ Response 400

        Project is not active.
        
+ Response 400

        No notification widget or widget not initialized.
        
+ Response 500 (plain/text)

        Unexpected content type. Expecting application/json.
        
## Send email [/{auth_token}/email]

+ Parameters
    + auth_token (required, string, `4ae3851817194e2596cf1b7103603ef8`) ... authentification token.

### Email [POST]

+ Request (application/json)

        {
            "to" : "email",
            "title" : "title",
            "subj" : "subj"
        }
        
+ Response 200

+ Response 400 (plain/text)

        Invalid token.
        
+ Response 400

        Email body is wrong. Missing or empty fields 'to', 'subj'.

+ Response 400

        Project is not active.

+ Response 400

        No email widget.
        
+ Response 500 (plain/text)

        Unexpected content type. Expecting application/json.
        
        
### Pin history data [/{auth_token}/data/{pin}]

+ Parameters
    + auth_token (required, string, `4ae3851817194e2596cf1b7103603ef8`) ... authentification token.
    + pin (required, string, `D8`) ... pin you want to read.

## Get all history data for specific pin [GET]

+ Response 200 (application/x-gzip)

### QR for project cloning [/{auth_token}/qr]

+ Parameters
    + auth_token (required, string, `4ae3851817194e2596cf1b7103603ef8`) ... authentification token.

## QR for project cloning [GET]

+ Response 200 (image/png)

## Get project [/{auth_token}/project]

Returns project connected with provided token.

+ Parameters
    + auth_token (required, string, `4ae3851817194e2596cf1b7103603ef8`) ... authentification token.

### Get project [GET]

+ Response 200 (application/json)

        {
           "id":125564119,
           "name":"New Project",
           "createdAt":0,
           "updatedAt":0,
           "widgets":[
              {
                 "type":"TWO_AXIS_JOYSTICK",
                 "id":1036300912,
                 "x":0,
                 "y":4,
                 "color":-308477697,
                 "width":5,
                 "height":4,
                 "pins":[
                    {
                       "pin":15,
                       "pwmMode":false,
                       "rangeMappingOn":false,
                       "pinType":"ANALOG",
                       "value":"1",
                       "min":0,
                       "max":255
                    },
                    {
                       "pin":15,
                       "pwmMode":false,
                       "rangeMappingOn":false,
                       "pinType":"ANALOG",
                       "value":"2",
                       "min":0,
                       "max":255
                    }
                 ],
                 "split":true,
                 "autoReturnOn":true,
                 "portraitLocked":false
              },
              {
                 "type":"BUTTON",
                 "id":1036300899,
                 "x":5,
                 "y":0,
                 "color":616861439,
                 "width":2,
                 "height":2,
                 "pinType":"DIGITAL",
                 "pin":8,
                 "pwmMode":false,
                 "rangeMappingOn":false,
                 "min":0,
                 "max":0,
                 "value":"0",
                 "pushMode":true
              },
              {
                 "type":"LED",
                 "id":1036300908,
                 "x":4,
                 "y":0,
                 "color":1602017535,
                 "width":1,
                 "height":1,
                 "label":"gggg",
                 "pin":-1,
                 "pwmMode":false,
                 "rangeMappingOn":false,
                 "min":0,
                 "max":0,
                 "frequency":0
              },
              {
                 "type":"LED",
                 "id":1036300904,
                 "x":7,
                 "y":0,
                 "color":1602017535,
                 "width":1,
                 "height":1,
                 "pinType":"VIRTUAL",
                 "pin":2,
                 "pwmMode":false,
                 "rangeMappingOn":false,
                 "min":0,
                 "max":0,
                 "frequency":0
              },
              {
                 "type":"TIMER",
                 "id":276297114,
                 "x":0,
                 "y":1,
                 "color":-308477697,
                 "width":3,
                 "height":1,
                 "pinType":"DIGITAL",
                 "pin":0,
                 "pwmMode":false,
                 "rangeMappingOn":false,
                 "min":0,
                 "max":0,
                 "startTime":75600,
                 "startValue":"dw\u00000\u00001",
                 "stopTime":75599,
                 "stopValue":"dw\u00000\u00000"
              },
              {
                 "type":"LED",
                 "id":1036300903,
                 "x":4,
                 "y":1,
                 "color":1602017535,
                 "width":1,
                 "height":1,
                 "pinType":"VIRTUAL",
                 "pin":1,
                 "pwmMode":false,
                 "rangeMappingOn":false,
                 "min":0,
                 "max":0,
                 "frequency":0
              },
              {
                 "type":"SLIDER",
                 "id":1036300911,
                 "x":0,
                 "y":0,
                 "color":-308477697,
                 "width":4,
                 "height":1,
                 "pinType":"DIGITAL",
                 "pin":3,
                 "pwmMode":true,
                 "rangeMappingOn":false,
                 "min":0,
                 "max":255,
                 "value":"87"
              },
              {
                 "type":"LED",
                 "id":1036300902,
                 "x":3,
                 "y":1,
                 "color":1602017535,
                 "width":1,
                 "height":1,
                 "pinType":"VIRTUAL",
                 "pin":0,
                 "pwmMode":false,
                 "rangeMappingOn":false,
                 "min":0,
                 "max":0,
                 "frequency":0
              },
              {
                 "type":"DIGIT4_DISPLAY",
                 "id":1036300913,
                 "x":5,
                 "y":4,
                 "color":-308477697,
                 "width":2,
                 "height":1,
                 "pinType":"ANALOG",
                 "pin":14,
                 "pwmMode":false,
                 "rangeMappingOn":false,
                 "min":0,
                 "max":1023,
                 "frequency":1000
              },
              {
                 "type":"BUTTON",
                 "id":1036300914,
                 "x":5,
                 "y":5,
                 "color":616861439,
                 "width":2,
                 "height":2,
                 "pinType":"DIGITAL",
                 "pin":1,
                 "pwmMode":false,
                 "rangeMappingOn":false,
                 "min":0,
                 "max":0,
                 "value":"1",
                 "pushMode":false
              },
              {
                 "type":"NOTIFICATION",
                 "id":1036300915,
                 "x":5,
                 "y":7,
                 "width":2,
                 "height":1,
                 "androidTokens":{
                    "uid":"token"
                 },
                 "notifyWhenOffline":false,
                 "priority":"normal"
              },
              {
                 "type":"EMAIL",
                 "id":1036300916,
                 "x":5,
                 "y":9,
                 "width":2,
                 "height":1
              }
           ],
           "boardType":"Arduino UNO",
           "keepScreenOn":false,
           "isShared":false,
           "isActive":true
        }
        
+ Response 400 (plain/text)

        Invalid token.