DRMN MCP 技術參考

給開發者與串接使用。一般使用者設定 AI 工具請看設定指南。

連線位址

MCP over Streamable HTTP。只有一個位址，只接受 POST，回應為 JSON。

POST https://digicms-cms.nichiahung.workers.dev/api/mcp
Authorization: Bearer dcms_…

驗證

每個請求都帶 Authorization: Bearer dcms_…（個人 API token）。token 屬於一個人，可以限定其中幾個商家，會到期，也隨時可以撤銷。OAuth（給 ChatGPT 與 claude.ai）排在之後的版本。每次呼叫工具都會重新檢查擁有者在你指定商家的角色，所以 token 的權限不會超過本人。

協定版本

MCP 2026-07-28 以無狀態方式提供：沒有 session，確認是帶著答案再呼叫一次（multi round-trip requests）。2025 版的 client 也以無狀態方式提供，所以無法在工具裡跳出確認，會改收到 needs_chat_confirmation（請人在對話裡回覆確認碼）。

限制

每把 token 每分鐘 120 次請求（超過回 HTTP 429 與 Retry-After）。
請求內容最多 256 KB。
不接受 JSON-RPC batch：一個請求只送一則訊息。

錯誤代碼

被拒絕或失敗的工具呼叫會回 isError，內容是 JSON：{ code, message, issues? }。

INVALID_INPUT: 參數不符合工具的 schema，issues 列出問題。
FORBIDDEN: 擁有者的角色或「只能準備」的 token 不允許這個操作。
NOT_FOUND: 找不到該 id，或這個商家不在 token 可用的範圍。兩種情況刻意回一樣的答案。
SUSPENDED: 這個商家已停權。
UNAUTHORIZED: token 在呼叫途中失效（已撤銷或過期）。
REVIEW_STALE: 草稿在審查之後被改過。請重新審查，並請人重新確認。
STALE: 資料在讀取之後被改過。請重新讀取再試。
CONFLICT: 有別的變更先儲存了。請重新讀取再試。
CONFIRMATION_UNAVAILABLE: 目前無法請人確認（確認框和對話確認碼都不行）。內容附有 DRMN 審查頁的連結。
INTERNAL: 伺服器內部錯誤，刻意不透露細節。

確認流程

會改變螢幕內容（發布、插播、撤下、重新發布）、改變螢幕行為（開關機時間、聲音、方向、旋轉）或建立公開報表連結的工具，是唯一需要人確認的。確認文字由伺服器依草稿快照產生，AI 無法改寫，並綁定審查 hash；中間草稿被改過，發布會失敗並回 REVIEW_STALE。「只能準備」的 token 在這些工具上會直接回 FORBIDDEN，連問都不問。

用 token 做自動化

排程工作、系統串接（POS、n8n、Make）與背景執行的 agent 適合用 token。它們可以查詢、建草稿、加入媒體，但不能自己讓內容上螢幕，因為沒有人在場確認。請把這類 token 建成「只能準備」，讓這件事從結構上就成立。做法是「機器準備好，人按一下」，例如 POS 建好草稿後通知店長，由店長打開審查連結。

工具清單

由伺服器實際提供的工具白名單自動產生，所以一定是最新的。除了 merchants_list，每個工具都要帶 merchant（來自 merchants_list 的短名稱）。

67 個工具

merchants_list唯讀
Lists the merchants this token can use, with name, short name (slug) and the owner's role. Call this first: every other tool needs a merchant.
參數 schema
```
{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {}
}
```
dashboard_get唯讀
Returns the merchant's screen and live campaign totals for the dashboard, and expiringMedia: media whose expiry date is within 14 days or has passed and that a live campaign plays (total, and the first 50 soonest date first, each with the campaigns that play it). Nothing stops playing on its date by itself; tell the person so they can replace the media or end the campaign. Requires "merchant" (call merchants_list first).
參數 schema
```
{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "merchant"
 ]
}
```

devices_list唯讀

Lists the merchant's screens with their location, connectivity, health, effective orientation, reported resolution, tags (id and name) and the recommended media spec (mediaSpec) for each, newest page first. tagIds keeps only the screens that carry every tag listed (tag ids from tags_list); total, online and offline then count those screens. Each description is cut to 200 characters (descriptionTruncated); devices_get returns all of it. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "limit": {
   "type": "integer",
   "minimum": 1,
   "maximum": 500
  },
  "cursor": {
   "type": "string",
   "maxLength": 64
  },
  "summary": {
   "type": "boolean"
  },
  "tagIds": {
   "description": "Only screens that carry every one of these tags (tag ids from tags_list). An id that is not the merchant's tag matches nothing.",
   "maxItems": 20,
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
   }
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "merchant"
 ]
}

devices_get唯讀

Returns one screen with its location, description (in full), tags, connectivity, health, effective orientation, reported resolution and the recommended media spec (mediaSpec) to make posters and videos for it. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "id",
  "merchant"
 ]
}

devices_now_playing唯讀

Names the media and campaign a screen last reported playing, with the media thumbnail. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "id",
  "merchant"
 ]
}

devices_diagnose唯讀

Explains one screen's state: last seen, online or offline, what it plays now, whether it runs the newest content, clock skew, last screenshot, opening hours, orientation, videos that may not play well on it, and a short list of findings (code, severity, message). Use it when someone asks why a screen is not playing. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "id",
  "merchant"
 ]
}

locations_list唯讀

Lists the merchant's locations for pickers. Each description is cut to 200 characters (descriptionTruncated); locations_get returns all of it. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "merchant"
 ]
}

locations_get唯讀

Returns one location: name, time zone, address, map position, loop settings and its description in full (the lists cut it to 200 characters). Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "id",
  "merchant"
 ]
}

media_get唯讀
Returns one piece of the merchant's media: name, description (in full), tags, type, status, size, checksum, expiry date and, for a video, its measured loudness (loudnessStatus null = not measured yet; it is measured when someone opens the media page). expiresOn is the last day (YYYY-MM-DD, inclusive, in each screen's local time) the media may play, or null; expiry is none, ok, soon (within 14 days; today counts) or expired. It is only a reminder: screens keep playing the media after that day. Requires "merchant" (call merchants_list first).
參數 schema
```
{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "id",
  "merchant"
 ]
}
```

media_list唯讀

Lists the merchant's media, newest first unless sort (name, size or date) and dir (asc or desc) are given, with search, type filter, a tag filter (tagIds, every tag listed) and paging: limit (default 50, at most 200) and offset; total is how many match. The search matches a media item's name or description. Each item carries its tags (id and name) and its description cut to 200 characters (descriptionTruncated); media_get returns all of it. The expiry filter keeps media that are none (no date), ok, soon or expired, soonest date first. expiresOn is the last day (YYYY-MM-DD, inclusive, in each screen's local time) the media may play, or null; expiry is none, ok, soon (within 14 days; today counts) or expired. It is only a reminder: screens keep playing the media after that day. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "search": {
   "type": "string",
   "maxLength": 200
  },
  "type": {
   "type": "string",
   "enum": [
    "image",
    "video",
    "web"
   ]
  },
  "readyOnly": {
   "type": "boolean"
  },
  "expiry": {
   "type": "string",
   "enum": [
    "none",
    "ok",
    "soon",
    "expired"
   ]
  },
  "tagIds": {
   "description": "Only media that carry every one of these tags (tag ids from tags_list). Combine with type or search to narrow further.",
   "maxItems": 20,
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
   }
  },
  "sort": {
   "type": "string",
   "enum": [
    "name",
    "size",
    "date"
   ]
  },
  "dir": {
   "type": "string",
   "enum": [
    "asc",
    "desc"
   ]
  },
  "limit": {
   "default": 50,
   "type": "integer",
   "minimum": 1,
   "maximum": 200
  },
  "offset": {
   "default": 0,
   "type": "integer",
   "minimum": 0,
   "maximum": 9007199254740991
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "merchant"
 ]
}

