NAV Navbar
Logo
cURL Python JSON

Introduction

API Endpoints

Production:
https://api.yombo.net

Development:
https://apidev.yombo.net

The API documentation is still a work in progress.

We’ve designed our API to be easily consumed by nearly any type of software, script, or application using standard HTTP. This allows a script to turn on/off device, poll device information, or change system configurations.

The Yombo API is organized around REST with predictable resource oriented URLs. The API uses standard HTTP response code to indicate successes or errors. Combined with HTTP verbs, this allows off-the-shelf HTTP clients to access the API. By default, our API returns results in JSON format, however we also support more advanced msgpack, as well as support for older clients with XML.

Topics

API Key

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-H "Accept: application/json" \
https://api.yombo.net/api/v1/command
import requests

url = 'https://api.yombo.net/api/v1/command'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    'Accept': 'application/json',  # demo, this is the default
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results

An API key must be sent with all requests for the service to accept the request. The API key should be submited in the header ‘x-api-key’, and looks like the following:

x-api-key: abc123xyz789

You can request an API key by emailing supprt@yombo.net with a desription for the usage of the API key.

Limit response sizes

Results can be rather large and can overwhelm lower powered machines, or cause retries on un-relable network connections. Here are the methods to limit the size of the result:

Summary

The following query string parameters are used for reducing response sizes:

Name Value Description Example
_filters[] Many Applies a filter on one or more colums. ?_filters[status]>1&_filters[label]^on
_filteroperator and, or Operation to apply filters on.
Either “and” together, or “or” together.
?_filters[status]>1&_filters[label]^on&_filteroperator=or
_pagelimit Numeric How many items per ‘page’ should be returned. ?_pagelimit=100
_pagestart Numeric What page to retrieve. AKA: Offset. ?_pagestart=4

Filters

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-H "Accept: application/json" \
https://api.yombo.net/api/v1/command?_pagelimit=2&_filter[label]=^o
import requests

url = 'https://api.yombo.net/api/v1/command?_pagelimit=2&_filter[label]=^o'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    'Accept': 'application/json',  # demo, this is the default
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/command?_filter[label]=^o&_pagelimit=2",
    "uri_description": "List of commands, includes private commands for logged in users or gateways.",
    "doc_uri": "https://yombo.net/docs/api/commands/",
    "locator": "command",
    "locator_type": "objects",
    "command": [
      {
        "id": "gaDO5dJgo397B",
        "voice_cmd": "on",
        "machine_label": "on",
        "label": "On",
        "description": "Sends an on command",
        "public": 2,
        "status": 1,
        "created_at": 1482065387,
        "updated_at": 1482065387
      },
      {
        "id": "bZ73EoBYd2e5w",
        "voice_cmd": "off",
        "machine_label": "off",
        "label": "Off",
        "description": "Sends an off command",
        "public": 2,
        "status": 1,
        "created_at": 1482065387,
        "updated_at": 1482065387
      }
    ]
  },
  "code": 200,
  "warnings": [],
  "errors": [],
  "filters": [],
  "pages": {
    "total_items": 41,
    "page_limit": 2,
    "total_pages": 21,
    "page_start": 1
  },
  "message": "OK",
  "html_message": "OK"
}

Advanced filtering of results is possible using the _filters[] query string parameter. Simply enter the field to be selected inside the brackets, followed the operator selection and finally, the value. See the below table for examples.

Operation Description Example
= Field value should equal filter. Show records that are enabled
?_filters[status]=1
!= Field value should NOT equal filter. Show records that are NOT enabled
(returns disabled and deleted)
?_filters[status]!=1
> Field value should be greater than filter. Show public or public pending.
?_filters[public]>0
>= Field value should be greater than
or equal to filter.
Show public or public pending.
?_filters[public]>=1
< Field value should be less than filter. Show private or public pending.
?_filters[public]<2
<= Field value should be less than
or equal to filter.
Show records are private or public pending.
?_filters[public]<=1
^ Should fields that start with something. See example
Return records where field starts with ‘o’. Like: ‘o*’
?_filters[label]^o
$ Should fields that end with something. Return records where field end with ‘ff’. Like: ‘*off’
?_filters[label]&ff

Filter Operator

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-H "Accept: application/json" \
https://api.yombo.net/api/v1/command?_filters[label]^coo&_filters[label]=on&_filteroperator=or
import requests

url = 'https://api.yombo.net/api/v1/command?_filters[label]^coo&_filters[label]=on&_filteroperator=or'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    'Accept': 'application/json',  # demo, this is the default
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/command?_filteroperator=or&_filters[label]=on&_filters[label]^coo",
    "uri_description": "List of commands, includes private commands for logged in users or gateways.",
    "doc_uri": "https://yombo.net/docs/api/commands/",
    "locator": "command",
    "locator_type": "objects",
    "command": [
      {
        "id": 1,
        "user_id": 0,
        "original_user_id": 1,
        "voice_cmd": "on",
        "machine_label": "on",
        "label": "On",
        "description": "Sends an on command",
        "public": 2,
        "status": 1,
        "created_at": "2016-12-18 12:49:47",
        "updated_at": "2016-12-18 12:49:47"
      },
      {
        "id": 15,
        "user_id": 0,
        "original_user_id": 1,
        "voice_cmd": "cool",
        "machine_label": "cool",
        "label": "Cool",
        "description": "Set a thermostat to cool.",
        "public": 2,
        "status": 1,
        "created_at": "2016-12-18 12:49:47",
        "updated_at": "2016-12-18 12:49:47"
      }
    ]
  },
  "code": 200,
  "warnings": [],
  "errors": [],
  "filters": [
    {
      "field": "label",
      "operator": "=",
      "search": "on"
    },
    {
      "field": "label",
      "operator": "^",
      "search": "coo"
    }
  ],
  "pages": {
    "total_items": 2,
    "page_limit": 750,
    "total_pages": 1,
    "page_start": 1
  },
  "message": "OK",
  "html_message": "OK"
}

Filters can be applied either “and” together, or can be “or” together. The default is “and”.

Paging

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-H "Accept: application/json" \
https://api.yombo.net/api/v1/command?_pagelimit=1&_pagestart=1
import requests

url = 'https://api.yombo.net/api/v1/command?_pagelimit=1&_pagestart=1'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    'Accept': 'application/json',  # demo, this is the default
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/command?_pagelimit=1&_pagestart=1",
    "uri_description": "List of commands, includes private commands for logged in users or gateways.",
    "doc_uri": "https://yombo.net/docs/api/commands/",
    "locator": "command",
    "locator_type": "objects",
    "command": [
      {
        "id": "gaDO5dJgo397B",
        "voice_cmd": "on",
        "machine_label": "on",
        "label": "On",
        "description": "Sends an on command",
        "public": 2,
        "status": 1,
        "created_at": 1482065387,
        "updated_at": 1482065387
      }
    ]
  },
  "code": 200,
  "warnings": [],
  "errors": [],
  "filters": [],
  "pages": {
    "total_items": 41,
    "page_limit": 1,
    "total_pages": 41,
    "page_start": 1
  },
  "message": "OK",
  "html_message": "OK"
}
Name Value Description
_pagelimit Numeric How many items per ‘page’ should be returned.
_pagestart Numeric What page to retrieve. The offset is like: (_pagelimit * (_pagestart-1))

The number of results per request is set with _pagelimit, while the offset is handled with _pagestart. For example, if there are 100 total items, items 30-40 can be retrieved with ?_pagelimit=10&_pagestart=3.

Each result set includes information about the number of items available as well as how many pages given the current page size limit. Also included is the requested page limit and start.

Responses

Yombo uses standard HTTP response codes to to signify various events. See the Error codes below for error results.

Success HTTP Codes

Error Code Meaning
200 Ok – Request processed normally.
201 Created – Content was created.

Error HTTP Codes

Error Code Meaning
400 Bad Request – Something was bad with your request.
401 Unauthorized – Bad API key or no user user authentication.
403 Forbidden – You were authenticated, but you do not have access to resource.
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access a resource with an invalid method
406 Not Acceptable – You requested a format that isn’t json, msgpack, or xml.
409 Conflict – Request could not be completed due to conflict, usually from a duplicate record or field within a record.
410 Gone – The requested item has been removed from our servers
418 I’m a teapot – You did something silly, so we laughing about it over tea and crackers.
429 Too Many Requests – You’re requesting too many cheesy poofs! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Error message codes

Unless the request was highly malformed, most responses will include error_codes which details the reason for the error. The message codes can also contain what field or specific item that cause the erro. For example, when requesting a filter on an invalid field, the error_codes will include “

Many errors will return error codes within the response.

Error Code Has
Data
Description
dns-too-soon Yes Tried to change DNS information too soon. Data contain EPOCH time when the value can be changed.
duplicate-entry Yes When a field with an existing value already exists. Usually checked on only labels and machine_labels.
not-found Yes When an item isn’t found, includes what can’t be found.
invalid-filter-operator Yes Returns when _filteroperator is invalid. See: Filter Operator
invalid-filter-comparator No The comparator within a fitler field is invalid. See: Filters
invalid-id Yes Returns the ID that is invalid.
invalid-input Yes When input isn’t formated correctly. Returns the field submitted and it’s value.
unchangeable-field Yes Returned when a field’s value is immutable.

Rate Limiting

The Yombo API has rate limits. We try to keep the limits generous, because we don’t want to interfere with awesome applications. But, you should know how they work.

Requests are limited on a windowed basis: when you first make a request, a window of time begins. During that window, you can only make a certain number of requests. A new window starts at the first request made after the end of the previous window.

Every API response includes headers about the rate limit, so your application can be proactive:

These headers are based on an emerging consensus among major websites.

If you do hit the limit, your request will fail with the status code 429 and a header telling you when to try again:

Common Fields

Machine Label

The machine_label is used inside modules and other places and allows developers to depend on the machine_label not changing. The machine_label is a generic form of the label field and only allows lower case lettering.

Public field

Many resources have a public field and is used to note if the item is private (0), public pending (1), or public (2).

