Skip to main content

The Build API

The Build API is now no longer available. Please use the impCentral™ API

The Electric Imp Build APIbeta provides developers with a means to access the functionality of Electric Imp’s web-based IDE by other means, allowing them to develop imp application models using the tools of their choice.

Virtually any development-oriented task the developer can currently perform with the IDE, they can perform using Buildbeta. For example, it provides a way to list the models the developer has created and any devices associated with them. Devices can be moved from model to model, their human-friendly names changed, or placed in an unassigned state. Device logs can be downloaded for inspection. New models can be created, old one deleted. Agent and device code can be uploaded, and older versions accessed. Devices can be restarted.

Changes made via Build will be reflected in the IDE, however it may be necessary to refresh the browser in which the IDE is being viewed if, for instance, it is showing a model that is also being modified via the API.

Build’s scope is currently restricted to actions performed using the IDE for software development. Commercial customers will get their own production-centric API — or an extension of this one — in due course.

Using Buildbeta

Buildbeta is accessed using standard HTTPS verbs — GET, POST, PUT and DELETE — made to the base URL:

build.electricimp.com/v4/

API entities are exposed at specific endpoints. The commands can be issued using any available mechanism for making HTTPS requests: a web browser, a command line utility such as curl, or the facilities provided by the host operating system to native software.

Although this is the first use of the name ‘Build’, it is being released as version 4 of the API for historical reasons. Previous versions are not compatible with the new specification outlined here, but will continue to be made available to customers using them. However, they will no longer be updated or supported.

Buildbeta Authorization

Buildbeta uses Basic Authentication. Requests must supply a standard ‘Authorization’ header with the content string set to "Basic" followed by a space and then the developer’s Base64-encoded API key, for example:

{ "Authorization" : "Basic AbCdEfgh01234" }

If an incorrect API key is provided, this will result in an Unauthorized Access error (see below).

See this page to learn how to obtain your API key.

Buildbeta Entities

Buildbeta defines four entities: Device, Model, Log Entry and Code Revision.

Devices describe imp-based devices. Log entries are the messages posted to a specific device’s log. Models represent application software. Code revisions record the device and agent code that comprise each build of a given model.

Entities’ actions which return data can be accompanied by optional URL-encoded parameters to help you get a subset of all the information recorded: a specific device, model or log entry, for instance.

Each entity comprises one or more properties. All properties can be read, but not all of them can be changed — those that can be are marked as such in the following documentation. Changing one or more properties involves making an HTTPS PUT request with the properties and their values passed in JSON format within the HTTPS request’s body. Read-only properties included in this object will ignored. Properties not included in the passed JSON will remain unchanged.

Buildbeta Error Reporting

Error messages will be returned with a 4xx HTTP status code for errors caused by problems with the request, or a 5xx status code if a problem occurred with server communications. The error code is accompanied by a basic human-readable text string indicating the nature of the error, and a longer string for printing.

These are the standard error responses:

Type Status Code Response Body
Unauthorized access 401 { "success" : false , "error" : <error info> }
Resource not found 404 { "success" : false , "error" : <error info> }
Endpoint rate-limited 429 { "success" : false , "error" : <error info> }
Unexpected internal error 500 { "success" : false , "error" : <error info> }
Other errors 400 { "success" : false , "error" : <error info> }

The returned <error info> is an object with the following keys:

Key Value
code The error code (see above)
message_short Brief human-readable description of error
message_full Verbose error message

for example:

{ "success" : false,
  "error"   : { "code"          : "ModelNotFound",
                "message_short" : "Model '44' not found",
                "message_full"  : "Model '44' not found" }}

and

{ "success" : false,
  "error"   : { "code"          : "ResourceNotFound",
               "message_short" : "Unknown route GET /v4/bad",
               "message_full"  : "Unknown route GET /v4/bad" }}

and

{ "success" : false,
  "error"   : { "code"          : "RateLimited",
                "message_short" : "RateLimited",
                "message_full"  : "Rate Limited; retry in <seconds>" }}

Errors generated by the Squirrel syntax checker are slightly different: they have an extra key, details:

{ "success" : false,
  "error"   : { "code"          : "CompileFailed",
                "message_short" : "Imp code compile failed",
                "message_full"  : "Imp code compile failed\n12:9 expression expected",
                "details"       : { "device_errors" : [<device error>, <device error>, ... ],
                                    "agent_errors"  : [<agent error>, <agent error>, ... ]}}}