media_library唯讀

Lists ready media with preview URLs for the playlist editor, newest first, at most 200. tagIds keeps only the media that carry every tag listed (tag ids from tags_list), including ones older than the newest 200. Each item carries its tags (id and name) and its description cut to 200 characters (descriptionTruncated); media_get returns all of it. expiresOn is the last day (YYYY-MM-DD, inclusive, in each screen's local time) the media may play, or null; expiry is none, ok, soon (within 14 days; today counts) or expired. It is only a reminder: screens keep playing the media after that day. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "tagIds": {
   "description": "Only media that carry every one of these tags (tag ids from tags_list). Combine with type or search to narrow further.",
   "maxItems": 20,
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
   }
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "merchant"
 ]
}

tags_list唯讀
Lists the merchant's tags by name (at most 200), each with its description and how many screens and media carry it. Call this before tags_create: the merchant may already have the tag, and 台北 and 臺北 are one tag. Tag ids go into the tagIds filters of devices_list and media_list and into devices_update_tags and media_update_tags. Requires "merchant" (call merchants_list first).
參數 schema
```
{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "merchant"
 ]
}
```

playlists_list唯讀

Lists the merchant's shared playlists. Each description is cut to 200 characters (descriptionTruncated); playlists_get returns all of it. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "merchant"
 ]
}

playlists_get唯讀

Returns one playlist with its items and its description in full. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "id",
  "merchant"
 ]
}

schedules_list唯讀

Lists the merchant's schedules with how many campaigns use each. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "merchant"
 ]
}

schedules_get唯讀

Returns one schedule's dates, hours and weekdays. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "id",
  "merchant"
 ]
}

schedules_timezones唯讀

Lists the locations with active screens and their time zones. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "merchant"
 ]
}

calendar_get唯讀

Returns what each screen at a location shows over a week or a month. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "view": {
   "type": "string",
   "enum": [
    "week",
    "month"
   ]
  },
  "locationId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "deviceId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "date": {
   "type": "string",
   "maxLength": 10
  },
  "summary": {
   "type": "boolean"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "view",
  "merchant"
 ]
}

deployments_list唯讀
Lists the merchant's campaigns with their live and draft versions, a page at a time. Each campaign's description is cut to 200 characters (descriptionTruncated); deployments_lineage returns all of it. latestStatus is the stored version status (a published campaign stays published after its flight ends); flightState says where now falls in the flight: upcoming, running (within the flight; its hours decide the times of day) or ended (plays nothing). draft.flightState "ended" means the draft's flight has passed and it cannot be published as it is. Requires "merchant" (call merchants_list first).
參數 schema
```
{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "limit": {
   "type": "integer",
   "minimum": 1,
   "maximum": 500
  },
  "cursor": {
   "type": "string",
   "maxLength": 64
  },
  "summary": {
   "type": "boolean"
  },
  "archived": {
   "description": "true lists only archived campaigns; left out or false hides them (the default list).",
   "type": "boolean"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "merchant"
 ]
}
```

deployments_lineage唯讀

Returns one campaign with its description (in full), live version, open draft and version history. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "lineageId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "withItems": {
   "description": "true adds each earlier published version's media list (items, frozen at publish; the 10 newest), to compare versions.",
   "type": "boolean"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "lineageId",
  "merchant"
 ]
}

deployments_targetable_devices唯讀

Lists the active screens a campaign can target. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "merchant"
 ]
}

deployments_using唯讀

Lists the live campaigns made from a playlist or schedule (every live campaign when neither is given), and what each is behind on. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "playlistId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "scheduleId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "merchant"
 ]
}

deployments_outdated唯讀

Lists live campaigns whose playlist or schedule changed after they were published (of one playlist or schedule when given). Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "playlistId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "scheduleId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "merchant"
 ]
}

reports_plays唯讀

Returns proof-of-play counts by campaign version, screen and media, with per-campaign and per-day totals (ads and filler apart), for a date range. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "from": {
   "type": "string",
   "maxLength": 100
  },
  "to": {
   "type": "string",
   "maxLength": 100
  },
  "timezone": {
   "type": "string",
   "maxLength": 100
  },
  "lineageId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "deviceId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "mediaId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "deploymentIds": {
   "minItems": 1,
   "maxItems": 20,
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
   }
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "from",
  "to",
  "timezone",
  "merchant"
 ]
}

reports_plays_daily唯讀

Returns proof-of-play counts per local day, campaign version, screen and media, for the by-day export. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "from": {
   "type": "string",
   "maxLength": 100
  },
  "to": {
   "type": "string",
   "maxLength": 100
  },
  "timezone": {
   "type": "string",
   "maxLength": 100
  },
  "lineageId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "deviceId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "mediaId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "deploymentIds": {
   "minItems": 1,
   "maxItems": 20,
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
   }
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "from",
  "to",
  "timezone",
  "merchant"
 ]
}

reports_share_links唯讀

Lists a campaign's share links and their state (valid, expired or revoked). Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "lineageId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "lineageId",
  "merchant"
 ]
}

devices_screenshot唯讀

Returns a screen's latest screenshot, any unanswered screenshot request, and whether the screen can take screenshots. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "id",
  "merchant"
 ]
}

