Customer API Documentation

Overview

The Customer API is a resource for Lamplighter customers to access their data from outside of the application. The API is currently a read-only API but we have plans to add create/update/delete functionality later. Each endpoint in the API returns JSON.

API Keys

In order to access the API, you need to generate at least one API key from the https://COMPANY.lamplighter.io/company/api-keys page in Lamplighter. You must be the account owner or have administrative privileges in order to access that page. You can generate as many API keys as you'd like.

Authentication

The Lamplighter API uses BASIC Authentication over SSL. Here is a sample request using PHP's curl functions.

<?php

$key    = '12345678901234567890';
$secret = '0192837465748392';

$ch = curl_init('https://api.lamplighter.io/user/444');

curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, $key.':'.$secret);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPGET, 1);

$response = urldecode(curl_exec($ch));
curl_close($ch);

Error Handling

Any requests made to the API that result in an error will return one of the following responses with an appropriate HTTP status code:

400 - Bad Request

{
   "error":"Object did not pass validation.",
   "messages":{
      "email":[
         "The email format is invalid."
      ],
      "password":[
         "The password field is required."
      ]
   }
}

401 - Unauthorized Request

{
   "error":"You are not authorized to access this resource."
}

404 - Invalid Record

{
   "error":"Record not found."
}

404 - Invalid API endpoint

{
   "error":"The specified API endpoint does not exist."
}

500 - Application error

{
   "error":"There was an application error."
}

503 - Maintenance

{
   "error":"This resource is currently down for maintenance."
}

Embeds

Many of the read-only API endpoints have embeddable relationship data sets that can be included with the API response. Endpoints with embed options return an array of what those options are. Many of the embeddable relationships can be nested using dot syntax as well.

The example below will fetch basic company data along with all the sites and all the notes belonging to those sites.

GET https://api.lamplighter.io/company?embed=sites.notes

This example will fetch your company's sites, the site's addons and notes with the authoring user embedded.

GET https://api.lamplighter.io/sites?embed=addons,notes.user

Request

GET https://api.lamplighter.io/user/41?embed=notes

Sample Response

{
   "data":{
      "id":41,
      "created_at":"2013-10-11 14:00:00",
      "updated_at":"2014-01-29 17:00:00",
      "first_name":"Darnell",
      "last_name":"Turner",
      "email":"darnell.turner@lambfighter.com",
      "avatar":"https:\/\/lamplighter.io\/upload\/avatars\/2012_12_01_41.jpg",
      "group":"Administrator",
      "daily_email":true,
      "notes":{
         "data":[
            {
               "id":25,
               "created_at":"2013-11-05 18:58:19",
               "updated_at":"2013-11-05 18:58:19",
               "author_id":"41",
               "name":"Some Information About a Site",
               "note":"<p>I think this data might be useful.<p>"
            },
            {
               "id":81,
               "created_at":"2014-03-11 15:09:21",
               "updated_at":"2014-03-11 15:09:21",
               "author_id":"41",
               "name":"Never Forget This",
               "note":"<p>This information is so valuable.<p>"
            }
         ],
         "embeds":[
            "site",
            "user"
         ]
      }
   },
   "embeds":[
      "notes",
      "site_permissions"
   ]
}

GET company

This endpoint fetches some basic information about your company. With the proper embeds, you can get nearly all your primary data out of Lamplighter.

Request

GET https://api.lamplighter.io/company

Sample Response

{
   "data":{
      "id":1337,
      "created_at":"2013-12-26 13:00:00",
      "updated_at":"2014-02-29 17:58:00",
      "name":"Lambfighter Media",
      "subdomain":"lambfighter",
      "plan":"Masuga",
      "logo":"https:\/\/lamplighter.io\/upload\/logos\/2012_13_17_20.png"
   },
   "embeds":[
      "sites",
      "users"
   ]
}

GET events

This endpoint fetches a paginated collection for company timeline events.

Request

GET https://api.lamplighter.io/events

Sample Response

