API docs by Redocly

Actcast API v0 (2021.10.22)

Download OpenAPI specification:Download

URL: https://github.com/Idein/actcast-support
https://actcast.io/docs/

Actcast API v0

このバージョンは試験的に提供しているものです。移行期間を設けたうえで破壊的変更を行う可能性があります。

このAPIを使用することでダッシュボードを経由せずにデバイスの管理ができます。

認証

ApiToken

Actcast上でAPIトークンを発行します。 Authorization ヘッダーに token {api-token} という文字列を設定しリクエストを行います。

デバイス一覧取得の例

$ curl -H "Authorization: token $YOUR_API_TOKEN" https://api.actcast.io/v0/groups/$YOUR_GROUP_ID/devices
Security Scheme Type: API Key
Header parameter name: Authorization

レートリミット

Actcast APIにはリクエスト数の制限が存在します。レートリミットの上限緩和についてはグループの情報や使用用途を添えてお問い合わせください。

APIのレスポンスは、レートリミットの状態を表す次のヘッダーを含みます。

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

ヘッダーの値は次の仕様に準拠しています。ただし、ヘッダー名の先頭に X- が加えられていることに注意してください。 draft-polli-ratelimit-headers-00

また、レスポンスのステータスコードが429(Too Many Requests)のとき追加で Retry-After ヘッダーが含まれます。 このとき Retry-After の値は次にリクエストを送れるようになるまでの秒数を表しています。

ステータスコード

ステータスコード 理由 備考
200 OK 成功
202 Accepted 成功(非同期)
400 Bad Request リクエスト形式の間違い
401 Unauthorized 認証情報の間違い
403 Forbidden 権限のエラー
404 Not Found 対象が存在しない
429 Too Many Requests レートリミット

ページネーション

一つのレスポンスに複数のリソースが含まれている場合、一定以上の数のリソースを取得しようとすると複数回のリクエストを行う必要があります。

next 方式

リクエスト時に次のクエリパラメータを付与します。

パラメータ名 備考
limit 取得するリソース数
next 続きを取得するためのトークン

レスポンスには次の項目が含まれます。

フィールド名 備考
items リソースの配列
totol 全体の数
next 続きを取得するためのトークン

デバイス一覧取得の例

$ curl -H "Authorization: token $YOUR_API_TOKEN" https://api.actcast.io/v0/groups/$YOUR_GROUP_ID/devices?limit=5
{
  "items": [
    ... snip ...
  ],
  "total": 10,
  "next": "dummy_next_token"
}
$ curl -H "Authorization: token $YOUR_API_TOKEN" https://api.actcast.io/v0/groups/$YOUR_GROUP_ID/devices?limit=5&next=dummy_next_token
{
  "items": [
    ... snip ...
  ],
  "total": 10,
  "next": null
}

データ型

プリミティブデータ型に対するformatの指定については下記のリンク先をご覧ください。

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#data-types

一部のクエリパラメータ(include_device_status など)で 0, 1 のいずれかを渡す必要がある場合 1 が有効を意味します。

リソース

Act

以下のテーブルは一部のフィールドの説明となります。

フィールド名 備考
act 設定される予定の値
reported_act デバイスから最後に報告された設定値

Tips

  • 一時的なサーバー負荷によって API がステータス 503 Service Unavailable を返す場合があります。 問題になる場合は Exponential Backoff アルゴリズムに従ってリトライすることを検討してください。

devices

デバイス一覧

グループが管理しているデバイス一覧を返します。 必要に応じて、欲しい情報をパラメータで渡すことが可能です。

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

The numbers of items to return

next
string

string

include_status
number
Enum: 0 1

add device status to device

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "items": [
    ],
  • "total": 0,
  • "next": "string"
}

デバイスコマンド送信

グループが管理しているデバイスに対してコマンドを送信します。 必要に応じて、デバイスを限定するクエリを渡すことが可能です。

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
query Parameters
q
string

random query to search something

Request Body schema: application/json
required
object (UpdateDevicesOperation)

type が update_device_info の時は tags, access_points, firmware_update_masks, firmware_config, auto_reboot_config, dying_log フィールド type が update_device_act の時は id, settings restore フィールド（settings が null | undefined の場合はデバイス固有の設定を削除します）（restore: true のときは、以前の固有設定があればそれを使い、なければ共通設定を使います） type が create_device_job の時は command フィールド がそれぞれ存在します。 type が uninstall_act, unregister_device の時は追加のフィールドはありません。

Responses

Request samples

Content type
application/json
{
  • "operation": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "code": "string",
  • "message": "string"
}

デバイス情報取得

デバイスの情報を返します。 必要に応じて、欲しい情報をパラメータで渡すことが可能です。

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)
query Parameters
include_status
number
Enum: 0 1