attributes_list唯讀
Lists the attributes a screen or location can carry, each with its key, label, type, what it applies to (device or location), the industry standard field it matches, and whether it can be set (writable), used in a group rule (ruleEligible) and used today (available). For now these are the system attributes: venue type, screen size and display technology (writable; their columns arrive in a later release, so available is false until then), and orientation, resolution, position, time zone and operating hours (computed from other fields). Look venue type codes up with taxonomies_venue_types. Requires "merchant" (call merchants_list first).
參數 schema
```
{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "merchant"
 ]
}
```
taxonomies_venue_types唯讀
Finds OpenOOH venue types (the standard list of kinds of place a screen can be in, such as retail > convenience store) for a screen's venue type. Give search (a name in Chinese or English, or an everyday word such as 超商; several words must all match) to find codes, best match first, or parent (a code from an earlier result) to list what is inside it, or both to search within it; with neither you get the top-level categories. At most 50 come back (truncated says when there were more). Each result has value (the code to store, like openooh-1.2:202), label, path and name, selectable (false for a top-level category: pick one of its children) and hasChildren. Deprecated types are not listed. Never guess a code: look it up here, and ask the person when two fit. Requires "merchant" (call merchants_list first).
參數 schema
```
{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "search": {
   "description": "Words to look for, in Chinese or English. Several words (separated by spaces) must all match.",
   "type": "string",
   "maxLength": 100
  },
  "parent": {
   "description": "A venue type code from an earlier result; lists what is inside it (with search: searches inside it).",
   "type": "string",
   "maxLength": 40
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "merchant"
 ]
}
```
media_request_upload寫入（螢幕不會改變）
Registers a file upload and returns presigned PUT URLs (upload, and thumbnailUpload when hasThumbnail is true) plus video compatibility warnings (never blocking; tell the person). Steps: (1) compute the SHA-256 hex checksum (shasum -a 256 FILE) and the size in bytes (stat); (2) for video read duration, width, height and codec with ffprobe -v error -select_streams v:0 -show_entries stream=codec_name,width,height:format=duration -of json FILE, and for images and videos alike make a 480-pixel-wide JPEG thumbnail whenever you can (the picture shown in the media library): ffmpeg -i FILE -ss 1 -frames:v 1 -vf scale=480:-2 thumb.jpg for video, ffmpeg -i FILE -vf scale=480:-2 thumb.jpg or on macOS sips -s format jpeg -Z 480 FILE --out thumb.jpg for an image (then set hasThumbnail true); (3) call this tool; (4) PUT the file: curl -sS -f -X PUT --data-binary @FILE with one -H "name: value" for EVERY header in upload.headers, unchanged, to upload.url (the thumbnail the same way with Content-Type image/jpeg and its own headers); (5) call media_finalize_upload with mediaId. Images up to 50 MB, videos up to 2 GB. If ffprobe is not installed, or you cannot read the person's files, use media_upload_link instead. If the merchant already has the same file, duplicateOf and mediaId name it and nothing needs uploading. Pass the same id again to retry safely. Requires "merchant" (call merchants_list first).
參數 schema
```
{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "name": {
   "type": "string",
   "maxLength": 500
  },
  "fileName": {
   "type": "string",
   "maxLength": 500
  },
  "mimeType": {
   "type": "string",
   "maxLength": 100
  },
  "fileSize": {
   "type": "integer",
   "minimum": 0,
   "maximum": 9007199254740991
  },
  "checksum": {
   "type": "string",
   "maxLength": 100
  },
  "duration": {
   "anyOf": [
    {
     "type": "number",
     "exclusiveMinimum": 0
    },
    {
     "type": "null"
    }
   ]
  },
  "width": {
   "anyOf": [
    {
     "type": "integer",
     "exclusiveMinimum": 0,
     "maximum": 9007199254740991
    },
    {
     "type": "null"
    }
   ]
  },
  "height": {
   "anyOf": [
    {
     "type": "integer",
     "exclusiveMinimum": 0,
     "maximum": 9007199254740991
    },
    {
     "type": "null"
    }
   ]
  },
  "hasThumbnail": {
   "type": "boolean"
  },
  "codec": {
   "anyOf": [
    {
     "type": "string",
     "maxLength": 50
    },
    {
     "type": "null"
    }
   ]
  },
  "id": {
   "type": "string",
   "maxLength": 36
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "name",
  "fileName",
  "mimeType",
  "fileSize",
  "checksum",
  "duration",
  "width",
  "height",
  "hasThumbnail",
  "merchant"
 ]
}
```

media_finalize_upload寫入（螢幕不會改變）

Marks an uploaded file as ready after checking that the stored object exists and has the declared size. Call it once the PUT to the presigned URL succeeded (and the thumbnail PUT, if any). Returns the media item; use its id in playlists. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "mediaId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "mediaId",
  "merchant"
 ]
}

media_upload_link唯讀
Returns a link (url) and a ticket so a person can add files through the CMS upload dialog, for AI tools that cannot read the person's files or lack ffmpeg. Give the person the url; they open it while signed in, choose the files, and come back to say they are done. Then call media_upload_status with the ticket. The link works for a few hours. Nothing is uploaded by this call. Requires "merchant" (call merchants_list first).
參數 schema
```
{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "merchant"
 ]
}
```

media_upload_status唯讀

Lists the media uploaded through one upload link (ticket from media_upload_link), with status, size, duration and video compatibility warnings. Only files uploaded through that link are returned, so use these ids and no others. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "ticket": {
   "type": "string",
   "minLength": 1,
   "maxLength": 1000
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "ticket",
  "merchant"
 ]
}

media_add_web_url寫入（螢幕不會改變）

Adds a web page as media and reports whether it may refuse to be embedded. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "name": {
   "type": "string",
   "maxLength": 500
  },
  "url": {
   "type": "string",
   "maxLength": 2000
  },
  "id": {
   "type": "string",
   "maxLength": 36
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "name",
  "url",
  "merchant"
 ]
}

media_rename寫入（螢幕不會改變）

Renames a media item. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "mediaId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "name": {
   "type": "string",
   "maxLength": 500
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "mediaId",
  "name",
  "merchant"
 ]
}

media_set_description寫入（螢幕不會改變）

Sets or clears a media item's description. Plain text of at most 1000 characters for colleagues and AI tools; it is never shown on a screen. Pass null or an empty text to clear it. This replaces the whole text and returns the one it replaced in "previous" (the audit log keeps it too). Lists show only the first 200 characters (descriptionTruncated: true). Read the whole text with media_get before you add to it or replace a truncated one. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "mediaId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "description": {
   "anyOf": [
    {
     "type": "string",
     "maxLength": 2000
    },
    {
     "type": "null"
    }
   ],
   "description": "Plain text for colleagues and AI tools, at most 1000 characters, never shown on a screen. null or an empty text clears it."
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "mediaId",
  "description",
  "merchant"
 ]
}

playlists_set_description寫入（螢幕不會改變）

Sets or clears a shared playlist's description. Plain text of at most 1000 characters for colleagues and AI tools; it is never shown on a screen. Pass null or an empty text to clear it. This replaces the whole text and returns the one it replaced in "previous" (the audit log keeps it too). Lists show only the first 200 characters (descriptionTruncated: true). Read the whole text with playlists_get before you add to it or replace a truncated one. A campaign's own content takes none: this refuses it, and the campaign's description is set with deployments_set_description. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "description": {
   "anyOf": [
    {
     "type": "string",
     "maxLength": 2000
    },
    {
     "type": "null"
    }
   ],
   "description": "Plain text for colleagues and AI tools, at most 1000 characters, never shown on a screen. null or an empty text clears it."
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "id",
  "description",
  "merchant"
 ]
}

devices_set_description寫入（螢幕不會改變）

Sets or clears a screen's description. Plain text of at most 1000 characters for colleagues and AI tools; it is never shown on a screen. Pass null or an empty text to clear it. This replaces the whole text and returns the one it replaced in "previous" (the audit log keeps it too). Lists show only the first 200 characters (descriptionTruncated: true). Read the whole text with devices_get before you add to it or replace a truncated one. It does not change what the screen plays. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "description": {
   "anyOf": [
    {
     "type": "string",
     "maxLength": 2000
    },
    {
     "type": "null"
    }
   ],
   "description": "Plain text for colleagues and AI tools, at most 1000 characters, never shown on a screen. null or an empty text clears it."
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "id",
  "description",
  "merchant"
 ]
}

locations_set_description寫入（螢幕不會改變）

Sets or clears a location's description. Plain text of at most 1000 characters for colleagues and AI tools; it is never shown on a screen. Pass null or an empty text to clear it. This replaces the whole text and returns the one it replaced in "previous" (the audit log keeps it too). Lists show only the first 200 characters (descriptionTruncated: true). Read the whole text with locations_get before you add to it or replace a truncated one. It does not change what any screen plays. Returns the row's new updatedAt too; a location form opened before this write is refused when saved, so it cannot overwrite the text. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "description": {
   "anyOf": [
    {
     "type": "string",
     "maxLength": 2000
    },
    {
     "type": "null"
    }
   ],
   "description": "Plain text for colleagues and AI tools, at most 1000 characters, never shown on a screen. null or an empty text clears it."
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "id",
  "description",
  "merchant"
 ]
}