The purpose of this is to allow users to create their own modules, commands, device types, etc, but if at a later time they wish for other to make use of am item, they can allow other users to.

Value Description
0 Private items can only be seen and used by the user that created it. The user can manage this item.
1 User wishs to make the item public, but it hasn’t been reviewed by Yombo staff and is treated like it’s private. User can still manage this item.
2 Public. Anyone can use this item. This item is managed by Yombo staff, but original owner is still tracked.

Status field

Many resources have a status field and is used to note if the item is disabled, enabled, or deleted. Regardless of the status field, they are returned to the gateway when requesting configurations.

Value Description
0 Item is disabled. Cannot be used by the gateway.
1 Item is enabled.
2 Item is deleted.

Miscellaneous

Performance Metics

To include performance metrics, simply include _timing to the query string. This will add response timing to the returned data. The value is in total seconds the server took to complete the request.

Request ID

Every request is assigned a request ID for tracking and logging. This ID can be included by adding _requestid to the query string. This will add the value request.id to the response. This ID can be referenced for support issues, and will be sent to gateways when requesting device commands.

Note, the request ID always returned in the response headers: X-Request-ID

Authentication

Nearly all resources require authentication. This is achieved by sending the Authorization header in your request (any resource example below for example). The format of the value is Bearer <session>, see examples below.

Login

There are two methods to login:

  1. Username & password - Returns a session to use for calls to the API and a Login Key for later logins.
  2. login_key - Login with just username and a login key from an earlier login with username & password.

The first method (username & password) is a standard login method. With this method, a session will be returned which is used in the Authentication header. A login_key is also returned, which can be used instead of a password at a later time. This allows applications to save a version of the user’s password instead of the actual password.

The second method (login_key) is nearly the same as the version, except that is uses the login_key for the username and password.

Note: The login URI is the same for both, the system will use the data fields submitted to determine which method is being used.

Username & Password

curl \
-H "x-api-key: abc123xyz789" \
-X POST -d '{"username":"yombo@example.com","password":"e?2V7XZfn@7vt&*c"}' \
https://api.yombo.net/api/v1/user/login
import requests

url = 'https://api.yombo.net/api/v1/user/login'
headers = {
    'x-api-key': 'abc123xyz789',
    }

payload = {
    "username": "yombo@example.com",
    "password": "e?2V7XZfn@7vt&*c",
    }

response = requests.post(url, headers=headers, json=payload)
{
  "response": {
    "uri": "/api/v1/user/login",
    "uri_description": "Login with username and password.",
    "doc_uri": "https://yombo.net/api/#authentication",
    "locator": "login",
    "locator_type": "object",
    "login": {
      "session": "eyJ0eXAiOiJKV1QiLCJ...",
      "login_key": "zBhODAzMDgyYjQ0NDg4Mz..."
    }
  },
  "code": 200,
  "warnings": [],
  "message": "Logged in",
  "html_message": "Logged in"
}

Login with username and password. This will return you a new session key and a new login_key. The session key will be used for requesting protected REST resources. The login_key can be used to get another session key without the need for storing the username and password anywhere.

POST request

POST https://api.yombo.net/api/v1/user/login

Data Parameters

Name Type Description
Required
username string The email address associated with the account being accessed.
password string Account password.

Login with key

curl \
-H "x-api-key: abc123xyz789" \
-X POST -d '{"login_key":"zBhODAzMDgyYjQ0NDg4Mz..."}' \
https://api.yombo.net/api/v1/user/login
import requests

url = 'https://api.yombo.net/api/v1/user/login'
headers = {
    'x-api-key': 'abc123xyz789',
    }

payload = {
    "login_key": "zBhODAzMDgyYjQ0NDg4Mz...",
    }

response = requests.post(url, headers=headers, json=payload)
{
  "response": {
    "uri": "/api/v1/user/login",
    "uri_description": "Login with login_key.",
    "doc_uri": "https://yombo.net/docs/api/#authentication",
    "locator": "login",
    "locator_type": "object",
    "login": {
      "session": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1...",
      "login_key": "zBhODAzMDgyYjQ0NDg4Mz..."
    }
  },
  "code": 200,
  "warnings": [],
  "message": "Logged in",
  "html_message": "Logged in"
}

This creates a new session, but returns the same login_key.

POST request

POST https://api.yombo.net/api/v1/user/login

Data Parameters

Name Type Description
Required
login_key string A login_key previously provided when logging in with username & pasword.
password string Account password.

Logout

There are three methods to logout:

  1. No data submitted - close current session.
  2. Submit login_key and will disable that login key, and logout any sessions created with that login_key.
  3. Username & password - This will termainate all login keys and all sessions associated with the account.

Note: The logout URI is the same for all three, the system will use the data fields submitted to determine which method is being used.

Close session

curl \
-H "x-api-key: abc123xyz789" \
-X POST -d '{}' \
https://api.yombo.net/api/v1/user/logout
import requests

url = 'https://api.yombo.net/api/v1/user/logout'
headers = {
    'x-api-key': 'abc123xyz789',
    }

payload = {
    }

response = requests.post(url, headers=headers, json=payload)
{
  "response": {
    "uri": "/api/v1/user/logout",
    "uri_description": "Logout user.",
    "doc_uri": "https://yombo.net/api/#authentication",
    "locator": "logout",
    "locator_type": "string",
    "logout": "success"
  },
  "code": 200,
  "warnings": [],
  "message": "Logout",
  "html_message": "Logout"
}

Just POST an empty payload, and this will close out the current session. The login_key can still be used to create a new session.

POST request

POST https://api.yombo.net/api/v1/user/logout

Data Parameters

None

Username & Password

curl \
-H "x-api-key: abc123xyz789" \
-X POST -d '{"username":"yombo@example.com","password":"e?2V7XZfn@7vt&*c"}' \
https://api.yombo.net/api/v1/user/logout
import requests

url = 'https://api.yombo.net/api/v1/user/logout'
headers = {
    'x-api-key': 'abc123xyz789',
    }

payload = {
    "username": "yombo@example.com",
    "password": "e?2V7XZfn@7vt&*c",
    }

response = requests.post(url, headers=headers, json=payload)
{
  "response": {
    "uri": "/api/v1/user/logout",
    "uri_description": "Logout user.",
    "doc_uri": "https://yombo.net/api/#authentication",
    "locator": "logout",
    "locator_type": "string",
    "logout": "success"
  },
  "code": 200,
  "warnings": [],
  "message": "Logout",
  "html_message": "Logout"
}

Login with username and password. This will return you a new session key and a new login_key. The session key will be used for requesting protected REST resources. The login_key can be used to get another session key without the need for storing the username and password anywhere.

POST request

POST https://api.yombo.net/api/v1/user/logout

Data Parameters

Name Type Description
Required
username string The email address associated with the account being accessed.
password string Account password.

Login Key

curl \
-H "x-api-key: abc123xyz789" \
-X POST -d '{"login_key":"zBhODAzMDgyYjQ0NDg4Mz..."}' \
https://api.yombo.net/api/v1/user/login
import requests

url = 'https://api.yombo.net/api/v1/user/login'
headers = {
    'x-api-key': 'abc123xyz789',
    }

payload = {
    "login_key": "zBhODAzMDgyYjQ0NDg4Mz...",
    }

response = requests.post(url, headers=headers, json=payload)
{
  "response": {
    "uri": "/api/v1/user/login",
    "uri_description": "Login with login_key.",
    "doc_uri": "https://yombo.net/docs/api/#authentication",
    "locator": "login",
    "locator_type": "object",
    "login": {
      "session": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1...",
      "login_key": "zBhODAzMDgyYjQ0NDg4Mz..."
    }
  },
  "code": 200,
  "warnings": [],
  "message": "Logged in",
  "html_message": "Logged in"
}

Disble the login_key and disable any session keys created with the provided login_key.

POST request

POST https://api.yombo.net/api/v1/user/logout

Data Parameters

Name Type Description
Required
login_key string A login_key previously provided when logging in with username & pasword.
password string Account password.

Core Resources

Commands

Commands are used to control Device.

GET - All Commands

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-H "Accept: application/json" \
https://api.yombo.net/api/v1/command/?_filters[label]=on
import requests

url = 'https://api.yombo.net/api/v1/command/?_filters[label]=on'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    'Accept': 'application/json',  # demo, this is the default
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/command?_filters[label]=on",
    "uri_description": "List of commands, includes private commands for logged in users or gateways.",
    "doc_uri": "https://yombo.net/api/#commands",
    "locator": "command",
    "locator_type": "objects",
    "command": [
      {
        "id": "gaDO5dJgo397B",
        "voice_cmd": "on",
        "machine_label": "on",
        "label": "On",
        "description": "Sends an on command",
        "public": 2,
        "status": 1,
        "created_at": 1482065387,
        "updated_at": 1482065387
      }
    ]
  },
  "code": 200,
  "warnings": [],
  "filters": [
    {
      "field": "label",
      "operator": "=",
      "search": "on"
    }
  ],
  "filter_operator": "and",
  "pages": {
    "total_items": 1,
    "page_limit": 750,
    "total_pages": 1,
    "page_start": 1
  },
  "message": "OK",
  "html_message": "OK"
}

This endpoint retrieves all commands.

GET Request

GET https://api.yombo.net/api/v1/command

Filters

List of available Filters:

GET - Specific Command

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
https://api.yombo.net/api/v1/command/gaDO5dJgo397B
import requests

url = 'https://api.yombo.net/api/v1/command/gaDO5dJgo397B'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/command/gaDO5dJgo397B",
    "uri_description": "Detailed information for a single command.",
    "doc_uri": "https://yombo.net/api/#commands",
    "locator": "command",
    "locator_type": "object",
    "command": {
      "id": "gaDO5dJgo397B",
      "voice_cmd": "on",
      "machine_label": "on",
      "label": "On",
      "description": "Sends an on command",
      "public": 2,
      "status": 1,
      "created_at": 1482065387,
      "updated_at": 1482065387
    }
  },
  "code": 200,
  "warnings": [],
  "message": "OK",
  "html_message": "OK"
}