{
    "data": [
        {
            "id": 39905,
            "created_at": "2015-03-13 03:59:37",
            "type": "Uptime Status Change",
            "header": "<strong><a href=\"https://app.lamplighter.io/mdesign/site/coolestsite/timeline\">CoolestSite</a></strong> site status has changed.",
            "header_text": "CoolestSite site status has changed.",
            "details": "CoolestSite is <strong>DOWN</strong> - Connection Timeout.",
            "details_text": "CoolestSite is DOWN - Connection Timeout."
        },
        {
            "id": 39903,
            "created_at": "2015-03-13 03:59:35",
            "type": "Uptime Status Change",
            "header": "<strong><a href=\"https://app.lamplighter.io/mdesign/site/amazingsite/timeline\">AmazingSite</a></strong> site status has changed.",
            "header_text": "AmazingSite site status has changed.",
            "details": "AmazingSite is <strong>DOWN</strong> - Connection Timeout.",
            "details_text": "AmazingSite is DOWN - Connection Timeout."
        },

        …

    ],
    "embeds":[
        "user",
        "site",
        "note",
        "addon",
    ],
    "meta": {
        "pagination": {
            "total": 5538,
            "count": 50,
            "per_page": 50,
            "current_page": 3,
            "total_pages": 111,
            "links": {
                "previous": "https://api.lamplighter.io/events?page=2",
                "next": "https://api.lamplighter.io/events?page=4"
            }
        }
    }
}

GET users

This endpoint fetches some basic information about each of your company's users.

Request

GET https://api.lamplighter.io/users

Sample Response

{
   "data":[
      {
         "id":3050,
         "created_at":"2013-09-26 13:58:52",
         "updated_at":"2014-01-29 16:23:34",
         "first_name":"Smokey",
         "last_name":"Floyd",
         "email":"smokey.floyd@lambfighter.com",
         "avatar":"https:\/\/lamplighter.io\/upload\/avatars\/2012_13_.jpg",
         "group":"Owner",
         "daily_email":true
      },
      {
         "id":3051,
         "created_at":"2014-01-03 14:54:17",
         "updated_at":"2014-01-28 15:02:42",
         "first_name":"Sabrina",
         "last_name":"Collins",
         "email":"sabrina.collins@lambfighter.com",
         "avatar":"",
         "group":"User",
         "daily_email":true
      }
   ],
   "embeds":[
      "notes",
      "site_permissions"
   ]
}

GET user/:id

This endpoint fetches information about a single user by ID.

Request

GET https://api.lamplighter.io/user/41

Sample Response

{
   "data":{
      "id":41,
      "created_at":"2013-10-11 14:48:30",
      "updated_at":"2014-01-29 17:57:05",
      "first_name":"Char Gar",
      "last_name":"Gothakon",
      "email":"chargar.gothakon@lambfighter.com",
      "avatar":"https:\/\/lamplighter.io\/upload\/avatars\/2012_12_10_41.jpg",
      "group":"Administrator",
      "daily_email":true
   },
   "embeds":[
      "notes",
      "site_permissions"
   ]
}

POST user

This endpoint allows you to create a new user.

Request

POST https://api.lamplighter.io/user

Request Body

{
   "email":"billy@verycompany.wow",
   "first_name":"Billy",
   "last_name":"Baxter",
   "password":"sc0o8YdOo",
   "group_id":1
}

Sample Response

200 OK
[]

PUT user/:id

This endpoint allows you to update an existing user by ID. It accepts all of the columns available with the POST user route.

Request

PUT https://api.lamplighter.io/user/500

Request Body

{
   "password":"4nDscrApPy2",
   "group_id":2
}

Sample Response

200 OK
[]

DELETE user/:id

This endpoint allows you to delete an existing user by ID.

Request

DELETE https://api.lamplighter.io/user/500

Sample Response

200 OK
[]

GET sites

This endpoint allows you to fetch a list of sites associated with your company account.

Request

GET https://api.lamplighter.io/sites

Sample Response

{
   "data":[
      {
         "id":1,
         "created_at":"2013-10-03 14:24:32",
         "updated_at":"2014-03-10 15:15:02",
         "name":"Your Amazing Site",
         "url":"http:\/\/youramazingsite.website",
         "cms":"ExpressionEngine",
         "cms_version":"2.5.5",
         "uptime": {
            "1": "100",
            "7": "100",
            "14": "98.7",
            "30": "96.4"
          }
      },
      {
         "id":2,
         "created_at":"2013-10-03 17:29:14",
         "updated_at":"2014-03-10 15:15:02",
         "name":"PainFreeTweezers",
         "url":"http:\/\/painfreetweezers.website",
         "cms":"WordPress"
         "cms_version":"4.0.0",
         "uptime": {
            "1": "100",
            "7": "100",
            "14": "100",
            "30": "99.2"
          }
      }
   ],
   "embeds":[
      "notes",
      "addons",
      "pagespeeds",
      "commits"
   ]
}