deployments_set_description寫入（螢幕不會改變）

Sets or clears a campaign's description (the campaign, not one of its versions). Plain text of at most 1000 characters for colleagues and AI tools; it is never shown on a screen. Pass null or an empty text to clear it. This replaces the whole text and returns the one it replaced in "previous" (the audit log keeps it too). Lists show only the first 200 characters (descriptionTruncated: true). Read the whole text with deployments_lineage before you add to it or replace a truncated one. It opens no new version and does not change what any screen plays, so it needs no publishing. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "lineageId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "description": {
   "anyOf": [
    {
     "type": "string",
     "maxLength": 2000
    },
    {
     "type": "null"
    }
   ],
   "description": "Plain text for colleagues and AI tools, at most 1000 characters, never shown on a screen. null or an empty text clears it."
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "lineageId",
  "description",
  "merchant"
 ]
}

media_set_expiry寫入（螢幕不會改變）

Sets or clears the last day (expiresOn, YYYY-MM-DD, inclusive, read in each screen's own time zone; null clears it) that up to 200 media items may play, usually the end of a licence. All items change together or none does, and each changed one is returned with its previous date (the audit log keeps it too). It is only a reminder: nothing stops playing on that day by itself, no screen and no review changes, and the home page, the media list (expiry filter) and a campaign's review (expiringMedia) are where it shows. When you schedule a campaign with such media, suggest ending its flight on the earliest expiresOn. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "ids": {
   "minItems": 1,
   "maxItems": 200,
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
   },
   "description": "The media to change, at most 200."
  },
  "expiresOn": {
   "anyOf": [
    {
     "type": "string",
     "maxLength": 40
    },
    {
     "type": "null"
    }
   ],
   "description": "The last day the media may play, YYYY-MM-DD; null (or an empty text) clears it."
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "ids",
  "expiresOn",
  "merchant"
 ]
}

tags_create寫入（螢幕不會改變）
Creates a tag, or returns the one the merchant already has under the same name (existing: true; names are compared ignoring case, full-width letters, extra spaces, a leading # and 臺/台, so asking twice is safe). A name is 1 to 40 characters; the optional description is one line of at most 200. "similar" lists existing tags with a near-identical name: a hint that you may have meant one of them (use it instead, or keep the new tag if it is a different thing). A merchant can have 200 tags. Renaming, merging and deleting tags are for people. Requires "merchant" (call merchants_list first).
參數 schema
```
{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "name": {
   "type": "string",
   "maxLength": 200
  },
  "description": {
   "description": "One line saying what the tag is for, at most 200 characters. Ignored when the tag already exists.",
   "anyOf": [
    {
     "type": "string",
     "maxLength": 400
    },
    {
     "type": "null"
    }
   ]
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "name",
  "merchant"
 ]
}
```

media_update_tags寫入（螢幕不會改變）

Puts tags on and takes tags off media items (ids from media_list or media_library). Puts tags on and takes tags off in one write: add and drop are tag ids, both are applied together and the order does not matter, and adding a tag an item already has (or dropping one it lacks) changes nothing. An item carries at most 20 tags. Every id is checked first, so a wrong id or a full item changes nothing. Tags never change what a screen plays and need no confirmation. The result counts the links added and removed. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "ids": {
   "minItems": 1,
   "maxItems": 200,
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
   },
   "description": "The media ids, at most 200."
  },
  "add": {
   "description": "Tag ids to put on every one of them (from tags_list; create a missing tag with tags_create first).",
   "maxItems": 20,
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
   }
  },
  "drop": {
   "description": "Tag ids to take off every one of them.",
   "maxItems": 20,
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
   }
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "ids",
  "merchant"
 ]
}

devices_update_tags寫入（螢幕不會改變）

Puts tags on and takes tags off screens (ids from devices_list). Puts tags on and takes tags off in one write: add and drop are tag ids, both are applied together and the order does not matter, and adding a tag an item already has (or dropping one it lacks) changes nothing. An item carries at most 20 tags. Every id is checked first, so a wrong id or a full item changes nothing. Tags never change what a screen plays and need no confirmation. The result counts the links added and removed. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "ids": {
   "minItems": 1,
   "maxItems": 200,
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
   },
   "description": "The screen ids, at most 200."
  },
  "add": {
   "description": "Tag ids to put on every one of them (from tags_list; create a missing tag with tags_create first).",
   "maxItems": 20,
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
   }
  },
  "drop": {
   "description": "Tag ids to take off every one of them.",
   "maxItems": 20,
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
   }
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "ids",
  "merchant"
 ]
}

devices_rename寫入（螢幕不會改變）

Renames a screen. Ask which screen first unless the merchant has only one, and say the old and new name before renaming. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "name": {
   "type": "string",
   "maxLength": 500
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "id",
  "name",
  "merchant"
 ]
}

devices_request_screenshot寫入（螢幕不會改變）

Asks a screen for a screenshot of what it shows; the screen answers within about 20 seconds. A second request while one is pending returns that one. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  },
  "wait": {
   "description": "Seconds to wait for the picture (at most 30); it comes back attached when it arrives in time. 0 or omitted = return at once.",
   "type": "integer",
   "minimum": 0,
   "maximum": 30
  }
 },
 "required": [
  "id",
  "merchant"
 ]
}

playlists_create寫入（螢幕不會改變）

Creates an empty playlist. The same caller-supplied id replays instead of creating a second one. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "name": {
   "type": "string",
   "maxLength": 500
  },
  "id": {
   "type": "string",
   "maxLength": 36
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "name",
  "merchant"
 ]
}

playlists_save_items寫入（螢幕不會改變）

Replaces a playlist's items and their play durations. trimDb (videos only, whole dB −12…+12) turns a video up or down on top of the automatic volume; omitted keeps what the same video had, so leave it out unless the person asks to change a video's volume. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "items": {
   "maxItems": 1000,
   "type": "array",
   "items": {
    "type": "object",
    "properties": {
     "mediaId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
     },
     "duration": {
      "anyOf": [
       {
        "type": "number",
        "exclusiveMinimum": 0,
        "maximum": 86400
       },
       {
        "type": "null"
       }
      ]
     },
     "trimDb": {
      "anyOf": [
       {
        "type": "integer",
        "minimum": -12,
        "maximum": 12
       },
       {
        "type": "null"
       }
      ]
     }
    },
    "required": [
     "mediaId",
     "duration"
    ]
   }
  },
  "expectedUpdatedAt": {
   "type": "string",
   "format": "date-time",
   "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "id",
  "items",
  "merchant"
 ]
}

schedules_create寫入（螢幕不會改變）