This endpoint retrieves a specific command.

GET Request

GET https://api.yombo.net/api/v1/command/<command_id>

POST - New Command

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-X POST -d '{"machine_label": "printer_off", "label": "Printer Off", "description": "Turns a networked printer off.", "voice_cmd": "", "public": 0, "_idempotency_key": "33c04c69-4bca-45a0-96bf-c072fba6f9a5", "machine_label": "off", "label": "Off", "description": "Send an off command.","status": 1}' \
https://api.yombo.net/api/v1/command
import requests

url = 'https://api.yombo.net/api/v1/command'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }

payload = {
    "machine_label": "printer_off",
    "label": "Printer Off",
    "description": "Turns a networked printer off.",
    "voice_cmd": "",
    "public": 0,
    "_idempotency_key": "33c04c69-4bca-45a0-96bf-c072fba6f9a5",
    "status": 1,
    }

response = requests.post(url, headers=headers, json=payload)
{
  "response": {
    "uri": "/api/v1/command?_timing",
    "uri_description": "Create new command.",
    "doc_uri": "https://yombo.net/api/#commands",
    "locator": "command",
    "locator_type": "object",
    "command": {
      "machine_label": "printer_off",
      "label": "Printer Off",
      "description": "Turns a networked printer off.",
      "voice_cmd": "",
      "public": 0,
      "updated_at": 1491678039,
      "created_at": 1491678039,
      "id": "XpGMVE7Ao9AY3"
    }
  },
  "code": 201,
  "warnings": [],
  "message": "Created",
  "idempotency": {
    "state": false,
    "time": 1491678039
  },
  "html_message": "Created",
  "timing": {
    "duration": 0.07738
  }
}

This endpoint creates a new command.

POST Request

POST https://api.yombo.net/api/v1/command

Command POST Parameters

Name Type Description
Required
machine_name string Machine name for this comand. Once set, this cannot be changed. Can only contain: a-z and _
label string A short human friendly label for the command.
description string A detailed description of what the command does.
Optional
voice_cmd string Used by various systems to compile a possible list of voice commands for devices. This is what the person would say or type to activate the command. Usually the same as the label or machine_label
status integer Default: 1. A status for the command.
public integer Default:0. If the command should be public.

See also:

PUT - Update Command

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-X POST -d '{"label": "Turn Printer Off", "description": "Turns a networked printer off.", "voice_cmd": "", "public": 0, "machine_label": "off", "label": "Off", "description": "Send an off command.","status": 1}' \
https://api.yombo.net/api/v1/command/XpGMVE7Ao9AY3
import requests

url = 'https://api.yombo.net/api/v1/command/XpGMVE7Ao9AY3'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }

payload = {
    "machine_label": "printer_off",
    "label": "Turn Printer Off",
    "description": "Turns a networked printer off.",
    "voice_cmd": "",
    "public": 0,
    "status": 1,
    }

response = requests.post(url, headers=headers, json=payload)
{
  "response": {
    "uri": "/api/v1/command/XpGMVE7Ao9AY3",
    "uri_description": "Update (patch) command.",
    "doc_uri": "https://yombo.net/api/#commands",
    "locator": "command",
    "locator_type": "object",
    "command": {
      "id": "XpGMVE7Ao9AY3",
      "voice_cmd": "",
      "machine_label": "printer_off",
      "label": "Turn Printer Off",
      "description": "Turns a networked printer off.",
      "public": 0,
      "status": 2,
      "created_at": 1491678039,
      "updated_at": 1491679497
    }
  },
  "code": 200,
  "warnings": [],
  "idempotency": {
    "state": false,
    "time": 1491679584
  },
  "message": "OK",
  "html_message": "OK"
}

This endpoint updates all attributes of a command. To update only one or more, see PATCH Update Command. Same requirements as POST - New Command, except use PUT verb instead of POST.

PUT Request

PUT https://api.yombo.net/api/v1/command/<command_id>

PATCH - Update Command

Allows updating one or mote attributes. Same as PUT - Update Command. However, use thePATCH verb instead of PUT and only submit attributes that need to be changed.

DELETE - Command

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-X DELETE \
https://api.yombo.net/api/v1/command/XpGMVE7Ao9AY3
import requests

url = 'https://api.yombo.net/api/v1/command/XpGMVE7Ao9AY3'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }

response = requests.delete(url, headers=headers)
{
  "response": {
    "uri": "/api/v1/command/XpGMVE7Ao9AY3",
    "uri_description": "Delete a command.",
    "doc_uri": "https://yombo.net/api/#commands",
    "locator": "command",
    "locator_type": "string",
    "command": "Deleted"
  },
  "code": 200,
  "warnings": [],
  "message": "Deleted",
  "html_message": "Deleted"
}

Deletes a command.

DELETE Request

DELETE https://api.yombo.net/api/v1/command/<command_id>

Devices

Devices are attached to gateways and are the end points that the user wants to automate with and control with commands.

GET - All Devices

# lets limit to 1
curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
https://api.yombo.net/api/v1/device?_pagelimit=1
import requests

url = 'https://api.yombo.net/api/v1/device?_pagelimit=1'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/device?_pagelimit=1",
    "uri_description": "List of devices.",
    "doc_uri": "https://yombo.net/api/#devices",
    "locator": "device",
    "locator_type": "objects",
    "device": [
      {
        "id": "dAlQ6aO7rBxN9Gj4",
        "gateway_id": "Q3kBOJqbkrzY7F68",
        "device_type_id": "dRx02WzL",
        "label": "Garage Door",
        "description": "The garage door",
        "notes": null,
        "voice_cmd": "garage door [open, close]",
        "voice_cmd_order": "both",
        "voice_cmd_src": "manual",
        "pin_code": "0",
        "pin_required": 0,
        "pin_timeout": 0,
        "statistic_label": null,
        "energy_type": null,
        "energy_tracker_source": null,
        "energy_tracker_device": null,
        "energy_map": null,
        "status": 1,
        "created_at": 1482065388,
        "updated_at": 1482065388,
        "variable_data": []
      }
    ]
  },
  "code": 200,
  "warnings": [],
  "pages": {
    "total_items": 2,
    "page_limit": 1,
    "total_pages": 2,
    "page_start": 1
  },
  "message": "OK",
  "html_message": "OK"
}

This endpoint retrieves all devices.

GET Request

GET https://api.yombo.net/api/v1/device

Filters

List of available Filters:

GET - Specific Device

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
https://api.yombo.net/api/v1/device/dAlQ6aO7rBxN9Gj4
import requests

url = 'https://api.yombo.net/api/v1/device/dAlQ6aO7rBxN9Gj4'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/device/dAlQ6aO7rBxN9Gj4",
    "uri_description": "Detailed information for a single device.",
    "doc_uri": "https://yombo.net/docs/api/devices/",
    "locator": "device",
    "locator_type": "object",
    "device": {
      "id": "dAlQ6aO7rBxN9Gj4",
      "gateway_id": "Q3kBOJqbkrzY7F68",
      "device_type_id": "dRx02WzL",
      "label": "Garage Door",
      "description": "The garage door",
      "notes": null,
      "voice_cmd": "garage door [open, close]",
      "voice_cmd_order": "both",
      "voice_cmd_src": "manual",
      "pin_code": "0",
      "pin_required": 0,
      "pin_timeout": 0,
      "statistic_label": null,
      "energy_type": null,
      "energy_tracker_source": null,
      "energy_tracker_device": null,
      "energy_map": null,
      "status": 1,
      "created_at": 1482065388,
      "updated_at": 1482065388,
      "variable_data": []
    }
  },
  "code": 200,
  "warnings": [],
  "message": "OK",
  "html_message": "OK"
}

This endpoint retrieves a specific device.

GET Request

GET https://api.yombo.net/api/v1/device/<device_id>

GET - Control a device

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
https://api.yombo.net/api/v1/device/M9WA2VJNA3bydo7G/61v9WdKgdJY8l
import requests

url = 'https://api.yombo.net/api/v1/device/M9WA2VJNA3bydo7G/61v9WdKgdJY8l'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/device/M9WA2VJNA3bydo7G/61v9WdKgdJY8l",
    "uri_description": "Send a device command.",
    "doc_uri": "https://yombo.net/api/#devices",
    "locator": "device",
    "locator_type": "string",
    "device": "sent"
  },
  "code": 200,
  "warnings": [],
  "message": "OK",
  "html_message": "OK"
}

Sends a command to a device. Must have the device id and command id to complete this.

Note: Currently, command’s cannot have input values, feature coming soon.

GET Request

GET https://api.yombo.net/api/v1/device/<device_id>/<command_id>

Query String Parameters

POST - New Device

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-X POST -d '{"gateway_id": "Q3kBOJqbkrzY7F68", "device_type_id": "dRx02WzL", "label": "Pretend Garage Door", "description": "An example garage door.","notes": "Extra area for notes.", "status": 1, "pin_required": 0, "pin_timeout": 90}' \
https://api.yombo.net/api/v1/device
import requests

url = 'https://api.yombo.net/api/v1/device'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }

payload = {
    "gateway_id": "Q3kBOJqbkrzY7F68",
    "device_type_id": "dRx02WzL",
    "label": "Pretend Garage Door",
    "description": "An example garage door.",
    "notes": "Extra area for notes.",
    "status": 1,
    "pin_required": 0,
    "pin_timeout": 90,
    }

response = requests.post(url, headers=headers, json=payload)
{
  "response": {
    "uri": "/api/v1/device",
    "uri_description": "Create new device.",
    "doc_uri": "https://yombo.net/api/#devices",
    "locator": "device",
    "locator_type": "object",
    "device": {
      "gateway_id": "Q3kBOJqbkrzY7F68",
      "device_type_id": "dRx02WzL",
      "label": "Pretend Garage Door",
      "description": "An example garage door.",
      "notes": "Extra area for notes.",
      "status": 1,
      "pin_required": "0",
      "updated_at": 1491682732,
      "created_at": 1491682732,
      "id": "2LveEn3q6Jm4V0wj"
    }
  },
  "code": 201,
  "warnings": [],
  "message": "Created",
  "html_message": "Created"
}