add device status to device

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "device": {
    },
  • "status": {
    }
}

デバイス設定変更

デバイスの名前やタグを変更します

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)
query Parameters
include_status
number
Enum: 0 1

add device status to device

Request Body schema: application/json
required
name
string (Name) [ 1 .. 100 ] characters
hostname
string (Hostname)
country_code
string (CountryCode)
tags
Array of strings (DeviceTagName) [ items [ 1 .. 128 ] characters ]
Array of objects
Array of objects (FirmwareUpdateMask)
object (FirmwareConfig)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "hostname": "string",
  • "country_code": "string",
  • "tags": [
    ],
  • "access_points": [
    ],
  • "firmware_update_masks": [
    ],
  • "firmware_config": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "code": "string",
  • "message": "string"
}

デバイス削除

デバイスを管理対象から外します

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)
query Parameters
include_status
number
Enum: 0 1

add device status to device

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "code": "string",
  • "message": "string"
}

デバイス上のAct

デバイスに設定されているActの情報を返します。 デバイスにActが設定されていない場合404 act_not_installedが返ります。

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "artifact_id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "id": 0,
  • "name": "string",
  • "settings": { },
  • "base_settings": { },
  • "device_specific_settings": { }
}

デバイス上のActの詳細設定

デバイスに設定されているActの詳細設定を変更します settingsはreleaseのsetting_schemaに適合しなければなりません

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)
Request Body schema: application/json
required
settings
object

Responses

Request samples

Content type
application/json
{
  • "settings": { }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "code": "string",
  • "message": "string"
}

デバイス上のActの変更

デバイスに設定されているActを変更します。 settingsはreleaseのsetting_schemaに適合しなければなりません device にインストール可能な Act の Release バイナリがなかった場合 404 が返ります

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)
Request Body schema: application/json
required
id
required
integer (ActId)
settings
object

Responses

Request samples

Content type
application/json
{
  • "id": 0,
  • "settings": { }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "code": "string",
  • "message": "string"
}

デバイス上のAct削除

デバイス上のActをアンインストールします

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "code": "string",
  • "message": "string"
}

デバイスのログ

過去14日以内のデバイスのログを返します（デバイス上のActのログを含みません）

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)
query Parameters
start
integer (UnixTimeMillis)

older limit to show logs

end
integer (UnixTimeMillis)

newer limit to show logs

limit
integer [ 1 .. 100 ]
Default: 20

The numbers of items to return

next
string

string

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "items": [
    ],
  • "next": "string"
}

デバイス上のActのログ

デバイスに設定されているActの過去14日以内の出力ログを返します。

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

The numbers of items to return

next
string

string

start
integer (UnixTimeMillis)

older limit to show logs

end
integer (UnixTimeMillis)

newer limit to show logs

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "items": [
    ],
  • "next": "string"
}

デバイスにジョブコマンドを送信

デバイスにジョブコマンドを送信します。

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)
job_command_type
required
string (JobCommandType)
Enum: "take_photo" "firmware_update" "os_reboot" "device_status" "os_shutdown" "blink_led"

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "code": "string",
  • "message": "string"
}

直近の撮影結果の取得

最後に撮影したカメラ画像の情報を返します。 URLは画像サーバーが期限付きで発行します。

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "photo": {
    },
  • "requested_at": "2019-08-24T14:15:22Z"
}

デバイスに撮影を要求

デバイス搭載のカメラで撮影します。 撮影要求から1日以上経過したカメラ画像は削除されます。

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "code": "string",
  • "message": "string"
}

デバイス証明書を取得

デバイスの証明書を取得します。

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "certificate_pem": "string"
}

apps

アプリ詳細

アプリの詳細情報を返します。

Authorizations:
ApiToken
path Parameters
app_id
required
integer (AppId)

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "app": {
    },
  • "latest_release": {
    }
}

リリース詳細

リリースの詳細情報を返します。

Authorizations:
ApiToken
path Parameters
artifact_id
required
integer (ArtifactId)

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "app_id": 0,
  • "artifact_id": 0,
  • "id": 0,
  • "long_description": "string",
  • "long_descriptions": { },
  • "manifesto": [
    ],
  • "revision": 0,
  • "setting_schema": { },
  • "short_description": "string",
  • "short_descriptions": { },
  • "version": "string"
}

リリースの設定のスキーマ

該当リリースをActとしてデバイスにインストールするときに設定可能な項目のスキーマを JSON Schema形式で返します。

Authorizations:
ApiToken
path Parameters
artifact_id
required
integer (ArtifactId)

Responses

Response samples

Content type
application/json; charset=utf-8
{ }

acts

デバイス上のAct

