Seam Docs
Search…
Your First Device API Call
5 mins
So what exactly can you do with Jane's devices? Well, that depends on their Capabilities! Let's discuss what those are and then use them.
​

Device Capabilities

A Device Capability is a feature or function of a device.
For example, on a door-lock the access_codes capability lets you program pin-codes. These codes then let a user unlock the door without keys.
Each Capability decomposes into actions, properties, and events.
  • Actions β€” things you can do to it.
  • Properties β€” the current state of the device.
  • Events β€” reports from the device describing state transitions.
Taken as a whole, the capabilities of a device describe its programmatic interface. At Seam, we work as best we can toward standardizing each capability's API across brands. For example, our lock/unlock actions work the same across brands of door locks.
​

Supported Device Capabilities

Let's inspect one of Jane's August devices to see its capabilities. Here we can see that her August locks support lock and access_codes capabilities.
Javascript
Python
1
// Replace with
2
// const Seam = require("seamapi")
3
// if not using ES6 modules and/or TypeScript.
4
import Seam from "seamapi";
5
​
6
// Seam will automatically use the SEAM_API_KEY environment variable if you
7
// don't provide an apiKey to `new Seam()`
8
const seam = new Seam();
9
​
10
const inspectDeviceCapabilities = async () => {
11
const {
12
devices: [someLock],
13
} = await seam.locks.list();
14
console.log(someLock.capabilities_supported);
15
};
16
​
17
inspectDeviceCapabilities();
18
​
19
/*
20
[ 'access_code', 'lock' ]
21
*/
Copied!
1
from seamapi import Seam, Device
2
​
3
seam = Seam()
4
some_lock = seam.locks.list()[0]
5
​
6
# Inspect the Lock
7
print(some_lock.capabilities_supported)
8
# ['access_code', 'lock']
Copied!
​

Lock/Unlock the Door

The lock capability provides two actions: LOCK and UNLOCK. It also has a locked property to know its current status.
Let's use this to toggle its state!
Javascript
Python
1
// Replace with
2
// const Seam = require("seamapi")
3
// if not using ES6 modules and/or TypeScript.
4
import Seam from "seamapi";
5
​
6
// Seam will automatically use the SEAM_API_KEY environment variable if you
7
// don't provide an apiKey to `new Seam()`
8
const seam = new Seam();
9
​
10
const toggleLock = async () => {
11
const {
12
devices: [someLock],
13
} = await seam.locks.list();
14
15
// If the lock is opened, lock it, else unlock it
16
if (someLock.properties.locked) {
17
await seam.locks.unlockDoor(someLock.device_id);
18
} else {
19
await seam.locks.lockDoor(someLock.device_id);
20
}
21
};
22
​
23
toggleLock();
Copied!
1
from seamapi import Seam, Device
2
​
3
seam = Seam()
4
some_lock = seam.locks.list()[0]
5
​
6
# Unlock or lock the door
7
if some_lock.properties["locked"]:
8
seam.locks.unlock_door(some_lock)
9
else:
10
seam.locks.lock_door(some_lock)
11
Copied!
​

Setting an Access Code

The access_code capability lets you program pin code on a lock. This code can used to unlock the door without keys.
Let's program an access code.
Javascript
Python
1
// Replace with
2
// const Seam = require("seamapi")
3
// if not using ES6 modules and/or TypeScript.
4
import Seam from "seamapi";
5
​
6
// Seam will automatically use the SEAM_API_KEY environment variable if you
7
// don't provide an apiKey to `new Seam()`
8
const seam = new Seam();
9
​
10
const createAccessCode = async () => {
11
const {
12
devices: [someLock],
13
} = await seam.locks.list();
14
​
15
await seam.accessCodes.create({
16
device_id: someLock.device_id,
17
name: "some-code",
18
});
19
};
20
​
21
createAccessCode();
22
​
23
/*
24
{
25
access_code_id: "6f9da26d-f5a3-4df9-9dc9-816251346bc5",
26
type: "ongoing",
27
code: "662156",
28
starts_at: null,
29
ends_at: null,
30
name: "some-code",
31
}
32
*/
Copied!
1
from seamapi import Seam, Device
2
​
3
seam = Seam()
4
some_lock = seam.locks.list()[0]
5
​
6
# Program an access code
7
access_code = seam.access_codes.create(some_lock, name="some-code")
8
print(access_code)
9
# AccessCode(access_code_id='6f9da26d-f5a3-4df9-9dc9-816251346bc5',
10
# type='ongoing',
11
# code='662156', <======== this is the code!
12
# starts_at=None,
13
# ends_at=None,
14
# name='some-code')
15
Copied!

Conclusion

This Quickstart Guide walked you through the main idea behind Seam.
This guide is only the beginning of your journey into the world of connected devices. Next, you can check out the Core Concepts behind Seam next, or pick up one of the device guides.
If you have questions or comments, please reach out. We love to hear from developers and see what you are building!
πŸ’“
​
☺
​
​