This endpoint creates a new device.

POST Request

POST https://api.yombo.net/api/v1/device

Device POST Parameters

Name Type Description
Required
gateway_id string Gateway ID to assign device to.
device_type_id string Device Type ID to assign device to.
pin_required integer 0 if not access code required, 1 if it does.
label string A short human friendly label for the device.
description string A description of what the device does.
notes string A detailed notesfor the device.
Optional
pin_code string Access code for the device. **Note: This is required if `pin_required` is to 1./td>
pin_timeout integer How long an application can remember the pin code for the user after the user enters it. **Note: This is required if `pin_required` is to 1./td>
voice_cmd string To be documented later. Leave blank for now.
voice_cmd_order string To be documented later. Set to `both` for now.
voice_cmd_src string To be documented later. Set to `auto` for now.
status integer The status of the module. Default=1. Possible values: 0=disabled, 1=enabled, 2=mark for deletion

PUT - Update Device

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-X PUT -d '{"gateway_id": "Q3kBOJqbkrzY7F68", "device_type_id": "dRx02WzL", "label": "Pretend Garage Door 2", "description": "An example garage door 2.","notes": "Extra area for notes 2.", "status": 1, "pin_required": 0, "pin_timeout": 90}' \
https://api.yombo.net/api/v1/device
import requests

url = 'https://api.yombo.net/api/v1/device'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }

payload = {
    "gateway_id": "Q3kBOJqbkrzY7F68",
    "device_type_id": "dRx02WzL",
    "label": "Pretend Garage Door 2",
    "description": "An example garage door 2.",
    "notes": "Extra area for notes 2.",
    "status": 1,
    "pin_required": 0,
    "pin_timeout": 90
    }

response = requests.put(url, headers=headers, json=payload)
{
  "response": {
    "uri": "/api/v1/device/2LveEn3q6Jm4V0wj",
    "uri_description": "Update (put) device.",
    "doc_uri": "https://yombo.net/api/#devices",
    "locator": "device",
    "locator_type": "object",
    "device": {
      "id": "2LveEn3q6Jm4V0wj",
      "gateway_id": "Q3kBOJqbkrzY7F68",
      "device_type_id": "dRx02WzL",
      "label": "Pretend Garage Door 2",
      "description": "An example garage door 2.",
      "notes": "Extra area for notes 2.",
      "voice_cmd": null,
      "voice_cmd_order": null,
      "voice_cmd_src": null,
      "pin_code": null,
      "pin_required": "0",
      "pin_timeout": null,
      "statistic_label": null,
      "energy_type": null,
      "energy_tracker_source": null,
      "energy_tracker_device": null,
      "energy_map": null,
      "status": 1,
      "created_at": 1491682732,
      "updated_at": 1491685923
    }
  },
  "code": 200,
  "warnings": [],
  "message": "OK",
  "html_message": "OK"
}

This endpoint updates all attributes of a device. To update only one or more, see PATCH Update Device. Same requirements as POST - New Device, except use PUT verb instead of POST.

PUT Request

PUT https://api.yombo.net/api/v1/device/<device_id>

PATCH - Update Device

Allows updating one or more attributes. Same as PUT - Update Device. However, use thePATCH verb instead of PUT and only submit attributes that need to be changed.

Delete - Device

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-X DELETE \
https://api.yombo.net/api/v1/device/2LveEn3q6Jm4V0wj
import requests

url = 'https://api.yombo.net/api/v1/device/2LveEn3q6Jm4V0wj'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }

response = requests.delete(url, headers=headers)
{
  "response": {
    "uri": "/api/v1/device/2LveEn3q6Jm4V0wj",
    "uri_description": "Delete a device.",
    "doc_uri": "https://yombo.net/api/#devices",
    "locator": "device",
    "locator_type": "string",
    "device": "Deleted"
  },
  "code": 200,
  "warnings": [],
  "message": "Deleted",
  "html_message": "Deleted"
}

Deletes a command.

DELETE Request

DELETE https://api.yombo.net/api/v1/device/<command_id>

Device Types (DT)

Each device is defined by it what it can do. For example, lamp modules can be turned on, off, set to a brightness level, or a few other types of commands. A device types define what commands can be used for a certain device as well as what device type a module can manage and accept commands for.

Device types can have attached one or more variable groups, each of which can have variable fields.

GET - All Device Types

# lets limit to 1
curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
https://api.yombo.net/api/v1//api/v1/device_type?_pagelimit=1&_pagestart=2
import requests

url = 'https://api.yombo.net/api/v1/device_type?_pagelimit=1&_pagestart=2'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/device_type?_pagelimit=1&_pagestart=2",
    "uri_description": "List of device types. ",
    "doc_uri": "https://yombo.net/docs/api/devicetypes/",
    "locator": "device_type",
    "locator_type": "objects",
    "device_type": [
      {
        "id": "kEmK2WM0",
        "category_id": "B4gYGqXG",
        "machine_label": "x10_lamp",
        "label": "X10 Lamp",
        "description": "An X10 lamp module or device.",
        "public": 2,
        "status": 1,
        "created_at": 1482065387,
        "updated_at": 1482065387,
        "variable_groups": [
          {
            "id": "a4vD0J4e7RyE",
            "relation_id": "kEmK2WM0",
            "relation_type": "device_type",
            "group_machine_label": "x10_address",
            "group_label": "X10 Address 1",
            "group_description": "X10 Address information",
            "group_weight": 1,
            "status": 1,
            "created_at": 1482065388,
            "updated_at": 1482065388
          }
        ],
        "variable_fields": [
          {
            "id": "WoBnydWjq7KMk",
            "group_id": "a4vD0J4e7RyE",
            "field_machine_label": "house",
            "field_label": "House Code",
            "field_description": "House code A-P.",
            "field_weight": 0,
            "value_required": 0,
            "value_max": 0,
            "value_min": 0,
            "encryption": "nosuggestion",
            "value_casing": "none",
            "input_type_id": "3VNoxrdz",
            "default_value": "",
            "help_text": "The house code of the X10 module, in the range between A and P.",
            "multiple": false,
            "created_at": 1482065388,
            "updated_at": 1482065389
          },
          {
            "id": "WE4aDdbyqAQY9",
            "group_id": "a4vD0J4e7RyE",
            "field_machine_label": "unit_code",
            "field_label": "Unit Code",
            "field_description": "X10 unit code, 1-16",
            "field_weight": 1,
            "value_required": 0,
            "value_max": 0,
            "value_min": 0,
            "encryption": "nosuggestion",
            "value_casing": "none",
            "input_type_id": "zjNLlNB8",
            "default_value": "",
            "help_text": "",
            "multiple": false,
            "created_at": 1482065388,
            "updated_at": 1482065389
          }
        ]
      }
    ]
  },
  "code": 200,
  "warnings": [],
  "pages": {
    "total_items": 31,
    "page_limit": 1,
    "total_pages": 31,
    "page_start": 2
  },
  "message": "OK",
  "html_message": "OK"
}

This endpoint returns all device types (unless narrowed down with a filter or page limit).

GET Request

GET https://api.yombo.net/api/v1/device_type

Filters

List of available Filters:

GET - Specific Device Type

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
https://api.yombo.net/api/v1/device_type/OgxDPx14
import requests

url = 'https://api.yombo.net/api/v1/device_type/OgxDPx14'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/device_type/OgxDPx14",
    "uri_description": "Detailed information for a single device type.",
    "doc_uri": "https://yombo.net/api/#devicetypes",
    "locator": "device_type",
    "locator_type": "object",
    "device_type": {
      "id": "OgxDPx14",
      "category_id": "0ORz8kyD",
      "machine_label": "hv_output_port",
      "label": "Homevision Output Port",
      "description": "A homevision output put.",
      "public": 1,
      "status": 1,
      "created_at": 1482065387,
      "updated_at": 1482065387,
      "variable_groups": [
        {
          "id": "Z9L60xwj5b8z",
          "relation_id": "OgxDPx14",
          "relation_type": "device_type",
          "group_machine_label": "port_info",
          "group_label": "Port Information",
          "group_description": "Homevision port information.",
          "group_weight": 0,
          "status": 1,
          "created_at": 1491294077,
          "updated_at": 1491294077
        }
      ],
      "variable_fields": [
        {
          "id": "1GerZqBnqpkJM",
          "group_id": "Z9L60xwj5b8z",
          "field_machine_label": "port",
          "field_label": "Port",
          "field_description": "The port number to control.",
          "field_weight": 0,
          "value_required": 0,
          "value_max": 15,
          "value_min": 0,
          "encryption": "nosuggestion",
          "value_casing": "none",
          "input_type_id": "8O6DyPDK",
          "default_value": "",
          "help_text": "",
          "multiple": false,
          "created_at": 1491294132,
          "updated_at": 1491294132
        }
      ]
    }
  },
  "code": 200,
  "warnings": [],
  "message": "OK",
  "html_message": "OK"
}

This endpoint retrieves a specific device.

GET Request

GET https://api.yombo.net/api/v1/device_type/<device_type_id>

POST - New Device Type

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-X POST -d '{"label": "Test Device Type", "machine_label": "test_device_type", "description": "This is a test device type.","category_id": "Boyowlym",}' \


https://api.yombo.net/api/v1/device_type
import requests

url = 'https://api.yombo.net/api/v1/device_type'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }

payload = {
    "label": "Test Device Type",
    "machine_label": "test_device_type", 
    "description": "This is a test device type.",
    "category_id": "Boyowlym",
    }

response = requests.post(url, headers=headers, json=payload)
{
  "response": {
    "uri": "/api/v1/device_type",
    "uri_description": "Create new device type.",
    "doc_uri": "https://yombo.net/api/#devicetypes",
    "locator": "device_type",
    "locator_type": "object",
    "device_type": {
      "label": "Test Device Type",
      "machine_label": "test_device_type",
      "description": "This is a test device type.",
      "category_id": "Boyowlym",
      "updated_at": 1491861736,
      "created_at": 1491861736,
      "id": "Oyxqz83X"
    }
  },
  "code": 201,
  "warnings": [],
  "message": "Created",
  "html_message": "Created"
}

