{ "openapi": "3.1.0", "info": { "title": "Ztalio API", "version": "1.0.0", "summary": "Manage your Ztalio screens, playlists and library from scripts and AI assistants.", "description": "Authenticate with an API key from ztalio.com → Settings → API access (included with the Pro and Network plans). Send it as `Authorization: Bearer ztk_…`. Keys carry scopes: read, write, push. Limit: 120 requests per minute per key. Also accepted: `x-api-key: ztk_…`.", "contact": { "email": "support@ztalio.com", "url": "https://ztalio.com/developers" } }, "servers": [ { "url": "https://api.ztalio.com/v1" } ], "security": [ { "apiKey": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "ztk_…" } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "NO_KEY", "BAD_KEY", "REVOKED_KEY", "NO_ACCOUNT", "UPGRADE_REQUIRED", "SCOPE", "NOT_FOUND", "RATE_LIMITED", "UPSTREAM" ] }, "upgrade": { "type": "string" }, "upgradeUrl": { "type": "string" }, "required": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "Screen": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "roku_80494493-1692-4899-912a-9bb52ce5cd9" ] }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "paired", "unlinked" ] }, "online": { "type": "boolean", "description": "seen in the last 3 minutes" }, "lastSeenAt": { "type": [ "string", "null" ], "format": "date-time" }, "linkedAt": { "type": [ "string", "null" ], "format": "date-time" }, "nowPlaying": { "type": [ "object", "null" ], "properties": { "itemCount": { "type": "integer" }, "firstItem": { "type": [ "string", "null" ] }, "transition": { "type": [ "string", "null" ] }, "slideSeconds": { "type": [ "integer", "null" ] }, "pushedAt": { "type": [ "string", "null" ] } } } } }, "Playlist": { "type": "object", "properties": { "playlistId": { "type": "string" }, "name": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "s3Key": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "mediaType": { "type": [ "string", "null" ], "enum": [ "image", "video", "audio", null ] } } } }, "shuffleEnabled": { "type": "boolean" }, "backgroundMusicS3Key": { "type": [ "string", "null" ] }, "schedule": { "type": [ "object", "null" ], "description": "{ rules: [{ days, startHour, endHour, … }] } — see the web app" }, "transition": { "type": "string", "enum": [ "none", "dissolve", "slide", "flip", "zoom" ] }, "slideSeconds": { "type": [ "integer", "null" ], "minimum": 2, "maximum": 3600 }, "updatedAt": { "type": "string" } } }, "MediaItem": { "type": "object", "properties": { "id": { "type": "string" }, "s3Key": { "type": "string", "description": "use this in playlist items and pushes" }, "thumbKey": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "folderId": { "type": "string" }, "mediaType": { "type": "string", "enum": [ "image", "video", "audio" ] }, "size": { "type": "integer" }, "createdAt": { "type": "string" } } }, "PushRequest": { "type": "object", "description": "Either playlistId or items[]", "properties": { "playlistId": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "image", "video" ] }, "title": { "type": "string" } } } }, "transition": { "type": "string", "enum": [ "none", "dissolve", "slide", "flip", "zoom" ] }, "slideSeconds": { "type": "integer", "minimum": 2, "maximum": 3600 } } }, "Account": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "userType": { "type": "string", "enum": [ "primary", "secondary" ] }, "timezone": { "type": [ "string", "null" ], "description": "IANA zone used by playlist schedules" }, "plan": { "type": "string", "enum": [ "pro", "network", "venue" ] }, "resources": { "type": "object", "properties": { "storageGB": { "type": "number" }, "storageUsedBytes": { "type": "integer" }, "displaysLinked": { "type": "integer" }, "displaysLimit": { "type": "integer" }, "usersLinked": { "type": "integer" }, "usersLimit": { "type": [ "integer", "null" ] } } }, "key": { "type": "object", "properties": { "keyId": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "write", "push" ] } } } } } }, "Folder": { "type": "object", "properties": { "folderId": { "type": "string" }, "name": { "type": "string" }, "parentFolderId": { "type": [ "string", "null" ] }, "isShared": { "type": "boolean" }, "isOwner": { "type": "boolean" } } }, "Track": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "artist": { "type": "string" }, "mood": { "type": "string" }, "durationSec": { "type": "integer" }, "s3Key": { "type": "string", "description": "use as backgroundMusicS3Key" } } }, "PushResult": { "type": "object", "properties": { "success": { "type": "boolean" }, "pushedDisplays": { "type": "array", "items": { "type": "string" } }, "failedDisplays": { "type": "array", "items": { "type": "object", "properties": { "displayId": { "type": "string" }, "reason": { "type": "string" } } } } } }, "SlideFields": { "type": "object", "description": "Content for a template. Which fields apply depends on the template (GET /slides/templates).", "properties": { "title": { "type": "string" }, "subtitle": { "type": "string" }, "kicker": { "type": "string", "description": "small label above the title" }, "body": { "type": "string", "description": "paragraph; newlines allowed" }, "badge": { "type": "string", "description": "text inside the round badge (promo)" }, "items": { "type": "array", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "price": { "type": "string" }, "desc": { "type": "string" }, "tag": { "type": "string" } } } }, "logo": { "type": "string", "description": "library key (s3Key) of your logo" }, "photo": { "type": "string", "description": "library key of a photo" }, "accent": { "type": "string", "description": "#RRGGBB" }, "font": { "type": "string", "enum": [ "Inter", "Playfair Display", "Bebas Neue", "Lora", "Montserrat" ] }, "name": { "type": "string", "description": "file title in the library" } } }, "SlideRequest": { "type": "object", "description": "Either template + fields, or a complete Studio doc.", "properties": { "template": { "type": "string", "enum": [ "menu-board", "price-list", "promo", "announcement", "hours", "welcome", "event", "portrait-menu" ], "default": "announcement" }, "fields": { "$ref": "#/components/schemas/SlideFields" }, "doc": { "type": "object", "description": "a complete StudioDoc (as returned by /slides/propose)" }, "name": { "type": "string" }, "playlistId": { "type": "string", "description": "append the slide to this playlist" }, "screenIds": { "type": "array", "items": { "type": "string" }, "description": "push the slide to these screens (needs the push scope)" } } }, "SlideResult": { "type": "object", "properties": { "s3Key": { "type": "string", "description": "the library key — use it in playlists and pushes" }, "title": { "type": "string" }, "folderId": { "type": "string" }, "size": { "type": "object", "properties": { "w": { "type": "integer" }, "h": { "type": "integer" } } }, "bytes": { "type": "integer" }, "ready": { "type": "boolean", "description": "true once the processed file is in the library (it always is within a minute)" }, "playlist": { "type": "object" }, "push": { "$ref": "#/components/schemas/PushResult" } } } } }, "paths": { "/me": { "get": { "summary": "The account behind this key", "x-scope": "read", "responses": { "200": { "description": "The account behind this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Account" ], "operationId": "getMe" } }, "/screens": { "get": { "summary": "List screens", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "screens": { "type": "array", "items": { "$ref": "#/components/schemas/Screen" } } } } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Screens" ], "operationId": "getScreens" } }, "/screens/analytics": { "get": { "summary": "Screen uptime analytics (same data as ztalio.com/analytics)", "x-scope": "read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Screens" ], "operationId": "getScreensAnalytics", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 7, "minimum": 1, "maximum": 30 }, "description": "window in days (1–30)" } ], "description": "Same data as ztalio.com/analytics: per screen, on-now, last seen, hours on per day and the usual hours; proof of play per playlist." } }, "/screens/{id}/rename": { "post": { "summary": "Rename a screen", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Renamed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Screens" ], "operationId": "postScreensIdRename" } }, "/screens/{id}/push": { "post": { "summary": "Push a playlist (or ad-hoc items) to one screen; the TV changes within seconds", "x-scope": "push", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushRequest" } } } }, "responses": { "200": { "description": "Pushed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushResult" } } } }, "400": { "description": "Empty playlist / bad body" }, "404": { "description": "Screen not found" }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Screens" ], "operationId": "postScreensIdPush" } }, "/push": { "post": { "summary": "Push to several screens", "x-scope": "push", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PushRequest" }, { "type": "object", "required": [ "screenIds" ], "properties": { "screenIds": { "type": "array", "items": { "type": "string" } } } } ] } } } }, "responses": { "200": { "description": "Pushed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushResult" } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Screens" ], "operationId": "postPush" } }, "/playlists": { "get": { "summary": "List playlists", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Playlist" } } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Playlists" ], "operationId": "getPlaylists" }, "post": { "summary": "Create a playlist", "x-scope": "write", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "playlistId": { "type": "string" }, "name": { "type": "string" } } } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Playlists" ], "operationId": "postPlaylists" } }, "/playlists/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Get a playlist", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Playlist" } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Playlists" ], "operationId": "getPlaylistsId" }, "patch": { "summary": "Update name, speed, transition, shuffle, music or schedule", "x-scope": "write", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "slideSeconds": { "type": "integer", "minimum": 2, "maximum": 3600 }, "transition": { "type": "string", "enum": [ "none", "dissolve", "slide", "flip", "zoom" ] }, "shuffleEnabled": { "type": "boolean" }, "backgroundMusicS3Key": { "type": [ "string", "null" ] }, "schedule": { "type": [ "object", "null" ] } } } } } }, "responses": { "200": { "description": "The updated playlist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Playlist" } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Playlists" ], "operationId": "patchPlaylistsId" }, "delete": { "summary": "Delete a playlist", "x-scope": "write", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Playlists" ], "operationId": "deletePlaylistsId" } }, "/playlists/{id}/items": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Append library items (by s3Key)", "x-scope": "write", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "s3Keys" ], "properties": { "s3Keys": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Appended", "content": { "application/json": { "schema": { "type": "object", "properties": { "added": { "type": "integer" }, "itemsCount": { "type": "integer" } } } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Playlists" ], "operationId": "postPlaylistsIdItems" }, "delete": { "summary": "Remove items (by s3Key)", "x-scope": "write", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "s3Keys" ], "properties": { "s3Keys": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Playlists" ], "operationId": "deletePlaylistsIdItems" } }, "/media": { "get": { "summary": "The library feed: folders and items", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "folders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "itemCount": { "type": "integer" } } } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MediaItem" } } } } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Library" ], "operationId": "getMedia" } }, "/folders": { "get": { "summary": "List folders", "x-scope": "read", "responses": { "200": { "description": "Folders you own or were granted", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Folder" } } } } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Library" ], "operationId": "getFolders" }, "post": { "summary": "Create a folder", "x-scope": "write", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "parentFolderId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder" } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Library" ], "operationId": "postFolders" } }, "/folders/{id}/items": { "get": { "summary": "Items in a folder", "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Items in the folder", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MediaItem" } } } } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Library" ], "operationId": "getFoldersIdItems" } }, "/music": { "get": { "summary": "The built-in background-music library", "x-scope": "read", "responses": { "200": { "description": "The built-in tracks", "content": { "application/json": { "schema": { "type": "object", "properties": { "tracks": { "type": "array", "items": { "$ref": "#/components/schemas/Track" } } } } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Library" ], "operationId": "getMusic" } }, "/uploads": { "post": { "summary": "Start an upload (S3 multipart). Then PUT each part to its URL and call complete.", "x-scope": "write", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "filename", "contentType", "sizeBytes", "totalParts" ], "properties": { "filename": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "totalParts": { "type": "integer", "description": "parts of up to 100 MB" }, "folderId": { "type": "string", "default": "root" } } } } } }, "responses": { "200": { "description": "Upload started", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadId": { "type": "string" }, "s3Key": { "type": "string" }, "totalParts": { "type": "integer" }, "contentType": { "type": "string" }, "folderId": { "type": "string" } } } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Uploads" ], "operationId": "postUploads" } }, "/uploads/{uploadId}/part-urls": { "post": { "summary": "Presigned PUT URLs for parts", "x-scope": "write", "parameters": [ { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "partNumbers" ], "properties": { "partNumbers": { "type": "array", "items": { "type": "integer" } } } } } } }, "responses": { "200": { "description": "Presigned PUT URLs", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadId": { "type": "string" }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer" }, "url": { "type": "string" } } } } } } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Uploads" ], "operationId": "postUploadsUploadIdPartUrls" } }, "/uploads/{uploadId}/complete": { "post": { "summary": "Finish the upload; the file is optimised and appears in the library within a minute", "x-scope": "write", "parameters": [ { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "parts" ], "properties": { "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer" }, "etag": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "Completed; the file is optimised and appears in the library within a minute", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadId": { "type": "string" }, "s3Key": { "type": "string" }, "folderId": { "type": "string" }, "location": { "type": "string" } } } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Uploads" ], "operationId": "postUploadsUploadIdComplete" } }, "/uploads/{uploadId}": { "delete": { "summary": "Abort an upload", "x-scope": "write", "parameters": [ { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Uploads" ], "operationId": "deleteUploadsUploadId" } }, "/slides/templates": { "get": { "tags": [ "Slides" ], "operationId": "getSlidesTemplates", "summary": "The eight slide templates and the fields each accepts", "x-scope": "read", "responses": { "200": { "description": "Templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "blurb": { "type": "string" }, "size": { "type": "object" }, "fields": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/slides/preview": { "post": { "tags": [ "Slides" ], "operationId": "postSlidesPreview", "summary": "Render a slide and return the PNG (base64) without saving it", "x-scope": "read", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideRequest" } } } }, "responses": { "200": { "description": "The PNG", "content": { "application/json": { "schema": { "type": "object", "properties": { "png": { "type": "string", "description": "base64 PNG" }, "size": { "type": "object" }, "bytes": { "type": "integer" }, "doc": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/slides/propose": { "post": { "tags": [ "Slides" ], "operationId": "postSlidesPropose", "summary": "Let the Studio assistant lay a slide out from a sentence (same quotas as ztalio.com/studio)", "x-scope": "write", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string" }, "template": { "type": "string" }, "fields": { "$ref": "#/components/schemas/SlideFields" } } } } } }, "responses": { "200": { "description": "A complete Studio doc to pass to POST /slides as `doc`", "content": { "application/json": { "schema": { "type": "object", "properties": { "doc": { "type": "object" }, "reply": { "type": "string" }, "turnsLeft": { "type": "integer" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The assistant did not produce a slide", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/slides": { "post": { "tags": [ "Slides" ], "operationId": "postSlides", "summary": "Make a slide from text — a menu board, promo, announcement, hours, welcome or event — and save it to the library (folder \"Studio\"); optionally add it to a playlist and push it to screens", "x-scope": "write", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideRequest" } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideResult" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan without API access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (120/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "tags": [ { "name": "Account" }, { "name": "Screens" }, { "name": "Playlists" }, { "name": "Library" }, { "name": "Uploads" }, { "name": "Slides" } ] }