デバイスに設定されているActの情報を返します。 デバイスにActが設定されていない場合404 act_not_installedが返ります。

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "artifact_id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "id": 0,
  • "name": "string",
  • "settings": { },
  • "base_settings": { },
  • "device_specific_settings": { }
}

デバイス上のActの詳細設定

デバイスに設定されているActの詳細設定を変更します settingsはreleaseのsetting_schemaに適合しなければなりません

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)
Request Body schema: application/json
required
settings
object

Responses

Request samples

Content type
application/json
{
  • "settings": { }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "code": "string",
  • "message": "string"
}

デバイス上のActの変更

デバイスに設定されているActを変更します。 settingsはreleaseのsetting_schemaに適合しなければなりません device にインストール可能な Act の Release バイナリがなかった場合 404 が返ります

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)
Request Body schema: application/json
required
id
required
integer (ActId)
settings
object

Responses

Request samples

Content type
application/json
{
  • "id": 0,
  • "settings": { }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "code": "string",
  • "message": "string"
}

デバイス上のAct削除

デバイス上のActをアンインストールします

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "code": "string",
  • "message": "string"
}

デバイス上のActのログ

デバイスに設定されているActの過去14日以内の出力ログを返します。

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

The numbers of items to return

next
string

string

start
integer (UnixTimeMillis)

older limit to show logs

end
integer (UnixTimeMillis)

newer limit to show logs

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "items": [
    ],
  • "next": "string"
}

act一覧

groupで使用しているact一覧を返します。

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

The numbers of items to return

offset
integer
Default: 0

The number of items to skip before starting to collect the result set

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "total": 0,
  • "items": [
    ]
}

act情報

actの情報を返します

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
act_id
required
integer (ActId)

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "artifact_id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "id": 0,
  • "name": "string",
  • "settings": { },
  • "app": {
    },
  • "release": {
    }
}

リリースの設定のスキーマ

該当リリースをActとしてデバイスにインストールするときに設定可能な項目のスキーマを JSON Schema形式で返します。

Authorizations:
ApiToken
path Parameters
artifact_id
required
integer (ArtifactId)

Responses

Response samples

Content type
application/json; charset=utf-8
{ }

logs

デバイスのログ

過去14日以内のデバイスのログを返します（デバイス上のActのログを含みません）

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)
query Parameters
start
integer (UnixTimeMillis)

older limit to show logs

end
integer (UnixTimeMillis)

newer limit to show logs

limit
integer [ 1 .. 100 ]
Default: 20

The numbers of items to return

next
string

string

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "items": [
    ],
  • "next": "string"
}

デバイスのイベントログ

過去14日以内のデバイスのイベントログを返します

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)
query Parameters
start
integer (UnixTimeMillis)

older limit to show logs

end
integer (UnixTimeMillis)

newer limit to show logs

limit
integer [ 1 .. 100 ]
Default: 20

The numbers of items to return

next
string

string

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "items": [
    ],
  • "next": "string"
}

デバイス上のActのログ

デバイスに設定されているActの過去14日以内の出力ログを返します。

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

The numbers of items to return

next
string

string

start
integer (UnixTimeMillis)

older limit to show logs

end
integer (UnixTimeMillis)

newer limit to show logs

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "items": [
    ],
  • "next": "string"
}

jobs

デバイスにジョブコマンドを送信

デバイスにジョブコマンドを送信します。

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)
job_command_type
required
string (JobCommandType)
Enum: "take_photo" "firmware_update" "os_reboot" "device_status" "os_shutdown" "blink_led"

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "code": "string",
  • "message": "string"
}

photo

直近の撮影結果の取得

最後に撮影したカメラ画像の情報を返します。 URLは画像サーバーが期限付きで発行します。

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "photo": {
    },
  • "requested_at": "2019-08-24T14:15:22Z"
}

デバイスに撮影を要求

デバイス搭載のカメラで撮影します。 撮影要求から1日以上経過したカメラ画像は削除されます。

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "code": "string",
  • "message": "string"
}

groups

グループ情報取得

グループの情報を返します。

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 0,
  • "name": "string",
  • "vendor_phase": "restricted",
  • "vendor_tokutei": {
    }
}

firmwares

ファームウェア詳細

ファームウェアのリリース詳細を返します

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
query Parameters
firmware_version
string
firmware_type
string
next
string

string

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "items": [
    ],
  • "next": "string"
}

events

デバイスのイベントログ

過去14日以内のデバイスのイベントログを返します

Authorizations:
ApiToken
path Parameters
group_id
required
integer (GroupId)
device_id
required
string (DeviceId)
query Parameters
start
integer (UnixTimeMillis)

older limit to show logs

end
integer (UnixTimeMillis)

newer limit to show logs

limit
integer [ 1 .. 100 ]
Default: 20

The numbers of items to return

next
string

string

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "items": [
    ],
  • "next": "string"
}