This endpoint creates a new device.

POST Request

POST https://api.yombo.net/api/v1/device

Device POST Parameters

Name Type Description
Required
machine_label string An ummutable label for developers to use. A computer version of the `label`.
label string A short human friendly label for the device.
description string A description of the device type.
category_id string Categorize the device type. Must be a ‘device_type’ category.
Optional
status integer Default: 1. A status for the device type.
public integer Default:0. If the device type should be public.

See also:

PUT - Update Device

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-X PUT -d '{"label": "Test Device Type", "description": "This is a test device type.","category_id": "Boyowlym",}' \
https://api.yombo.net/api/v1/device_type/Oyxqz83X
import requests

url = 'https://api.yombo.net/api/v1/device_type/Oyxqz83X'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }

payload = {
    "label": "Test Device Type",
    "machine_label": "test_device_type", 
    "description": "This is a test device type.",
    "category_id": "Boyowlym",
    }

response = requests.post(url, headers=headers, json=payload)
{
  "response": {
    "uri": "/api/v1/device_type/Oyxqz83X",
    "uri_description": "Update (put) device type.",
    "doc_uri": "https://yombo.net/api/#devicetypes",
    "locator": "device_type",
    "locator_type": "object",
    "device_type": {
      "id": "Oyxqz83X",
      "category_id": "Boyowlym",
      "machine_label": "test_device_type",
      "label": "Test Device Type",
      "description": "This is a test device type.",
      "public": 0,
      "status": 1,
      "created_at": 1491861736,
      "updated_at": 1491861736
    }
  },
  "code": 200,
  "warnings": [],
  "message": "OK",
  "html_message": "OK"
}

This endpoint updates all attributes of a device. To update only one or more, see PATCH Update Device. Same requirements as POST - New Device, except use PUT verb instead of POST.

PUT Request

PUT https://api.yombo.net/api/v1/device/<device_id>

PATCH - Update Device

Allows updating one or more attributes. Same as PUT - Update Device. However, use thePATCH verb instead of PUT and only submit attributes that need to be changed.

Delete - Device

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-X DELETE \
https://api.yombo.net/api/v1/device_type/Oyxqz83X
import requests

url = 'https://api.yombo.net/api/v1/device_type/Oyxqz83X'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }

response = requests.delete(url, headers=headers)
{
  "response": {
    "uri": "/api/v1/device_type/Oyxqz83X",
    "uri_description": "Delete a device type.",
    "doc_uri": "https://yombo.net/api/#devicetypes",
    "locator": "device_type",
    "locator_type": "string",
    "device_type": "Deleted"
  },
  "code": 200,
  "warnings": [],
  "message": "Deleted",
  "html_message": "Deleted"
}

Deletes a device type.

DELETE Request

DELETE https://api.yombo.net/api/v1/device/<device_type_id>

DT Commands

Device Type Command

Each device type can have it’s own list of commands. For example, an appliance module or relay can only turn on and off, and will have those two commands associated with that device type.

DT Command Inputs

Device Type Command Inputs

Each device type and it’s matching command may accept user inputs. Matching an input to a device type command allows the system to validate the input for a given command request.

Gateways (GW)

Gateways are computers (or small form factor devices) where Yombo Gateway is installed.

GET - All Gateways

# lets limit to 1
curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
https://api.yombo.net/api/v1/gateway?_pagelimit=1
import requests

url = 'https://api.yombo.net/api/v1/gateway?_pagelimit=1'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/gateway?_pagelimit=1",
    "uri_description": "List of gateways.",
    "doc_uri": "https://yombo.net/docs/api/gateways/",
    "locator": "gateway",
    "locator_type": "objects",
    "gateway": [
      {
        "id": "wbay0o1O8qGK7F68",
        "hash_short": "$2y$10$H8/NGBv0PR2EHaMc4V4JtuR2IkfGPCF5eEZsWQqt.6Oc4KP3ACpci",
        "machine_label": "henry",
        "label": "henry",
        "description": "",
        "last_connect": null,
        "status": 0,
        "created_at": 1489816839,
        "updated_at": 1491437388
      }
    ]
  },
  "code": 200,
  "warnings": [],
  "filters": [
    {
      "field": "label",
      "operator": "=",
      "search": "Shed"
    }
  ],
  "filter_operator": "and",
  "pages": {
    "total_items": 1,
    "page_limit": 1,
    "total_pages": 1,
    "page_start": 1
  },
  "message": "OK",
  "html_message": "OK"
}

This endpoint retrieves all gateways.

GET Request

GET https://api.yombo.net/api/v1/gateway

Filters

List of available Filters:

GET - Specific Gateway

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-H "Accept: application/json" \
https://api.yombo.net/api/v1/gateway/wbay0o1O8qGK7F68
import requests

url = 'https://api.yombo.net/api/v1/gateway/wbay0o1O8qGK7F68'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    'Accept': 'application/json',  # demo, this is the default
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/gateway/wbay0o1O8qGK7F68",
    "uri_description": "Detailed information for a single gateway.",
    "doc_uri": "https://yombo.net/docs/api/gateways/",
    "locator": "gateway",
    "locator_type": "object",
    "gateway": {
      "id": "wbay0o1O8qGK7F68",
      "hash_short": "$2y$10$H8/NGBv0PR2EHaMc4V4JtuR2IkfGPCF5eEZsWQqt.6Oc4KP3ACpci",
      "machine_label": "henry",
      "label": "henry",
      "description": "",
      "last_connect": null,
      "status": 0,
      "created_at": 1489816839,
      "updated_at": 1491437388
    }
  },
  "code": 200,
  "warnings": [],
  "message": "OK",
  "html_message": "OK"
}

This endpoint retrieves a specific gateway.

GET Request

GET https://api.yombo.net/api/v1/gateway/<gateway_id>

POST - New Gateway

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-X POST -d '{"label": "Shed", "machine_label": "Shed", "description": "Example."}' \
https://api.yombo.net/api/v1/gateway
import requests

url = 'https://api.yombo.net/api/v1/gateway'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }

payload = {
"label": "Shed",
"machine_label": "Shed",
"description": "Example.",
    }

response = requests.post(url, headers=headers, json=payload)
{
  "response": {
    "uri": "/api/v1/gateway",
    "uri_description": "Create new gateway.",
    "doc_uri": "https://yombo.net/docs/api/gateways/",
    "locator": "gateway",
    "locator_type": "object",
    "gateway": {
      "label": "Shed",
      "machine_label": "shed",
      "description": "Example.",
      "updated_at": 1491862823,
      "created_at": 1491862823,
      "id": "P9Zpzyq7kqkx7F68",
      "hash": "5XYBeiU9BhF3mAMbmcQLPR7TF63j9XRj1SYxDzHc",
      "uuid": "8sofHkTRS3nReTWe"
    }
  },
  "code": 201,
  "warnings": [],
  "message": "Created",
  "html_message": "Created"
}

This endpoint creates a new gateway.

POST Request

POST https://api.yombo.net/api/v1/gateway

Gateway POST Parameters

Name Type Description
Required
machine_label string An ummutable label for the gateway.
label string A short human friendly label for the gateway.
description string A description of for the gateway.
Optional
status integer A status for the gateway.

See also:

PUT - Update Gateway

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-X PUT -d '{"label": "Shed2", "description": "Example2."}' \
https://api.yombo.net/api/v1/gateway/P9Zpzyq7kqkx7F68
import requests

url = 'https://api.yombo.net/api/v1/gateway/P9Zpzyq7kqkx7F68'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }

payload = {
"label": "Shed2",
"description": "Example.2",
    }

response = requests.post(url, headers=headers, json=payload)
{
  "response": {
    "uri": "/api/v1/gateway/P9Zpzyq7kqkx7F68",
    "uri_description": "Update gateway.",
    "doc_uri": "https://yombo.net/docs/api/gateways/",
    "locator": "gateway",
    "locator_type": "object",
    "gateway": {
      "id": "P9Zpzyq7kqkx7F68",
      "hash_short": "$2y$10$SGGxFdQsLa2hGhYSX94EV.p4N0hAfvp2WHqyL87G2OLEWG.lAWUYC",
      "machine_label": "shed",
      "label": "Shed2",
      "description": "Example.2",
      "last_connect": null,
      "status": 0,
      "created_at": 1491862823,
      "updated_at": 1491863511
    }
  },
  "code": 200,
  "warnings": [],
  "message": "Updated",
  "html_message": "Updated"
}

This endpoint updates all attributes of a gateway. To update only one or more, see PATCH Update Gateway. Same requirements as POST - New Device, except use PUT verb instead of POST.

PUT Request

PUT https://api.yombo.net/api/v1/gateway/<gateway_id>

PATCH - Update Gateway

Allows updating one or more attributes. Same as PUT - Update Gateway. However, use thePATCH verb instead of PUT and only submit attributes that need to be changed.

Delete - Gateway

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-H "Accept: application/json" \
-X DELETE \
https://api.yombo.net/api/v1/gateway/P9Zpzyq7kqkx7F68
import requests

url = 'https://api.yombo.net/api/v1/gateway/P9Zpzyq7kqkx7F68'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }

response = requests.delete(url, headers=headers)
{
  "response": {
    "uri": "/api/v1/gateway/P9Zpzyq7kqkx7F68",
    "uri_description": "Gateway deleted",
    "doc_uri": "https://yombo.net/api/#gateways-gw",
    "locator": "gateway",
    "locator_type": "string",
    "gateway": "Deleted"
  },
  "code": 200,
  "warnings": [],
  "message": "Deleted",
  "html_message": "Deleted"
}

Deletes a gateway.

DELETE Request

DELETE https://api.yombo.net/api/v1/gateway/<gateway_id>

GW Commands

# lets limit to 1
curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
https://api.yombo.net/api/v1/gateway/Q3kBOJqbkrzY7F68/command
import requests