Creates a named schedule of dates, hours and weekdays. For different hours on different days (e.g. Tue 09:00–12:00 and Wed 12:00–18:00), pass `windows` (non-overlapping) and leave daysOfWeek/startTime/endTime null. The same caller-supplied id replays. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "name": {
   "type": "string",
   "maxLength": 500
  },
  "timezone": {
   "anyOf": [
    {
     "type": "string",
     "maxLength": 100
    },
    {
     "type": "null"
    }
   ]
  },
  "startDate": {
   "anyOf": [
    {
     "type": "string",
     "maxLength": 100
    },
    {
     "type": "null"
    }
   ]
  },
  "endDate": {
   "anyOf": [
    {
     "type": "string",
     "maxLength": 100
    },
    {
     "type": "null"
    }
   ]
  },
  "startTime": {
   "anyOf": [
    {
     "type": "string",
     "maxLength": 100
    },
    {
     "type": "null"
    }
   ]
  },
  "endTime": {
   "anyOf": [
    {
     "type": "string",
     "maxLength": 100
    },
    {
     "type": "null"
    }
   ]
  },
  "daysOfWeek": {
   "anyOf": [
    {
     "maxItems": 7,
     "type": "array",
     "items": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
     }
    },
    {
     "type": "null"
    }
   ],
   "description": "ISO weekdays: 1 = Monday … 7 = Sunday (0 is not a day); null = every day."
  },
  "windows": {
   "anyOf": [
    {
     "maxItems": 14,
     "type": "array",
     "items": {
      "type": "object",
      "properties": {
       "daysOfWeek": {
        "anyOf": [
         {
          "maxItems": 7,
          "type": "array",
          "items": {
           "type": "integer",
           "minimum": -9007199254740991,
           "maximum": 9007199254740991
          }
         },
         {
          "type": "null"
         }
        ],
        "description": "ISO weekdays: 1 = Monday … 7 = Sunday (0 is not a day); null = every day."
       },
       "startTime": {
        "anyOf": [
         {
          "type": "string",
          "maxLength": 100
         },
         {
          "type": "null"
         }
        ]
       },
       "endTime": {
        "anyOf": [
         {
          "type": "string",
          "maxLength": 100
         },
         {
          "type": "null"
         }
        ]
       }
      },
      "required": [
       "daysOfWeek",
       "startTime",
       "endTime"
      ]
     }
    },
    {
     "type": "null"
    }
   ]
  },
  "id": {
   "type": "string",
   "maxLength": 36
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "name",
  "timezone",
  "startDate",
  "endDate",
  "startTime",
  "endTime",
  "daysOfWeek",
  "merchant"
 ]
}

schedules_update寫入（螢幕不會改變）

Replaces a schedule's name, dates, hours and weekdays. Leaving out `windows` keeps the schedule's windows. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "name": {
   "type": "string",
   "maxLength": 500
  },
  "timezone": {
   "anyOf": [
    {
     "type": "string",
     "maxLength": 100
    },
    {
     "type": "null"
    }
   ]
  },
  "startDate": {
   "anyOf": [
    {
     "type": "string",
     "maxLength": 100
    },
    {
     "type": "null"
    }
   ]
  },
  "endDate": {
   "anyOf": [
    {
     "type": "string",
     "maxLength": 100
    },
    {
     "type": "null"
    }
   ]
  },
  "startTime": {
   "anyOf": [
    {
     "type": "string",
     "maxLength": 100
    },
    {
     "type": "null"
    }
   ]
  },
  "endTime": {
   "anyOf": [
    {
     "type": "string",
     "maxLength": 100
    },
    {
     "type": "null"
    }
   ]
  },
  "daysOfWeek": {
   "anyOf": [
    {
     "maxItems": 7,
     "type": "array",
     "items": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
     }
    },
    {
     "type": "null"
    }
   ],
   "description": "ISO weekdays: 1 = Monday … 7 = Sunday (0 is not a day); null = every day."
  },
  "windows": {
   "anyOf": [
    {
     "maxItems": 14,
     "type": "array",
     "items": {
      "type": "object",
      "properties": {
       "daysOfWeek": {
        "anyOf": [
         {
          "maxItems": 7,
          "type": "array",
          "items": {
           "type": "integer",
           "minimum": -9007199254740991,
           "maximum": 9007199254740991
          }
         },
         {
          "type": "null"
         }
        ],
        "description": "ISO weekdays: 1 = Monday … 7 = Sunday (0 is not a day); null = every day."
       },
       "startTime": {
        "anyOf": [
         {
          "type": "string",
          "maxLength": 100
         },
         {
          "type": "null"
         }
        ]
       },
       "endTime": {
        "anyOf": [
         {
          "type": "string",
          "maxLength": 100
         },
         {
          "type": "null"
         }
        ]
       }
      },
      "required": [
       "daysOfWeek",
       "startTime",
       "endTime"
      ]
     }
    },
    {
     "type": "null"
    }
   ]
  },
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "expectedUpdatedAt": {
   "type": "string",
   "format": "date-time",
   "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "name",
  "timezone",
  "startDate",
  "endDate",
  "startTime",
  "endTime",
  "daysOfWeek",
  "id",
  "merchant"
 ]
}

deployments_save_and_review寫入（螢幕不會改變）