For full details of the objects <device error> and <agent error>, see Code Revision.

Success

Responses indicate a successful operation by returning the HTTP status code 200 and including the JSON

{ "success" : true,
  <returned data> }

in the response body. Further, method-specific data is also included in the response body.

All interactions with the API return data, even DELETE operations.

Buildbeta Access Rate Limitations

Build users are allotted no more than 50 requests per API key at any given moment. Every request you make reduces that total by one. If the total falls to zero, Build will return the HTTP status code 429. Every second, the total of available requests is increased by five, up to the maximum of 50. In response to receiving a 429, your your code should re-issue the request that triggered the limitation after at least one second.

Extra information can be gleaned from the response’s headers:

Header Value
X-RateLimit-Limit Request total limit, ie. the current maximum burst rate
X-RateLimit-Remaining Current number of requests that can be handled before you get rate limited
X-RateLimit-Reset Number of seconds until you have the maximum number of requests available again

These headers are available in all responses to help manage request posting.

Buildbeta Reference

Device

The device resource represents any imp-enabled device. It provides access to the same information currently displayed in the IDE — device name and ID — but can also be used to query state data: WiFi signal strength and whether the device is currently online or not. It can be used to find which model the device has been assigned to. It also records the identity of the agent that the device is paired with and the agent’s operational status.

Each individual device can be located at the path /devices/[id].

Device Properties

Key Value Type Editable Notes
id String No The device ID, eg. ‘23239eb236a7c9ee’
name String Yes The device’s human-friendly identifier, eg. ‘My April’
model_id String Yes The internal ID of the model. Default: null
powerstate String No “online” or “offline”
rssi Integer No WiFi signal strength as last reported by device in decibel milliwatts (dBm)
agent_id String No The ID of the device’s agent, eg. ‘AbCdEfgH1234’
agent_status String No “online” or “offline”

In all JSON responses, device objects will be denoted by <device>.

Delete a Device

Verb DELETE

Endpoint /devices/[id]

Response { "success" : true }

Notes