url = 'https://api.yombo.net/api/v1/gateway/Q3kBOJqbkrzY7F68/command'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/gateway/Q3kBOJqbkrzY7F68/command",
    "uri_description": "List of possible commands for a gateway.",
    "doc_uri": "https://yombo.net/api/#gateways-gw",
    "locator": "gateway_command",
    "locator_type": "objects",
    "gateway_command": [
      {
        "id": "gaDO5dJgo397B",
        "voice_cmd": "on",
        "machine_label": "on",
        "label": "On",
        "description": "Sends an on command",
        "public": 2,
        "status": 1,
        "created_at": 1482065387,
        "updated_at": 1482065387,
        "always_load": 1
      },
      {
        "id": "bZ73EoBYd2e5w",
        "voice_cmd": "off",
        "machine_label": "off",
        "label": "Off",
        "description": "Sends an off command",
        "public": 2,
        "status": 1,
        "created_at": 1482065387,
        "updated_at": 1482065387,
        "always_load": 1
      },
      {
        "id": "wEzLbdPqoQYga",
        "voice_cmd": "close",
        "machine_label": "close",
        "label": "Close",
        "description": "Sends a close command",
        "public": 2,
        "status": 1,
        "created_at": 1482065387,
        "updated_at": 1482065387,
        "always_load": 1
      },
      {
        "id": "61v9WdKgdJY8l",
        "voice_cmd": "open",
        "machine_label": "open",
        "label": "Open",
        "description": "Sends an open command",
        "public": 2,
        "status": 1,
        "created_at": 1482065387,
        "updated_at": 1482065387,
        "always_load": 1
      },
      {
        "id": "xXpGMVEAV9AY3",
        "voice_cmd": "dim",
        "machine_label": "dim",
        "label": "Dim",
        "description": "Sends a dim command",
        "public": 2,
        "status": 1,
        "created_at": 1482065387,
        "updated_at": 1482065387,
        "always_load": 1
      },
      {
        "id": "vQ6ExoZAdaDOl",
        "voice_cmd": "brighten",
        "machine_label": "brighten",
        "label": "Brighten",
        "description": "Sends a brighten command",
        "public": 2,
        "status": 1,
        "created_at": 1482065387,
        "updated_at": 1482065387,
        "always_load": 1
      }
    ]
  },
  "code": 200,
  "warnings": [],
  "message": "OK",
  "html_message": "OK"
}

A read only resource. Page limit and filtering is not available for this resource.

Get a list of all commands a specific gateway should know about. This performs all the logic based on what modules are installed.

GET Request

GET https://api.yombo.net/api/v1/gateway/<gateway_id>/command

GW Device Types

Results have been manually trimmed due to length.

# lets limit to 1
curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
https://api.yombo.net/api/v1/gateway/Q3kBOJqbkrzY7F68/device_type
import requests

url = 'https://api.yombo.net/api/v1/gateway/Q3kBOJqbkrzY7F68/device_type'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/gateway/Q3kBOJqbkrzY7F68/device_type",
    "uri_description": "List of possible device types for a gateway.",
    "doc_uri": "https://yombo.net/api/#gateways-gw",
    "locator": "gateway_device_type",
    "locator_type": "objects",
    "gateway_device_type": [
      {
        "id": "kEmK2WM0",
        "category_id": "B4gYGqXG",
        "machine_label": "x10_lamp",
        "label": "X10 Lamp",
        "description": "An X10 lamp module or device.",
        "public": 2,
        "status": 1,
        "created_at": 1482065387,
        "updated_at": 1482065387,
        "variable_groups": [
          {
            "id": "a4vD0J4e7RyE",
            "relation_id": "kEmK2WM0",
            "relation_type": "device_type",
            "group_machine_label": "x10_address",
            "group_label": "X10 Address 1",
            "group_description": "X10 Address information",
            "group_weight": 1,
            "status": 1,
            "created_at": 1482065388,
            "updated_at": 1482065388
          }
        ],
        "variable_fields": [
          {
            "id": "WoBnydWjq7KMk",
            "group_id": "a4vD0J4e7RyE",
            "field_machine_label": "house",
            "field_label": "House Code",
            "field_description": "House code A-P.",
            "field_weight": 0,
            "value_required": 0,
            "value_max": 0,
            "value_min": 0,
            "encryption": "nosuggestion",
            "value_casing": "none",
            "input_type_id": "3VNoxrdz",
            "default_value": "",
            "help_text": "The house code of the X10 module, in the range between A and P.",
            "multiple": false,
            "created_at": 1482065388,
            "updated_at": 1482065389
          },
          {
            "id": "WE4aDdbyqAQY9",
            "group_id": "a4vD0J4e7RyE",
            "field_machine_label": "unit_code",
            "field_label": "Unit Code",
            "field_description": "X10 unit code, 1-16",
            "field_weight": 1,
            "value_required": 0,
            "value_max": 0,
            "value_min": 0,
            "encryption": "nosuggestion",
            "value_casing": "none",
            "input_type_id": "zjNLlNB8",
            "default_value": "",
            "help_text": "",
            "multiple": false,
            "created_at": 1482065388,
            "updated_at": 1482065389
          }
        ],
        "always_load": 1
      }
    ]
  },
  "code": 200,
  "warnings": [],
  "message": "OK",
  "html_message": "OK"
}

Gateway Device Types

A read only resource. Page limit and filtering is not available for this resource.

Get a list of all device types a specific gateway should know about. This performs all the logic based on what modules are installed.

GET Request

GET https://api.yombo.net/api/v1/gateway/<gateway_id>/device_type

GW DT Commands

Results have been manually trimmed due to length.

# lets limit to 1
curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
https://api.yombo.net/api/v1/gateway/Q3kBOJqbkrzY7F68/device_type_command
import requests

url = 'https://api.yombo.net/api/v1/gateway/Q3kBOJqbkrzY7F68/device_type_command'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/gateway/Q3kBOJqbkrzY7F68/device_type_command",
    "uri_description": "List of possible device type commands for a gateway.",
    "doc_uri": "https://yombo.net/api/#gateways-gw",
    "locator": "gateway_device_type_command",
    "locator_type": "integer",
    "gateway_device_type_command": [
      {
        "id": "VM7OpvK3",
        "device_type_id": "kEmK2WM0",
        "command_id": "gaDO5dJgo397B",
        "created_at": 1482065387
      },
      {
        "id": "wO2al8ay",
        "device_type_id": "kEmK2WM0",
        "command_id": "bZ73EoBYd2e5w",
        "created_at": 1482065387
      },
      {
        "id": "bJvNjvr3",
        "device_type_id": "kEmK2WM0",
        "command_id": "xXpGMVEAV9AY3",
        "created_at": 1482065387
      }
    ]
  },
  "code": 200,
  "warnings": [],
  "message": "OK",
  "html_message": "OK"
}

Gateway Device Type Commands

A read only resource. Page limit and filtering is not available for this resource.

Get a list of device types and available commands for a specific gateway should know about. This performs all the logic based on what modules are installed.

GET Request

GET https://api.yombo.net/api/v1/gateway/<gateway_id>/device_type_command

GW DNS

Gateway domain name is configured through this resource. The actually IP address setting is managed by the gateway itself when it communciates with the backend server.

GET - Retrieve Gateway Domain

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
https://api.yombo.net/api/v1/gateway/wbay0o1O8qGK7F68/dns_name
import requests

url = 'https://api.yombo.net/api/v1/gateway/wbay0o1O8qGK7F68/dns_name'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/gateway/wbay0o1O8qGK7F68/dns_name",
    "uri_description": "View gateway DNS Name information.",
    "doc_uri": "https://yombo.net/docs/api/dns/",
    "locator": "dns_name",
    "locator_type": "object",
    "dns_name": {
      "gateway_id": "wbay0o1O8qGK6D34",
      "dns_name": "henry",
      "dns_domain_id": "bp2XDP",
      "dns_domain": "yombo.me",
      "allow_change_at": 1492466336,
      "fqdn": "example.yombo.me"
    }
  },
  "code": 200,
  "warnings": [],
  "message": "OK",
  "html_message": "OK"
}

This endpoint retrieves domain name information for a gateway.

GET Request

GET https://api.yombo.net/api/v1/gateway/<gateway_id>/dns_name

POST - New or update Gateway Domain

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-X POST -d '{"dns_name": "example2", "dns_domain_id": "1DVoLx" }' \
https://api.yombo.net/api/v1/gateway/wbay0o1O8qGK7F68/dns_name
import requests

url = 'https://api.yombo.net/api/v1/gateway/wbay0o1O8qGK7F68/dns_name'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }

payload = {
    "dns_name": "example2",
    "dns_domain_id": "1DVoLx",
    }

response = requests.post(url, headers=headers, json=payload)
{
  "response": {
    "uri": "/api/v1/gateway/MxJn521RedOK3EYl/dns_name",
    "uri_description": "Create new gateway dns name.",
    "doc_uri": "https://yombo.net/docs/api/dns/",
    "locator": "dns_name",
    "locator_type": "object",
    "dns_name": {
      "gateway_id": "MxJn521RedOK3EYl",
      "dns_name": "example2",
      "dns_domain_id": "1DVoLx",
      "dns_domain": "homelink.one",
      "allow_change_at": 1494461179,
      "fqdn": "example2.homelink.one"
    }
  },
  "code": 201,
  "warnings": [],
  "message": "Created",
  "html_message": "Created"
}

This endpoint created or updates a DNS domain name. This function is also mapped to the PATCH http verb for compatibility.

POST Request

POST https://api.yombo.net/api/v1/gateway/<gateway_id>/dns_name

Command POST Parameters

Name Type Description
Required
dns_domain_id string The domain ID, retrieved from DNS Domains
dns_name string The desired 3rd level domain. Can only contain letters and numbers, must have at least one letter.

GW Modules

Gateways use modules to extend it’s capabilites. Module installation is managed with this resource.

GET - All Gateway Modules