Saves the campaign wizard as a draft and returns its review before publishing: screens, hours (one or several weekly windows) and flight. Saving does not change any screen; to put it on screens, call deployments_publish with the draftId. Hours give the campaign a schedule of its own (kept while its hours stay the same); it is never shared with another campaign unless you pass that campaign's scheduleId, which only do when the person asks to use the same hours as it. scheduleSharedWith names the other campaigns on the schedule; tell the person, since editing a shared schedule later (schedules_update) changes them too at their next publish. Content: pass items (the campaign's own content, the default; no playlist needed) or playlistId (a shared playlist, only when the person asks to reuse one). description, if given, sets the campaign's description (a note about what it is for; it replaces the old text, which the audit log keeps; leave it out to keep what is there). The review's expiringMedia lists media whose expiry date is before the flight ends, or any dated media when the flight has no end. It never blocks; tell the person, and suggest ending the flight on the earliest expiresOn that has not passed. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "draftId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "lineageId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "name": {
   "type": "string",
   "maxLength": 500
  },
  "playlistId": {
   "description": "A shared playlist (playlists_list). Only when the person asks to reuse one; otherwise pass items.",
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "items": {
   "description": "The campaign's own content, in play order: media ids from media_library, each with seconds to show it (null or omitted = the media's own length; images then show for the default time). Use this or playlistId. Saving again with items replaces the campaign's content; it never touches a shared playlist or another campaign. trimDb (videos only, whole dB −12…+12) turns a video up or down on top of the automatic volume; omitted keeps what the same video had, so leave it out unless the person asks to change a video's volume.",
   "minItems": 1,
   "maxItems": 500,
   "type": "array",
   "items": {
    "type": "object",
    "properties": {
     "mediaId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
     },
     "duration": {
      "anyOf": [
       {
        "type": "number",
        "exclusiveMinimum": 0,
        "maximum": 86400
       },
       {
        "type": "null"
       }
      ]
     },
     "trimDb": {
      "anyOf": [
       {
        "type": "integer",
        "minimum": -12,
        "maximum": 12
       },
       {
        "type": "null"
       }
      ]
     }
    },
    "required": [
     "mediaId"
    ]
   }
  },
  "portraitPlaylistId": {
   "anyOf": [
    {
     "type": "string",
     "format": "uuid",
     "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    {
     "type": "null"
    }
   ]
  },
  "scheduleId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "hours": {
   "description": "When it plays each week: null = all day, every day; one window; or an array of windows that do not overlap, e.g. weekdays 11:00-14:00 and 17:00-21:00 plus weekends 10:00-22:00. Use this or scheduleId.",
   "anyOf": [
    {
     "anyOf": [
      {
       "type": "object",
       "properties": {
        "days": {
         "maxItems": 7,
         "type": "array",
         "items": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
         },
         "description": "Weekdays, ISO numbering: 1 = Monday … 7 = Sunday (0 is not a day)."
        },
        "start": {
         "type": "string",
         "maxLength": 5,
         "description": "HH:MM, in each screen's local time."
        },
        "end": {
         "type": "string",
         "maxLength": 5,
         "description": "HH:MM; earlier than start means the window runs past midnight."
        }
       },
       "required": [
        "days",
        "start",
        "end"
       ]
      },
      {
       "minItems": 1,
       "maxItems": 14,
       "type": "array",
       "items": {
        "type": "object",
        "properties": {
         "days": {
          "maxItems": 7,
          "type": "array",
          "items": {
           "type": "integer",
           "minimum": -9007199254740991,
           "maximum": 9007199254740991
          },
          "description": "Weekdays, ISO numbering: 1 = Monday … 7 = Sunday (0 is not a day)."
         },
         "start": {
          "type": "string",
          "maxLength": 5,
          "description": "HH:MM, in each screen's local time."
         },
         "end": {
          "type": "string",
          "maxLength": 5,
          "description": "HH:MM; earlier than start means the window runs past midnight."
         }
        },
        "required": [
         "days",
         "start",
         "end"
        ]
       }
      }
     ]
    },
    {
     "type": "null"
    }
   ]
  },
  "deviceIds": {
   "maxItems": 1000,
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
   },
   "description": "Screens named directly, by id from devices_list ([] when the campaign targets only whole locations). When editing a campaign, start from its targetRefs.deviceIds (deployments_lineage), not its targets: targets are the screens it reaches today, including those of its locations, and naming them would keep them playing after they leave the location."
  },
  "locationIds": {
   "description": "Whole locations, by id from locations_list: every active screen there plays the campaign, including screens paired or moved there later, and a screen moved out stops. Use this when the person means a store or site rather than particular screens. Omitted keeps the campaign's locations as they are; [] removes them.",
   "maxItems": 200,
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
   }
  },
  "description": {
   "anyOf": [
    {
     "type": "string",
     "maxLength": 2000
    },
    {
     "type": "null"
    }
   ],
   "description": "Plain text for colleagues and AI tools, at most 1000 characters, never shown on a screen. null or an empty text clears it."
  },
  "mode": {
   "type": "string",
   "enum": [
    "rotate",
    "filler",
    "takeover"
   ]
  },
  "saturation": {
   "type": "number",
   "minimum": 0.1,
   "maximum": 10
  },
  "playUnit": {
   "type": "string",
   "enum": [
    "item",
    "playlist"
   ]
  },
  "flightStart": {
   "description": "Flight start: YYYY-MM-DD (from the start of that day) or YYYY-MM-DDTHH:MM. Each screen's local wall-clock time (its location's time zone), never UTC; no offset or Z. null or omitted = no start: it plays from the moment it is published.",
   "anyOf": [
    {
     "type": "string",
     "maxLength": 20
    },
    {
     "type": "null"
    }
   ]
  },
  "flightEnd": {
   "description": "Flight end: YYYY-MM-DD (through the end of that day) or YYYY-MM-DDTHH:MM (until that time). Each screen's local wall-clock time (its location's time zone), never UTC; no offset or Z. null = no end.",
   "anyOf": [
    {
     "type": "string",
     "maxLength": 20
    },
    {
     "type": "null"
    }
   ]
  },
  "expectedUpdatedAt": {
   "type": "string",
   "format": "date-time",
   "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "name",
  "deviceIds",
  "merchant"
 ]
}

deployments_copy_to_own_content寫入（螢幕不會改變）

Copies what a live campaign plays into content of its own ("only change this campaign") and starts its next version with it. Requires "merchant" (call merchants_list first).

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "lineageId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  }
 },
 "required": [
  "lineageId",
  "merchant"
 ]
}

deployments_publish改變螢幕（需要確認）

Publishes a campaign draft to its screens. Requires "merchant" (call merchants_list first). Changes what screens show, so the person confirms it first: in your tool's dialog, or, if the result is needs_chat_confirmation, by replying with its code; then call this tool again with the same arguments plus chatConfirmation: { token: <confirmationToken>, code: <what the person typed> }.

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "draftId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "expectedReviewHash": {
   "type": "string",
   "pattern": "^[0-9a-f]{64}$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  },
  "chatConfirmation": {
   "description": "Only when a previous call returned needs_chat_confirmation.",
   "type": "object",
   "properties": {
    "token": {
     "type": "string",
     "maxLength": 4000
    },
    "code": {
     "type": "string",
     "maxLength": 20
    }
   },
   "required": [
    "token",
    "code"
   ]
  }
 },
 "required": [
  "draftId",
  "merchant"
 ]
}

deployments_start_announcement改變螢幕（需要確認）

Starts a full-screen announcement: one piece of media takes the chosen screens over until its end time. Requires "merchant" (call merchants_list first). Changes what screens show, so the person confirms it first: in your tool's dialog, or, if the result is needs_chat_confirmation, by replying with its code; then call this tool again with the same arguments plus chatConfirmation: { token: <confirmationToken>, code: <what the person typed> }.

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "name": {
   "type": "string",
   "maxLength": 500
  },
  "mediaId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "deviceIds": {
   "maxItems": 1000,
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
   },
   "description": "Screens named directly, by id from devices_list ([] when only whole locations)."
  },
  "locationIds": {
   "description": "Whole locations, by id from locations_list: every active screen there shows the announcement, including screens paired there before it ends.",
   "maxItems": 200,
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
   }
  },
  "flightStart": {
   "description": "Flight start: YYYY-MM-DD (from the start of that day) or YYYY-MM-DDTHH:MM. Each screen's local wall-clock time (its location's time zone), never UTC; no offset or Z. null or omitted = no start: it plays from the moment it is published.",
   "anyOf": [
    {
     "type": "string",
     "maxLength": 20
    },
    {
     "type": "null"
    }
   ]
  },
  "flightEnd": {
   "type": "string",
   "maxLength": 20,
   "description": "Flight end: YYYY-MM-DD (through the end of that day) or YYYY-MM-DDTHH:MM (until that time). Each screen's local wall-clock time (its location's time zone), never UTC; no offset or Z. Required: an announcement always ends by itself."
  },
  "lineageId": {
   "type": "string",
   "maxLength": 36
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  },
  "chatConfirmation": {
   "description": "Only when a previous call returned needs_chat_confirmation.",
   "type": "object",
   "properties": {
    "token": {
     "type": "string",
     "maxLength": 4000
    },
    "code": {
     "type": "string",
     "maxLength": 20
    }
   },
   "required": [
    "token",
    "code"
   ]
  }
 },
 "required": [
  "name",
  "mediaId",
  "deviceIds",
  "flightEnd",
  "merchant"
 ]
}

deployments_withdraw改變螢幕（需要確認）