GET site/:id

This endpoint fetches information about a single site by ID. Uptime percentages--when available--are segmented by past 1 day, 7 days, 14 days and 30 days.

Request

GET https://api.lamplighter.io/site/451

Sample Response

{
   "data":{
      "id":451,
      "created_at":"2013-10-03 14:24:32",
      "updated_at":"2014-02-11 18:15:02",
      "name":"Monitored Website",
      "url":"http://monitoredwebsite.website",
      "cms":"ExpressionEngine",
      "cms_version":"2.8.0",
      "uptime": {
        "1": "100",
        "7": "100",
        "14": "98.7",
        "30": "96.4"
      }
   },
   "embeds":[
      "notes",
      "addons",
      "pagespeeds",
      "commits",
      "timelineEvents"
   ]
}

POST site

This endpoint allows you to create a new site.

Valid "cms" values: Craft, ExpressionEngine, None, WordPress

Request

POST https://api.lamplighter.io/site

Request Body

{
   "name":"Super Amazing Client Site",
   "url":"http:\/\/superamazingclient.site",
   "cms":"ExpressionEngine",
   "cms_version":"5.0.4",
   "version_control":"bitbucket",
   "admin_url":"http://superamazingclient.site/manage_admin"
}

Sample Response

200 OK
[]

PUT site/:id

This endpoint allows you to update an existing site by ID. It accepts all of the columns available with the POST site route.

Request

PUT https://api.lamplighter.io/site/365

Request Body

{
   "cms_version":"6.0.0",
   "version_control":"github"
}

Sample Response

200 OK
[]

DELETE site/:id

This endpoint allows you to delete an existing site by ID.

Request

DELETE https://api.lamplighter.io/site/365

Sample Response

200 OK
[]

GET notes

This endpoint fetches a list of your company's notes.

Request

GET https://api.lamplighter.io/notes

Sample Response

{
   "data":[
      {
         "id":3205,
         "created_at":"2013-10-25 15:35:14",
         "updated_at":"2013-10-25 15:35:14",
         "author_id":"34",
         "name":"Something Very Important",
         "note":"<p>This is a very important note.</p>"
      },
      {
         "id":3206,
         "created_at":"2013-11-21 20:26:37",
         "updated_at":"2013-11-21 20:26:37",
         "author_id":"34",
         "name":"Useful Information",
         "note":"<p>Here is some information you might like.</p>"
      }
   ],
   "embeds":[
      "site",
      "user"
   ]
}

GET note/:id

This endpoint fetches a single note by ID.

Request

GET https://api.lamplighter.io/note/3205

Sample Response

{
   "data":{
      "id":3205,
      "created_at":"2013-10-25 15:35:14",
      "updated_at":"2013-10-25 15:35:14",
      "author_id":"34",
      "name":"Something Very Important",
      "note":"<p>This is a very important note.</p>"
   }
   "embeds":[
      "site",
      "user"
   ]
}

POST note

This endpoint allows you to create a new note.

Request

POST https://api.lamplighter.io/note

Request Body

{
   "user_id": 50,
   "site_id": 105,
   "name":"Office Contact Person",
   "note":"<p>Thurman Merman (616) 555-1010</p>"
}

Sample Response

200 OK
[]

PUT note/:id

This endpoint allows you to update an existing note by ID. It accepts all of the columns available with the POST note route.

Request

PUT https://api.lamplighter.io/note/2020

Request Body

{
   "name":"Primary Office Contact Person",
   "note":"<p>Thurman Merman (616) 555-1035</p>"
}

Sample Response

200 OK
[]

DELETE note/:id

This endpoint allows you to delete an existing note by ID.

Request

DELETE https://api.lamplighter.io/note/2020

Sample Response

200 OK
[]