# lets limit to 1
curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
https://api.yombo.net/api/v1/gateway/wbay0o1O8qGK7F68/module?_pagelimit=1
import requests

url = 'https://api.yombo.net/api/v1/gateway/wbay0o1O8qGK7F68/module?_pagelimit=1'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/gateway/wbay0o1O8qGK7F68/module?_pagelimit=1",
    "uri_description": "List of modules attached to a gateway.",
    "doc_uri": "https://yombo.net/api/#gw-modules",
    "locator": "gateway_module",
    "locator_type": "objects",
    "gateway_module": [
      {
        "gateway_id": "wbay0o1O8qGK6D34",
        "module_id": "nwQ7m57MKk",
        "install_branch": "production",
        "module_type": "interface",
        "machine_label": "Homevision",
        "label": "Homevision",
        "short_description": "Adds support for Homevision and Homevision Pro automation systems to Yombo. Support X10, relays, sensors, and other items.",
        "description": "Summary\r\n=======\r\n\r\nAdds support for Homevision and Homevision Pro automation systems to Yombo. Support X10, relays, sensors, and other items.\r\n\r\nUsage\r\n=====\r\n\r\nThe goal is support all to functions: X10, relays, input and outputs, 1-wire temperature\r\nsensors, and more.\r\n\r\nInstallation\r\n============\r\n\r\nSimply mark this module as being used by the gateway, and the gateway will\r\ndownload and install this module automatically.\r\n\r\nRequirements\r\n============\r\n\r\nTo be used with the Yombo Gateway. If X-10 control is desired, install the\r\nX10 API module.\r\n\r\nLicense\r\n=======\r\n\r\nThe [Yombo](https://yombo.net/) team and other contributors hopes that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\r\n\r\nSee LICENSE file for full details.\r\n",
        "description_formatting": "markdown",
        "see_also": null,
        "repository_link": "https://bitbucket.org/yombo/module-homevision",
        "issue_tracker_link": "",
        "install_count": 0,
        "doc_link": "https://bitbucket.org/yombo/module-homevision",
        "git_link": "https://bitbucket.org/yombo/module-homevision.git",
        "prod_branch": "master",
        "dev_branch": "develop3",
        "prod_version": "056099dd",
        "dev_version": null,
        "public": 0,
        "status": 0,
        "created_at": 1489873989,
        "updated_at": 1491367792,
        "variable_groups": [
          {
            "id": "1XVBGZKeQDwx",
            "relation_id": "nwQ7m57MKk",
            "relation_type": "module",
            "group_machine_label": "connections",
            "group_label": "Interface Connection",
            "group_description": "Interface connection information for serial/usb port.",
            "group_weight": 1,
            "status": 1,
            "created_at": 1482065388,
            "updated_at": 1482065388
          }
        ],
        "variable_fields": [
          {
            "id": "Dox5ygJ9d98G0",
            "group_id": "1XVBGZKeQDwx",
            "field_machine_label": "port",
            "field_label": "Port Name",
            "field_description": "Port name to find device. either /dev/ttyUSB0, com1:, /dev/custom_map_name",
            "field_weight": 0,
            "value_required": 0,
            "value_max": 0,
            "value_min": 0,
            "encryption": "nosuggestion",
            "value_casing": "none",
            "input_type_id": "3VNoxrdz",
            "default_value": "",
            "help_text": "For linux machines, it's advisable to setup a udev mapping for consistency. See: https://yombo.com/ for more information.",
            "multiple": false,
            "created_at": 1482065388,
            "updated_at": 1482065388
          }
        ],
        "variable_data": [
          {
            "id": "4k8mOj64p6r3Jx2p",
            "gateway_id": "wbay0o1O8qGK6D34",
            "field_id": "Dox5ygJ9d98G0",
            "relation_id": "nwQ7m57MKk",
            "relation_type": "module",
            "data": "/dev/homevision",
            "data_weight": 0,
            "created_at": 1489873990,
            "updated_at": 1489873990
          }
        ],
        "device_types": [
          {
            "id": "x9yNA1DxyYdrRgLw",
            "module_id": "nwQ7m57MKk",
            "device_type_id": "0VmP7Wbn",
            "created_at": 1489043780
          },
          {
            "id": "EmX4W0YJMDgzNnJP",
            "module_id": "nwQ7m57MKk",
            "device_type_id": "kEmK2WM0",
            "created_at": 1482065387
          },
          {
            "id": "n6jvNkY9pDq3Egra",
            "module_id": "nwQ7m57MKk",
            "device_type_id": "QvWaQWjk",
            "created_at": 1482065387
          },
          {
            "id": "Ro9v8Nb5AbZwWB7p",
            "module_id": "nwQ7m57MKk",
            "device_type_id": "OgxDPx14",
            "created_at": 1482065387
          },
          {
            "id": "dm6vwJKaxbLpBy7G",
            "module_id": "nwQ7m57MKk",
            "device_type_id": "1XmJ2md3",
            "created_at": 1482065387
          }
        ]
      }
    ]
  },
  "code": 200,
  "warnings": [],
  "pages": {
    "total_items": 13,
    "page_limit": 1,
    "total_pages": 13,
    "page_start": 1
  },
  "message": "OK",
  "html_message": "OK"
}

Get all modules assigned to a gateway.

GET Request

GET https://api.yombo.net/api/v1/gateway/<gateway_id>/module

Filters

List of available Filters:

GET - Specific Gateway Module

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
https://api.yombo.net/api/v1/gateway/wbay0o1O8qGK6D34/module/nwQ7m57MKk
import requests

url = 'https://api.yombo.net/api/v1/gateway/wbay0o1O8qGK7F68/module/nwQ7m57MKk'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/gateway/wbay0o1O8qGK7F68/module/nwQ7m57MKk",
    "uri_description": "Detailed information for a single module installed on a gateway.",
    "doc_uri": "https://yombo.net/api/#gw-modules",
    "locator": "gateway_module",
    "locator_type": "object",
    "gateway_module": {
      "gateway_id": "wbay0o1O8qGK6D34",
      "module_id": "nwQ7m57MKk",
      "install_branch": "production",
      "module_type": "interface",
      "machine_label": "Homevision",
      "label": "Homevision",
      "short_description": "Adds support for Homevision and Homevision Pro automation systems to Yombo. Support X10, relays, sensors, and other items.",
      "description": "Summary\r\n=======\r\n\r\nAdds support for Homevision and Homevision Pro automation systems to Yombo. Support X10, relays, sensors, and other items.\r\n\r\nUsage\r\n=====\r\n\r\nThe goal is support all to functions: X10, relays, input and outputs, 1-wire temperature\r\nsensors, and more.\r\n\r\nInstallation\r\n============\r\n\r\nSimply mark this module as being used by the gateway, and the gateway will\r\ndownload and install this module automatically.\r\n\r\nRequirements\r\n============\r\n\r\nTo be used with the Yombo Gateway. If X-10 control is desired, install the\r\nX10 API module.\r\n\r\nLicense\r\n=======\r\n\r\nThe [Yombo](https://yombo.net/) team and other contributors hopes that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\r\n\r\nSee LICENSE file for full details.\r\n",
      "description_formatting": "markdown",
      "see_also": null,
      "repository_link": "https://bitbucket.org/yombo/module-homevision",
      "issue_tracker_link": "",
      "install_count": 0,
      "doc_link": "https://bitbucket.org/yombo/module-homevision",
      "git_link": "https://bitbucket.org/yombo/module-homevision.git",
      "prod_branch": "master",
      "dev_branch": "develop3",
      "prod_version": "056099dd",
      "dev_version": null,
      "public": 0,
      "status": 0,
      "created_at": 1489873989,
      "updated_at": 1491367792,
      "variable_groups": [
        {
          "id": "1XVBGZKeQDwx",
          "relation_id": "nwQ7m57MKk",
          "relation_type": "module",
          "group_machine_label": "connections",
          "group_label": "Interface Connection",
          "group_description": "Interface connection information for serial/usb port.",
          "group_weight": 1,
          "status": 1,
          "created_at": 1482065388,
          "updated_at": 1482065388
        }
      ],
      "variable_fields": [
        {
          "id": "Dox5ygJ9d98G0",
          "group_id": "1XVBGZKeQDwx",
          "field_machine_label": "port",
          "field_label": "Port Name",
          "field_description": "Port name to find device. either /dev/ttyUSB0, com1:, /dev/custom_map_name",
          "field_weight": 0,
          "value_required": 0,
          "value_max": 0,
          "value_min": 0,
          "encryption": "nosuggestion",
          "value_casing": "none",
          "input_type_id": "3VNoxrdz",
          "default_value": "",
          "help_text": "For linux machines, it's advisable to setup a udev mapping for consistency. See: https://yombo.com/ for more information.",
          "multiple": false,
          "created_at": 1482065388,
          "updated_at": 1482065388
        }
      ],
      "variable_data": [
        {
          "id": "4k8mOj64p6r3Jx2p",
          "gateway_id": "wbay0o1O8qGK6D34",
          "field_id": "Dox5ygJ9d98G0",
          "relation_id": "nwQ7m57MKk",
          "relation_type": "module",
          "data": "/dev/homevision",
          "data_weight": 0,
          "created_at": 1489873990,
          "updated_at": 1489873990
        }
      ]
    }
  },
  "code": 200,
  "warnings": [],
  "message": "OK",
  "html_message": "OK"
}

This endpoint retrieves a specific module for a gateway. Note: Same results can be achieved using a filter.

GET Request

GET https://api.yombo.net/api/v1/gateway/<gateway_id>/module/</module_id>

POST - Add module to gateway

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-X POST -d '{"module_id": "p3ky9DARdr", "install_branch": "production"}' \
https://api.yombo.net/api/v1/gateway/wbay0o1O8qGK7F68/module
import requests

url = 'https://api.yombo.net/api/v1/gateway/wbay0o1O8qGK7F68/module'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }

payload = {
    "module_id": "p3ky9DARdr",
    "install_branch": "production",
    }