Withdraws a published campaign from its screens. Requires "merchant" (call merchants_list first). Changes what screens show, so the person confirms it first: in your tool's dialog, or, if the result is needs_chat_confirmation, by replying with its code; then call this tool again with the same arguments plus chatConfirmation: { token: <confirmationToken>, code: <what the person typed> }.

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "lineageId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  },
  "chatConfirmation": {
   "description": "Only when a previous call returned needs_chat_confirmation.",
   "type": "object",
   "properties": {
    "token": {
     "type": "string",
     "maxLength": 4000
    },
    "code": {
     "type": "string",
     "maxLength": 20
    }
   },
   "required": [
    "token",
    "code"
   ]
  }
 },
 "required": [
  "lineageId",
  "merchant"
 ]
}

deployments_republish_latest改變螢幕（需要確認）

Publishes the next version of a live campaign with its playlist as it is now. Requires "merchant" (call merchants_list first). Changes what screens show, so the person confirms it first: in your tool's dialog, or, if the result is needs_chat_confirmation, by replying with its code; then call this tool again with the same arguments plus chatConfirmation: { token: <confirmationToken>, code: <what the person typed> }.

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "lineageId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "expectedReviewHash": {
   "type": "string",
   "pattern": "^[0-9a-f]{64}$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  },
  "chatConfirmation": {
   "description": "Only when a previous call returned needs_chat_confirmation.",
   "type": "object",
   "properties": {
    "token": {
     "type": "string",
     "maxLength": 4000
    },
    "code": {
     "type": "string",
     "maxLength": 20
    }
   },
   "required": [
    "token",
    "code"
   ]
  }
 },
 "required": [
  "lineageId",
  "merchant"
 ]
}

deployments_republish_latest_many改變螢幕（需要確認）

Publishes the next version of several live campaigns (up to 20) with their playlist and schedule as they are now, after one confirmation. Every campaign is reviewed first and one with a problem refuses the whole call. Each campaign is published in its own atomic step: if one fails midway, the ones before it stay published and the error says which. Requires "merchant" (call merchants_list first). Changes what screens show, so the person confirms it first: in your tool's dialog, or, if the result is needs_chat_confirmation, by replying with its code; then call this tool again with the same arguments plus chatConfirmation: { token: <confirmationToken>, code: <what the person typed> }.

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "lineageIds": {
   "minItems": 1,
   "maxItems": 20,
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
   }
  },
  "expectedReviewHash": {
   "description": "Leave this out; the confirmation sets it.",
   "type": "string",
   "pattern": "^[0-9a-f]{64}$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  },
  "chatConfirmation": {
   "description": "Only when a previous call returned needs_chat_confirmation.",
   "type": "object",
   "properties": {
    "token": {
     "type": "string",
     "maxLength": 4000
    },
    "code": {
     "type": "string",
     "maxLength": 20
    }
   },
   "required": [
    "token",
    "code"
   ]
  }
 },
 "required": [
  "lineageIds",
  "merchant"
 ]
}

deployments_publish_own_content改變螢幕（需要確認）

Publishes a campaign's own content as it is now; no other campaign changes. Requires "merchant" (call merchants_list first). Changes what screens show, so the person confirms it first: in your tool's dialog, or, if the result is needs_chat_confirmation, by replying with its code; then call this tool again with the same arguments plus chatConfirmation: { token: <confirmationToken>, code: <what the person typed> }.

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "lineageId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "expectedReviewHash": {
   "type": "string",
   "pattern": "^[0-9a-f]{64}$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  },
  "chatConfirmation": {
   "description": "Only when a previous call returned needs_chat_confirmation.",
   "type": "object",
   "properties": {
    "token": {
     "type": "string",
     "maxLength": 4000
    },
    "code": {
     "type": "string",
     "maxLength": 20
    }
   },
   "required": [
    "token",
    "code"
   ]
  }
 },
 "required": [
  "lineageId",
  "merchant"
 ]
}

deployments_restore_version改變螢幕（需要確認）

Puts a campaign back to an earlier version: publishes a new version with exactly that version's content, screens, hours, flight and mode (also the undo of a withdrawal). The earlier version is not changed. Refused when the version is already live, the campaign has a draft, or something it needs is gone (media, a screen). Requires "merchant" (call merchants_list first). Changes what screens show, so the person confirms it first: in your tool's dialog, or, if the result is needs_chat_confirmation, by replying with its code; then call this tool again with the same arguments plus chatConfirmation: { token: <confirmationToken>, code: <what the person typed> }.

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "lineageId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "version": {
   "type": "integer",
   "minimum": 1,
   "maximum": 9007199254740991,
   "description": "The version number to bring back, from deployments_lineage."
  },
  "expectedReviewHash": {
   "type": "string",
   "pattern": "^[0-9a-f]{64}$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  },
  "chatConfirmation": {
   "description": "Only when a previous call returned needs_chat_confirmation.",
   "type": "object",
   "properties": {
    "token": {
     "type": "string",
     "maxLength": 4000
    },
    "code": {
     "type": "string",
     "maxLength": 20
    }
   },
   "required": [
    "token",
    "code"
   ]
  }
 },
 "required": [
  "lineageId",
  "version",
  "merchant"
 ]
}

devices_set_operating_hours改變螢幕（需要確認）

Sets the weekly opening hours of one or more screens (null = not set, [] = set, closed all week). They feed the airtime report; screens play the same either way. Each window's times are "HH:MM", with daysOfWeek ISO 1 (Monday) to 7 (Sunday) or null for every day and both times null for all day; a start later than the end runs overnight and belongs to the day it starts, and windows are read in the screen's location timezone. Requires "merchant" (call merchants_list first). Changes what screens show, so the person confirms it first: in your tool's dialog, or, if the result is needs_chat_confirmation, by replying with its code; then call this tool again with the same arguments plus chatConfirmation: { token: <confirmationToken>, code: <what the person typed> }.

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "ids": {
   "minItems": 1,
   "maxItems": 200,
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
   }
  },
  "hours": {
   "anyOf": [
    {
     "maxItems": 14,
     "type": "array",
     "items": {
      "type": "object",
      "properties": {
       "daysOfWeek": {
        "anyOf": [
         {
          "type": "array",
          "items": {
           "type": "integer",
           "minimum": -9007199254740991,
           "maximum": 9007199254740991
          }
         },
         {
          "type": "null"
         }
        ]
       },
       "startTime": {
        "type": [
         "string",
         "null"
        ]
       },
       "endTime": {
        "type": [
         "string",
         "null"
        ]
       }
      },
      "required": [
       "daysOfWeek",
       "startTime",
       "endTime"
      ]
     }
    },
    {
     "type": "null"
    }
   ]
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  },
  "chatConfirmation": {
   "description": "Only when a previous call returned needs_chat_confirmation.",
   "type": "object",
   "properties": {
    "token": {
     "type": "string",
     "maxLength": 4000
    },
    "code": {
     "type": "string",
     "maxLength": 20
    }
   },
   "required": [
    "token",
    "code"
   ]
  }
 },
 "required": [
  "ids",
  "hours",
  "merchant"
 ]
}

devices_set_audio改變螢幕（需要確認）

Turns sound on or off for the videos on a screen. Requires "merchant" (call merchants_list first). Changes what screens show, so the person confirms it first: in your tool's dialog, or, if the result is needs_chat_confirmation, by replying with its code; then call this tool again with the same arguments plus chatConfirmation: { token: <confirmationToken>, code: <what the person typed> }.

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "audio": {
   "type": "boolean"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  },
  "chatConfirmation": {
   "description": "Only when a previous call returned needs_chat_confirmation.",
   "type": "object",
   "properties": {
    "token": {
     "type": "string",
     "maxLength": 4000
    },
    "code": {
     "type": "string",
     "maxLength": 20
    }
   },
   "required": [
    "token",
    "code"
   ]
  }
 },
 "required": [
  "id",
  "audio",
  "merchant"
 ]
}