Deleting the specified device removes it from the list of devices that are assigned to models. It does not remove the device from your account. Deleting a connected device will result in that device immediately losing its model association: its model_id property is set to null (in the IDE it will appear under ‘Unassigned Device’. Deleting a disconnected device will result in no change to the device’s record until it is reconnects, either through its existing device code or because it has been power-cycled. When it reconnects, it model association is removed: again, its model_id property is set to null.

Example

The following Linux/Unix command line code will delete a specific device:

curl -v -X DELETE -u '<MY_API_KEY>:' https://build.electricimp.com/v4/devices/<DEVICE_ID>

To delete the device under Windows, you will need to configure the command as follows:

curl -k -v -X DELETE -u '<MY_API_KEY>:' https://build.electricimp.com/v4/devices/<DEVICE_ID>

This Python code does the same job:

import json, httplib, base64
apiKey = base64.b64encode('<YOUR_API_KEY>')
devId = '<DEVICE_ID>'
connection = httplib.HTTPSConnection('build.electricimp.com')
connection.connect()
connection.request('DELETE', '/v4/devices/' + devId, '', {"Authorization":"Basic " + apiKey})
results = json.loads(connection.getresponse().read())
print results

Get a Device

Verb GET

Endpoint /devices/[id]

Response { "success" : true, "device" : <device> }

Example

The following Linux/Unix command line code will retrive and display the details of a specific device, selected using its device ID, noted after listing all of your devices:

curl -v -X GET -u '<MY_API_KEY>:' https://build.electricimp.com/v4/devices/<DEVICE_ID>

To get a device’s properties under Windows, you will need to configure the command as follows:

curl -k -v -X GET -u '<MY_API_KEY>:' https://build.electricimp.com/v4/devices/<DEVICE_ID>

Here is a Python snippet to retrieve a specific device’s details:

import json, httplib, base64
apiKey = base64.b64encode('<YOUR_API_KEY>')
headers = {"Authorization":"Basic " + apiKey}
devId = '<DEVICE_ID>'
connection = httplib.HTTPSConnection('build.electricimp.com')
connection.connect()
connection.request('GET', '/v4/devices/' + devId, '', headers)
results = json.loads(connection.getresponse().read())
print results

List Devices

Verb GET

Endpoint /devices

Response { "success" : true, "devices" : [<device>, <device>, ... <device>] }

Notes

If any of the optional query parameters are to be supplied, they must be passed in URL-encoded form. If no devices are found, the devices key will have an empty array value.

Examples

The following Linux/Unix command line code will retrieve and display all of the devices associated with your developer account:

curl -v -X GET -u '<MY_API_KEY>:' https://build.electricimp.com/v4/devices

This is the code you’d use if you have the device’s name:

curl -v -X GET -u '<MY_API_KEY>:' https://build.electricimp.com/v4/devices?name=<DEVICE_NAME>

The following code lists all the devices associated with the model:

curl -v -X GET -u '<MY_API_KEY>:' https://build.electricimp.com/v4/devices?model_id=<MODEL_ID>

To get a list of your devices under Windows, you will need to configure the command as follows:

curl -k -v -X GET -u '<MY_API_KEY>:' https://build.electricimp.com/v4/devices

Here is a Python snippet to retrieve all your devices:

import json, httplib, base64
apiKey = base64.b64encode('<YOUR_API_KEY>')
headers = {"Authorization":"Basic " + apiKey}
connection = httplib.HTTPSConnection('build.electricimp.com')
connection.connect()
connection.request('GET', '/v4/devices', '' , headers)
results = json.loads(connection.getresponse().read())
print results

The following code returns all your devices with names containing the string ‘test’:

import json, httplib, base64, urllib
apiKey = base64.b64encode('<YOUR_API_KEY>')
headers = {"Authorization":"Basic " + apiKey}
params = urllib.urlencode({'name':'test'})
connection = httplib.HTTPSConnection('build.electricimp.com')
connection.connect()
connection.request('GET', '/v4/devices?' + params, '', headers)
results = json.loads(connection.getresponse().read())
print results

Restart a Device

Verb POST

Endpoint /devices/[id]/restart

Response { "success" : true }

Notes

Call this method to restart a specific device. To restart all of the devices assigned to a specific model, use Restart Model. Restarting a device also restarts its agent.

If the method returns { "success" : true }, it does not mean that the device has restarted, only that an instruction to restart has been sent. If the device is caught within an infinite loop, or is asleep or offline, it may not be able to respond to the restart command.

Example

The following Linux/Unix command line code can be used to reboot the device:

curl -v -X POST -u '<MY_API_KEY>:' https://build.electricimp.com/v4/devices/<DEVICE_ID>/restart

To restart a device under Windows, you will need to configure the command as follows:

curl -k -v -X POST -u '<MY_API_KEY>:' https://build.electricimp.com/v4/devices/<DEVICE_ID>/restart

So does this Python code:

import json, httplib, base64
apiKey = base64.b64encode('<YOUR_API_KEY>')
headers = {"Authorization":"Basic " + apiKey}
devId = '<DEVICE_ID>'
connection = httplib.HTTPSConnection('build.electricimp.com')
connection.connect()
connection.request('POST', '/v4/devices/ + devId + '/restart', '', headers)
results = json.loads(connection.getresponse().read())
print results

Update a Device

Verb PUT

Endpoint /devices/[id]

Request Full or partial JSON representation of the device’s properties

Response { "success" : true, "device" : <device> }

Notes

This method only updates the editable device properties. Read-only properties will not be changed and neither will omitted properties. No notification is currently given that an attempt has been made to change an immutable property. However, as the updated device object is returned, it is possible to compare values ‘before’ and ‘after’ to check what changes have actually been made.

Assign a model_id of null ("") if you wish to move a device into an unassigned state.

The device’s name can contain no more than 128 characters and must include at least one non-space character. Attempts to set a device name outside of these restrictions will result in an error. Because devices are currently differentiated solely by their ID, multiple devices may have the same name.

When you update a device, you must include the header "Content-Type: application/json" in your request.

Examples

To assign a new model to a device (under Linux/Unix), you will need the software’s model ID and the ID of the device:

curl -v -X PUT -u '<MY_API_KEY>:' -H "Content-Type: application/json" -d '{"model_id":<MODEL_ID>}' https://build.electricimp.com/v4/devices/<DEVICE_ID>

To remove a device’s assignment to a model, assign it to a null model:

curl -v -X PUT -u '<MY_API_KEY>:' -H "Content-Type: application/json" -d '{"model_id":""}' https://build.electricimp.com/v4/devices/<DEVICE_ID>

Here is a Python snippet to assign a specific device to a specific model:

import json, httplib, base64
devId = '<DEVICE_ID>'
modId = '<THE_MODEL_ID>'
apiKey = base64.b64encode('YOUR_API_KEY')
headers = {"Authorization":"Basic " + apiKey, "Content-Type": "application/json"}
data = json.dumps({"model_id":modId})
connection = httplib.HTTPSConnection('build.electricimp.com')
connection.connect()
connection.request('PUT', '/v4/devices/' + devId, data, headers)
results = json.loads(connection.getresponse().read())
print results

Log Entry

The log entry resource represents a single item in a device’s log. A given device may therefore be associated with many log entries. Logs are stored with the device that generates them, including messages logged by the device’s agent. There is a limit applied to the number of log entries stored with each device: no more than 200 of the most recent log entries are retained. Beyond this number, the addition of a new log entry will cause the oldest one to be deleted.

Specific log entries are located at the path /devices/[id]/logs.

Log Entry Properties

Key Value Type Editable Notes
timestamp String No The ISO 8601 timestamp at which the entry was posted
type String No The entry’s flag, eg. ”Agent”, “Device”, “Status”, etc.
message String No The logged information

In all JSON responses, log entry objects will be denoted by <log entry>.

The API currently provides the following values for the log entry type key:

Type Value Source/Reason
server.log Device code calls server.log()
server.error Device code error
server.sleep Device goes into Deep Sleep
agent.log Agent code calls server.log()
agent.error Agent code error
status Status message
powerstate Device power state message
lastexitcode Exit Code message
firmware Firmware update message

List Logs

Verb GET

Endpoint /devices/[id]/logs

Response { "success" : true, "logs" : [ <log entry>, <log entry>, <log entry>, ... ], "poll_url" : "/v4/..." }

Notes

If the optional query parameter, since, is to be supplied with a value, it must be passed in URL-encoded form. If no log entries are found, the value of the logs key will be an empty array.

This method provides a way to retrieve not only historical log entries but also to receive log entries in near real time. Called without parameters, the method will return however many historical log entries are stored on the server, up to a maximum of 200; the server retains no more than 200 recent log entries. The response also includes a value assigned to the key poll_url, which can be called as a long poll: it will return after one minute (the timeout) or when a new log entry is posted. In either case, the same poll_url can be called again to await the next log entry (or timeout).

The poll_url contains a token to identify the specific log, so should not be edited. If you require a poll_url for another device, make a suitable call to /devices/[id]/logs to retrieve it. Any token will expire if not used within five minutes of issue. The token is used to ensure only new log entries are returned each time it is called.

Examples

The following Linux/Unix command line code will retrieve and present the most recent log entries (up to a maximum of 200) for the device:

curl -v -X GET -u '<MY_API_KEY>:' https://build.electricimp.com/v4/devices/<DEVICE_ID>/logs

To list your models under Windows, you will need to configure the command as follows:

curl -k -v -X GET -u '<MY_API_KEY>:' https://build.electricimp.com/v4/devices/<DEVICE_ID>/logs

Here is a Python snippet to retrieve all of a device’s log files:

import json, httplib, base64
apiKey = base64.b64encode('<YOUR_API_KEY>')
devId = '<DEVICE_ID>'
connection = httplib.HTTPSConnection('build.electricimp.com')
connection.connect()
connection.request('GET', '/v4/devices/' + devId + '/logs', '', {"Authorization":"Basic " + apiKey})
results = json.loads(connection.getresponse().read())
print results

Model

The model resource represents an imp application and comprises agent and device code. The code itself is stored as a series of code revision objects under the model to which they belong.

Specific models are located at the path /models/[id].

Model Properties

Key Value Type Editable Notes
id String No The model’s unique ID code
name String Yes The model’s human-friendly name, eg. ‘Digital Clock’
devices Array No The id values of the devices assigned to the model, or an empty array if the model has no devices assigned to it

In all JSON responses, model objects will be denoted by <model>.

Create a Model

Verb POST

Endpoint /models

Response { "success" : true, "model" : <model> }

Notes

Only the name property can be set. If you include a value for id in your properties, it will be ignored. The id property is generated for you.

The model’s name can contain no more than 128 characters and must include at least one non-space character. Attempts to set a model name outside of these restrictions will result in an error.

When you create a model, you must include the header "Content-Type: application/json" in your request.

Example

The following Linux/Unix command line code shows you how to create a new model and then assign it to a device:

Create the model:

curl -v -X POST -u '<MY_API_KEY>:' -H "Content-Type: application/json" -d '{"name":"Test"}' https://build.electricimp.com/v4/models

Update your list of models to get the new model’s ID:

curl -v -X GET -u '<MY_API_KEY>:' https://build.electricimp.com/v4/models

Assign the new model to the device using its ID:

curl -v -X PUT -u '<MY_API_KEY>:' -H "Content-Type: application/json" -d '{"model_id":modId}' https://build.electricimp.com/v4/devices/<DEVICE_ID>

This code shows how you create a model called “test” using Python:

import json, httplib, base64
apiKey = base64.b64encode('<YOUR_API_KEY>')
data = json.dumps({"name":"test"})
headers = {"Content-type":"application/json", "Authorization":"Basic " + apiKey}
connection = httplib.HTTPSConnection('build.electricimp.com')
connection.connect()
connection.request('POST', '/v4/models', data, headers)
results = json.loads(connection.getresponse().read())
print results

Delete a Model

Verb DELETE

Endpoint /models/[id]

Response { "success" : true }

Notes

Models can only be deleted if no devices have been assigned to them. This includes factory imps. Devices can be assigned to other models, or assigned to no model, using the device object’s Update Device method. Factory imps can not be unassigned at this time.

Example

The following Linux/Unix command line code shows you how to delete an existing model:

curl -v -X DELETE -u '<MY_API_KEY>:' https://build.electricimp.com/v4/models/<MODEL_ID>

To delete the model under Windows, you will need to configure the commands as follows:

curl -k -v -X DELETE -u '<MY_API_KEY>:' https://build.electricimp.com/v4/models/<MODEL_ID>

This Python code performs the same task:

import json, httplib, base64
apiKey = base64.b64encode('<YOUR_API_KEY>')
headers = {"Authorization":"Basic " + apiKey}
modId = '<MODEL_ID>'
connection = httplib.HTTPSConnection('build.electricimp.com')
connection.connect()
connection.request('DELETE', '/v4/models/ + modId', '', headers)
results = json.loads(connection.getresponse().read())
print results

Get a Model

Verb GET

Endpoint /devices/[id]

Response { "success" : true, "model" : <model> }

Example

The following Linux/Unix command line code will retrive and display the details of a specific model, selected using its model ID, noted after listing all of your models:

curl -v -X GET -u '<MY_API_KEY>:' https://build.electricimp.com/v4/models/<MODEL_ID>

To get a model’s properties under Windows, you will need to configure the commands as follows:

curl -k -v -X GET -u '<MY_API_KEY>:' https://build.electricimp.com/v4/models/<MODEL_ID>

Here’s a Python snippet that returns the same information:

import json, httplib, base64
apiKey = base64.b64encode('<YOUR_API_KEY>')
headers = {"Authorization":"Basic " + apiKey}
modId = '<MODEL_ID>'
connection = httplib.HTTPSConnection('build.electricimp.com')
connection.connect()
connection.request('GET', '/v4/models/' + modId, '', headers)
results = json.loads(connection.getresponse().read())
print results

List Models

Verb GET

Endpoint /models

Response { "success" : true, "models" : [<model>, <model>, ... <model>] }

Notes

If the optional query parameter is to be supplied, it must be passed in URL-encoded form. If no models were found, the models key will have an empty array value.

Examples

The following Linux/Unix command line code will retrieve and display all of the models associated with your developer account:

curl -v -X GET -u '<MY_API_KEY>:' https://build.electricimp.com/v4/models

This code presents the details of the model named “WeatherStation”:

curl -v -X GET -u '<MY_API_KEY>:' https://build.electricimp.com/v4/models?name=weatherstation

This code lists all of your models whose names contain the string “neo”:

curl -v -X GET -u '<MY_API_KEY>:' https://build.electricimp.com/v4/models?name=neo

To list your models under Windows, you will need to configure the command as follows:

curl -k -v -X GET -u '<MY_API_KEY>:' https://build.electricimp.com/v4/models

Here is a Python snippet that returns the same information:

import urllib, json, httplib, base64
apiKey = base64.b64encode('<YOUR_API_KEY>')
headers = {"Authorization":"Basic " + apiKey}
params = urllib.urlencode({"name":"neo"})
connection = httplib.HTTPSConnection('build.electricimp.com')
connection.connect()
connection.request('GET', '/v4/models?' + params, '', headers)
results = json.loads(connection.getresponse().read())
print results

While this code returns all your models:

import json, httplib, base64
apiKey = base64.b64encode('YOUR_API_KEY')
headers = {"Authorization":"Basic " + apiKey}
connection = httplib.HTTPSConnection('build.electricimp.com')
connection.connect()
connection.request('GET', '/v4/models', '', headers)
results = json.loads(connection.getresponse().read())
print results

Restart a Model’s Devices

Verb POST

Endpoint /models/[id]/restart

Response { "success" : true }

Notes

Restarting the devices also restarts those devices’ agents. Call this method to restart all of the devices assigned to a specific model. To restart a specific device, use Restart Device.

If the method returns { "success" : true }, it does not mean that any or all of the devices have restarted, only that an instruction to restart has been sent to them. If one or more of the devices are caught within an infinite loop, or are asleep or offline, they may not be able to respond to the restart command.

Example

The following Linux/Unix command line code can be used to reboot all of the devices assigned to a model:

curl -v -X POST -u '<MY_API_KEY>:' https://build.electricimp.com/v4/models/<MODEL_ID>/restart

To restart a model’s devices under Windows, you will need to configure the command as follows:

curl -k -v -X POST -u '<MY_API_KEY>:' https://build.electricimp.com/v4/models/<MODEL_ID>/restart

So does this Python code:

import json, httplib, base64
apiKey = base64.b64encode('<YOUR_API_KEY>')
headers = {"Authorization":"Basic " + apiKey}
modId = '<MODEL_ID>'
connection = httplib.HTTPSConnection('build.electricimp.com')
connection.connect()
connection.request('POST', '/v4/models/ + modId + '/restart', '', headers)
results = json.loads(connection.getresponse().read())
print results

Update a Model

Verb PUT

Endpoint /models/[id]

Request Full or partial JSON representation of the model’s properties

Response { "success" : true, "model" : <model> }

Notes

Only the name property can be edited. If you include a value for id in your updated properties, it will be ignored.

The model’s name can contain no more than 128 characters and must include at least one non-space character. Attempts to set a model name outside of these restrictions will result in an error.

When you update a model, you must include the header "Content-Type: application/json" in your request.

Example

The following Linux/Unix command line code can be used to give a model a new human-readable name. You’ll need the model’s ID, which you can obtain by listing all models:

curl -v -X PUT -u '<MY_API_KEY>:' -H "Content-Type: application/json" -d '{"name":"Excelsior"}' https://build.electricimp.com/v4/models/<MODEL_ID>

Here’s how it can be done in Python:

import json, httplib, base64
apiKey = base64.b64encode('<YOUR_API_KEY>')
data = json.dumps({"name":"Excelsior"})
headers = {"Content-type":"application/json", "Authorization":"Basic " + apiKey}
modId = '<MODEL_ID>'
connection = httplib.HTTPSConnection('build.electricimp.com')
connection.connect()
connection.request('PUT', '/v4/models/' + modId, data, headers)
results = json.loads(connection.getresponse().read())
print results

Code Revision

The code revision resource represents a model’s agent and device code as uploaded at a particular time. A single revision can contain updated agent code, updated device code, or both. If one of these properties is not provided, it is automatically populated in the new code revision with a copy from the previous revision. Typically, a model will contain many code revisions, the number growing as the model evolves. Each code revision is equivalent to a new build in the IDE.

When a new code revision is uploaded to a model, it is first checked for syntax errors — the equivalent of hitting the ‘Check’ button in the IDE. Any errors found in either the device and/or the agent code are reported, and no code is saved. If both agent and device code pass the syntax check, they are saved, and the model’s build total is incremented — the equivalent of hitting ‘Build’ in the IDE. Successfully uploaded and stored code revisions are not run until the model’s devices are restarted.

Specific code revisions are located at the path /models/[id]/revisions.

Full Code Revision Properties

Key Value Type Editable Notes
version Integer No The build number of the model
created_at String No The UTC Unix timestamp taken when the code was created
device_code String Yes The device code
agent_code String Yes The agent code

In all JSON responses, code revision objects will be denoted by <revision> for the full object above, or <short revision> for the shortened version:

Short Code Revision Properties

Key Value Type Editable Notes
version Integer No The build number of the model
created_at String No The UTC Unix timestamp taken when the code was created

Get a Code Revision

Verb GET

Endpoint /models/[id]/revisions/[build number]

Response { "success" : true, "revisions" : <revision> }

Example

The following Linux/Unix command line code can be used to get the code for build 42 of model:

curl -v -X GET -u '<YOUR_API_KEY>:' https://build.electricimp.com/v4/models/<MODEL_ID>/revisions/42

To get the code revision under Windows, you will need to configure the command as follows:

curl -k -v -X GET -u '<MY_API_KEY>:' https://build.electricimp.com/v4/models/<MODEL_ID>/revisions/42

List Code Revisions

Verb GET

Endpoint /models/[id]/revisions

Response { "success" : true, "revisions" : [ <short revision>, <short revision>, ... ] }

Notes

No more than 200 revisions will be returned with any one request, even if your request explicitly asks for a greater number of revisions (assuming they all exist). For example, if your model has reached build 206, and you provide no optional query parameters, you will be returned builds 6 through 206, ie. the most recent 200 revisions. If you require a build outside of the 200 returned to you, either provide optional parameters, or request a specific revision.

However many code revisions are requested (implicitly or explicitly) they will be provided in reverse order, the most recent revision in the requested list coming first.

If any of the optional query parameters are to be supplied, they must be passed in URL-encoded form. An empty response body indicates no matching code revisions were found. The list of revisions returned by this model uses the short version of the code revision properties, ie. the version and created_at properties only.

Examples

The following Linux/Unix command line code can be used to list all the code revisions (in short form) for a model:

curl -v -X GET -u '<YOUR_API_KEY>:' https://build.electricimp.com/v4/models/<MODEL_ID>/revisions

The following command line code can be used to list the code revisions (in short form) from builds 100 to 110 for a model. Note that you need to put the URL in double-quotes to prevent the command line terminating the input at the ‘&’:

curl -v -X GET -u '<YOUR_API_KEY>:' "https://build.electricimp.com/v4/models/<MODEL_ID>/revisions?build_min=100&build_max=110"

To list all the code revisions under Windows, you will need to configure the command as follows:

curl -k -v -X GET -u '<MY_API_KEY>:' https://build.electricimp.com/v4/models/<MODEL_ID>/revisions

Upload a Code Revision

Verb PUT

Endpoint /models/[id]/revisions

Request Full or partial JSON representation of the code revision’s properties

Response { "success" : true, "revision" : <revision> }

Notes

If either or both of the code revision’s agent_code and device_code properties are omitted or null, then those values will be automatically be populated with the values from the previous code revision, or null if that revision contains empty values (or there is no previous code revision).

When you upload code, you must include the header "Content-Type: application/json" in your request.

Code Revision Errors

Uploaded code revisions are first checked for syntax errors just as the IDE does when you click ‘Check’, ‘Build’ or ‘Build and Run’. If errors are found in your agent and/or device code, they will be reported as outlined above. The error structure contains an extra key, details: its value is an object containing two keys, device_errors and agent_errors. These have one or more <device error> and <agent error> objects as their values.

The <device error> and <agent error> objects contain the following keys:

Key Value Type Notes
row Integer The source file row at which the error was reported
column Integer The source file column at which the error was reported
error String The error reported by the syntax checker

The result is a response such as this:

{ "success" : false,
  "error"  : { "code"   : "CompileFailed",
               "message_short" : "Imp code compile failed",
               "message_full" : "Imp code compile failed\n12:9 expression expected",
               "details" : { "device_errors" : { "row" : 2 ,
                                                 "column" : 19,
                                                 "error" : "expression expected" },
                              "agent_errors" : "" }
             }
}

Example

The following Linux/Unix command line code can be used to add initial dummy code to a newly created model:

curl -v -X POST -u '<MY_API_KEY>:' -H "Content-Type: application/json" -d '{"agent_code":"// Agent Code","device_code":"// Device Code"}' https://build.electricimp.com/v4/models/<MODEL_ID>/revisions

Back to the top of the page