response = requests.post(url, headers=headers, json=payload)
{
  "response": {
    "uri": "/api/v1/gateway/wbay0o1O8qGK7F68/module",
    "uri_description": "Link module to gateway.",
    "doc_uri": "https://yombo.net/api/#gw-modules",
    "locator": "gateway_module",
    "locator_type": "object",
    "gateway_module": {
      "module_id": "p3ky9DARdr",
      "install_branch": "production",
      "gateway_id": "wbay0o1O8qGK7F68",
      "updated_at": 1491885919,
      "created_at": 1491885919
    }
  },
  "code": 201,
  "warnings": [],
  "message": "Created",
  "html_message": "Created"
}

Adds a new module to be installed on the gateway.

POST Request

POST https://api.yombo.net/api/v1/gateway/<gateway_id>/module

Device POST Parameters

Name Type Description
Required
module_id string Module to assign to gateway.
install_branch string Which development branch to install, one of: “production” or “development”
Optional
status integer The status of the module. Default=1. Possible values: 0=disabled, 1=enabled, 2=mark for deletion

PUT - Update Device

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-X POST -d '{"module_id": "p3ky9DARdr", "install_branch": "development"}' \
https://api.yombo.net/api/v1/gateway/wbay0o1O8qGK7F68/module
import requests

url = 'https://api.yombo.net/api/v1/gateway/wbay0o1O8qGK7F68/module'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }

payload = {
    "module_id": "p3ky9DARdr",
    "install_branch": "development",
    }

response = requests.post(url, headers=headers, json=payload)
{
  "response": {
    "uri": "/api/v1/gateway/wbay0o1O8qGK7F68/module/nwQ7m57MKk",
    "uri_description": "Update gateway.",
    "doc_uri": "https://yombo.net/api/#gw-modules",
    "locator": "gateway_module",
    "locator_type": "object",
    "gateway_module": {
      "gateway_id": "wbay0o1O8qGK7F68",
      "module_id": "nwQ7m57MKk",
      "install_branch": "development",
      "status": 1,
      "created_at": 1483503995,
      "updated_at": 1485903495
    }
  },
  "code": 200,
  "warnings": [],
  "message": "Updated",
  "html_message": "Updated"
}

This endpoint updates all attributes of a device. To update only one or more, see PATCH Update Device. Same requirements as POST - New Device, except use PUT verb instead of POST.

PUT Request

PUT https://api.yombo.net/api/v1/device/<device_id>

Delete - Remove module from gateway

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-X DELETE \
https://api.yombo.net/api/v1/gateway/wbay0o1O8qGK7F68/module/nwQ7m57MKk'
import requests

url = 'https://api.yombo.net/api/v1/gateway/wbay0o1O8qGK7F68/module/nwQ7m57MKk'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }

response = requests.delete(url, headers=headers)
{
  "response": {
    "uri": "/api/v1/gateway/wbay0o1O8qGK7F68/module/nwQ7m57MKk",
    "uri_description": "Gateway mdoule deleted",
    "doc_uri": "https://yombo.net/api/#gw-modules",
    "locator": "gateway_module",
    "locator_type": "string",
    "gateway_module": "Deleted"
  },
  "code": 200,
  "warnings": [],
  "message": "Deleted",
  "html_message": "Deleted"
}

Deletes a command.

DELETE Request

DELETE https://api.yombo.net/api/v1/device/<command_id>

GW New Hash

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
https://api.yombo.net/api/v1/gateway/wbay0o1O8qGK7F68/new_hash
import requests

url = 'https://api.yombo.net/api/v1/gateway/3YDa6er5lqKo7F68/new_hash'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }

response = requests.get(url, headers=headers)
{
  "response": {
    "uri": "/api/v1/gateway/3YDa6er5lqKo7F68/new_hash",
    "uri_description": "Gateway hash created, owner notified.",
    "doc_uri": "https://yombo.net/api/#gateways-gw",
    "locator": "gateway",
    "locator_type": "object",
    "gateway": {
      "id": "3YDa6er5lqKo7F68",
      "machine_label": "raspberry",
      "label": "Raspberry Pi 3",
      "description": "asdfasdfasdf",
      "last_connect": null,
      "status": 0,
      "created_at": 1485305711,
      "updated_at": 1491869485,
      "hash": "59esREQDnUdLQqUFu9XwrKWwoW0tzJ7vfXwDxFE1",
      "uuid": "2azXIkHxi0oIs3EJ"
    }
  },
  "code": 200,
  "warnings": [],
  "message": "OK",
  "html_message": "OK"
}

When reinstalling a gateway, a new hash is sometimes required. This basically resets the gateway password when connecting to the backend. Typically, this should only be used when installing a new gateway and the previous gateway information was non-recoverable.

GET Request

GET https://api.yombo.net/api/v1/gateway/<gateway_id>/new_hash

GW Users

Gateways restrict users who can login and access the gateway. There are currently two components to the gateway user access sytem:

Currently, basic user access controls are implemented. Further access controls are planned.

See Users to search for user id’s.

GET - All users for a gateway

# lets limit to 1
curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
https://api.yombo.net/api/v1/gateway/3YDa6er5lqKo9U3q/user
import requests

url = 'https://api.yombo.net/api/v1/gateway/3YDa6er5lqKo9U3q/user'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/gateway/3YDa6er5lqKo9U3q/user",
    "uri_description": "List of users for a requested gateways.",
    "doc_uri": "https://yombo.net/docs/api/gateways/",
    "locator": "gateway_users",
    "locator_type": "integer",
    "gateway_users": [
      {
        "id": "Z3l9OMg0C2SRSuCgaZ",
        "gateway_id": "3YDa6er5lqKo9AQX",
        "user_id": "aCVlx2tPKemQiR2HEy",
        "created_at": 1485305711,
        "updated_at": 1485305712,
        "email": "testuser1@yombo.net"
      }
    ]
  },
  "code": 200,
  "warnings": [],
  "pages": {
    "total_items": 9,
    "page_limit": 400,
    "total_pages": 1,
    "page_start": 1
  },
  "message": "OK",
  "html_message": "OK"
}

Get all users who can access the gateway.

GET Request

GET https://api.yombo.net/api/v1/gateway/<gateway_id>/user

POST - Add module to gateway

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-X POST -d '{"user_id": "aCVlx2tPKemQiR2HEy"}' \
https://api.yombo.net/api/v1/gateway/3YDa6er5lqKo9U3q/user
import requests

url = 'https://api.yombo.net/api/v1/gateway/3YDa6er5lqKo9U3q/user'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }

payload = {
    "user_id": "aCVlx2tPKemQiR2HEy",
    }

response = requests.post(url, headers=headers, json=payload)
{
  "response": {
    "uri": "/api/v1/gateway/3YDa6er5lqKo9U3q/user",
    "uri_description": "Add a user to a gateway.",
    "doc_uri": "https://yombo.net/api/#gw-users",
    "locator": "gateway_users",
    "locator_type": "object",
    "gateway_users": {
      "user_id": "aCVlx2tPKemQiR2HEy",
      "gateway_id": "3YDa6er5lqKo9U3q",
      "updated_at": 1491891067,
      "created_at": 1491891067,
      "id": "IAJ3wkWpSlDgIuLQm3"
    }
  },
  "code": 201,
  "warnings": [],
  "message": "Created",
  "html_message": "Created"
}

Adds a user to be able to access the gateway.

POST Request

POST https://api.yombo.net/api/v1/gateway/<gateway_id>/module

Device POST Parameters

Name Type Description
Required
user_id string User ID to add. See Users for looking up users.

Delete - Remove user from gateway

curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-X DELETE \
https://api.yombo.net/api/v1/gateway/gateway/3YDa6er5lqKo9U3q/user/aCVlx2tPKemQiR2HEy'
import requests

url = 'https://api.yombo.net/api/v1/gateway/3YDa6er5lqKo9U3q/user/aCVlx2tPKemQiR2HEy'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }

response = requests.delete(url, headers=headers)
{
  "response": {
    "uri": "/api/v1/gateway/3YDa6er5lqKo9U3q/user/aCVlx2tPKemQiR2HEy",
    "uri_description": "Gateway user deleted.",
    "doc_uri": "https://yombo.net/api/#gw-users",
    "locator": "gateway_users",
    "locator_type": "string",
    "gateway_users": "Deleted"
  },
  "code": 200,
  "warnings": [],
  "message": "Deleted",
  "html_message": "Deleted"
}

Deletes a command.

DELETE Request

DELETE https://api.yombo.net/api/v1/gateway/<gateway_id>/user/<user_id>

Modules

Modules extend the capabilies of the gateway…

Module Device Types

Manage and view what device types are attached to modules.

Variable Groups

Variable groups contain multiple variable fields. This is just a way to group similar fields together, such as login information or device addressing information.

Variable Fields

Variable fields are defined by the module developer and define what types of variable data should be collected by the user when installing a module or configuring a device.

Variable Data

Variable data is provided by users and to sent to modules and devices during runtime of the gateway.

Other Resources

Categories

Some objects within the API are broken down by categories. (To be completed.)

DNS

A read only resource.

This resource shows available domains and if a subdomain is available. See the gateway dns for managing a specific gateway’s DNS.

Input Types

Input types are used on data collection fields to help filter and validate input.

Users

Search for user’s ID based on email address.

GET - Find user ID

# lets limit to 1
curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
https://api.yombo.net/api/v1/user/yombo@example.com
import requests

url = 'https://api.yombo.net/api/v1/user/yombo@example.com'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
{
  "response": {
    "uri": "/api/v1/user/testuser1@yombo.net",
    "uri_description": "Find a single user based on ID or email.",
    "doc_uri": "https://yombo.net/docs/api/user/",
    "locator": "user",
    "locator_type": "integer",
    "user": {
      "id": "aCVlx2tPKemQiR2HEy",
      "name": "test",
      "email": "testuser1@yombo.net"
    }
  },
  "code": 200,
  "warnings": [],
  "message": "OK",
  "html_message": "OK"
}

Get all users who can access the gateway.

GET Request

GET https://api.yombo.net/api/v1/user/<email_address>

External Links