devices_set_orientation改變螢幕（需要確認）

Fixes whether a screen plays a campaign's portrait or landscape content, whatever the player reports; null follows the player's report again (unknown plays as landscape). Requires "merchant" (call merchants_list first). Changes what screens show, so the person confirms it first: in your tool's dialog, or, if the result is needs_chat_confirmation, by replying with its code; then call this tool again with the same arguments plus chatConfirmation: { token: <confirmationToken>, code: <what the person typed> }.

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "orientation": {
   "anyOf": [
    {
     "type": "string",
     "enum": [
      "landscape",
      "portrait"
     ]
    },
    {
     "type": "null"
    }
   ]
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  },
  "chatConfirmation": {
   "description": "Only when a previous call returned needs_chat_confirmation.",
   "type": "object",
   "properties": {
    "token": {
     "type": "string",
     "maxLength": 4000
    },
    "code": {
     "type": "string",
     "maxLength": 20
    }
   },
   "required": [
    "token",
    "code"
   ]
  }
 },
 "required": [
  "id",
  "orientation",
  "merchant"
 ]
}

devices_set_rotation改變螢幕（需要確認）

Sets how many degrees clockwise (0, 90, 180, 270) the player turns its whole output, for a screen mounted turned; players that can turn then show portrait content on a landscape panel and the other way round. Requires "merchant" (call merchants_list first). Changes what screens show, so the person confirms it first: in your tool's dialog, or, if the result is needs_chat_confirmation, by replying with its code; then call this tool again with the same arguments plus chatConfirmation: { token: <confirmationToken>, code: <what the person typed> }.

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "rotation": {
   "anyOf": [
    {
     "type": "number",
     "const": 0
    },
    {
     "type": "number",
     "const": 90
    },
    {
     "type": "number",
     "const": 180
    },
    {
     "type": "number",
     "const": 270
    }
   ]
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  },
  "chatConfirmation": {
   "description": "Only when a previous call returned needs_chat_confirmation.",
   "type": "object",
   "properties": {
    "token": {
     "type": "string",
     "maxLength": 4000
    },
    "code": {
     "type": "string",
     "maxLength": 20
    }
   },
   "required": [
    "token",
    "code"
   ]
  }
 },
 "required": [
  "id",
  "rotation",
  "merchant"
 ]
}

devices_claim改變螢幕（需要確認）

Pairs a screen by its pairing code and places it at a location. It starts playing at once whatever is aimed at that location as a whole (campaigns and full-screen announcements), so an AI tool's pairing is confirmed by a person, who sees what will start (owner decision 2026-10-12). Codes expire after a few minutes; the screen then shows a new one. Requires "merchant" (call merchants_list first). Changes what screens show, so the person confirms it first: in your tool's dialog, or, if the result is needs_chat_confirmation, by replying with its code; then call this tool again with the same arguments plus chatConfirmation: { token: <confirmationToken>, code: <what the person typed> }.

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "code": {
   "type": "string",
   "maxLength": 20
  },
  "name": {
   "type": "string",
   "maxLength": 500
  },
  "locationId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  },
  "chatConfirmation": {
   "description": "Only when a previous call returned needs_chat_confirmation.",
   "type": "object",
   "properties": {
    "token": {
     "type": "string",
     "maxLength": 4000
    },
    "code": {
     "type": "string",
     "maxLength": 20
    }
   },
   "required": [
    "token",
    "code"
   ]
  }
 },
 "required": [
  "code",
  "name",
  "locationId",
  "merchant"
 ]
}

devices_request_restart改變螢幕（需要確認）

Restarts a screen's player (not the device): the picture goes dark for about 5-10 seconds, then the same content plays on. The screen picks it up within about 20 seconds; the request expires after 2 minutes (e.g. offline). A second request while one is pending returns that one; otherwise a screen can be restarted at most once every 5 minutes, and only when its player version supports it (devices_get: capabilities includes "restart"). Requires "merchant" (call merchants_list first). Changes what screens show, so the person confirms it first: in your tool's dialog, or, if the result is needs_chat_confirmation, by replying with its code; then call this tool again with the same arguments plus chatConfirmation: { token: <confirmationToken>, code: <what the person typed> }.

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  },
  "chatConfirmation": {
   "description": "Only when a previous call returned needs_chat_confirmation.",
   "type": "object",
   "properties": {
    "token": {
     "type": "string",
     "maxLength": 4000
    },
    "code": {
     "type": "string",
     "maxLength": 20
    }
   },
   "required": [
    "token",
    "code"
   ]
  }
 },
 "required": [
  "id",
  "merchant"
 ]
}

reports_create_share_link改變螢幕（需要確認）

Creates a revocable share link to a campaign's proof-of-play report. expiresAt is a YYYY-MM-DD local date, stored as the end of that day in UTC, or null for a link that never expires. For an AI tool the link always expires: 30 days from today when left out, at most 365 days. Requires "merchant" (call merchants_list first). Changes what screens show, so the person confirms it first: in your tool's dialog, or, if the result is needs_chat_confirmation, by replying with its code; then call this tool again with the same arguments plus chatConfirmation: { token: <confirmationToken>, code: <what the person typed> }.

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "lineageId": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "expiresAt": {
   "anyOf": [
    {
     "type": "string",
     "maxLength": 100
    },
    {
     "type": "null"
    }
   ]
  },
  "id": {
   "type": "string",
   "maxLength": 36
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  },
  "chatConfirmation": {
   "description": "Only when a previous call returned needs_chat_confirmation.",
   "type": "object",
   "properties": {
    "token": {
     "type": "string",
     "maxLength": 4000
    },
    "code": {
     "type": "string",
     "maxLength": 20
    }
   },
   "required": [
    "token",
    "code"
   ]
  }
 },
 "required": [
  "lineageId",
  "merchant"
 ]
}

reports_revoke_share_link改變螢幕（需要確認）

Revokes a share link so its URL stops working. An AI tool can revoke only links its owner created (in DRMN or through any of their keys). Requires "merchant" (call merchants_list first). Changes what screens show, so the person confirms it first: in your tool's dialog, or, if the result is needs_chat_confirmation, by replying with its code; then call this tool again with the same arguments plus chatConfirmation: { token: <confirmationToken>, code: <what the person typed> }.

參數 schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "merchant": {
   "type": "string",
   "minLength": 1,
   "maxLength": 100,
   "description": "The merchant's short name (slug) from merchants_list."
  },
  "chatConfirmation": {
   "description": "Only when a previous call returned needs_chat_confirmation.",
   "type": "object",
   "properties": {
    "token": {
     "type": "string",
     "maxLength": 4000
    },
    "code": {
     "type": "string",
     "maxLength": 20
    }
   },
   "required": [
    "token",
    "code"
   ]
  }
 },
 "required": [
  "id",
  "merchant"
 ]
}

Skill

一份 SKILL.md，教 AI 認識用語、安全的流程與錯誤處理：

https://digicms-cms.nichiahung.workers.dev/ai/skill/SKILL.md