{ "openapi": "3.1.0", "info": { "title": "HiZex Herald API", "version": "1.0.0", "description": "HiZex Herald — producer, identity, inbox, events and webhook endpoints. Units are always derived from the verified credential or session, never from the request body." }, "components": { "securitySchemes": { "producerKey": { "type": "http", "scheme": "bearer", "description": "Per-unit producer credential `hub__`" }, "session": { "type": "apiKey", "in": "cookie", "name": "hub_session", "description": "Console SSO session cookie" }, "lineIdToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "LINE id token (LIFF). Under LINE_MOCK the header `x-mock-line-user` is accepted instead." }, "hmac": { "type": "apiKey", "in": "header", "name": "X-Herald-Signature", "description": "v1=HMAC-SHA256(secret, `${X-Herald-Timestamp}.${rawBody}`) with X-Herald-Key-Id; ±300 s" }, "adapterSignature": { "type": "apiKey", "in": "header", "name": "X-Line-Signature", "description": "Verified by the adapter (LINE: channel secret; mock: `x-mock-signature: ok`)" } }, "schemas": {} }, "paths": { "/v1/messages": { "post": { "summary": "Create a message intent (draft)", "tags": [ "messages" ], "description": "Idempotent on `Idempotency-Key` per unit: a replay returns 200 with the original id. `individual` audiences are for producer credentials with individualTargeting only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "unitId": { "description": "Console users with several units pick one; producers are pinned to their credential", "type": "string" }, "categoryId": { "type": "string", "minLength": 1 }, "templateId": { "type": "string" }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "messages": { "description": "Canonical content; alternative to templateId", "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text" ] }, "text": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "kind", "text" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image" ] }, "url": { "type": "string", "format": "uri" }, "alt": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "previewUrl": { "type": "string", "format": "uri" } }, "required": [ "kind", "url", "alt" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sticker" ] }, "packageId": { "type": "string" }, "stickerId": { "type": "string" }, "fallbackText": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "kind", "packageId", "stickerId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "card" ] }, "header": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "title": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "body": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "imageUrl": { "type": "string", "format": "uri" }, "actions": { "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "uri" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "url": { "type": "string", "format": "uri" } }, "required": [ "kind", "label", "url" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "postback" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "data": { "type": "object", "properties": { "v": { "type": "number", "enum": [ 1 ] }, "s": { "type": "string" }, "n": { "type": "string" }, "o": { "type": "string" }, "m": { "type": "string" }, "a": { "type": "string" } }, "required": [ "v" ] } }, "required": [ "kind", "label", "data" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "nextNode" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "nodeId": { "type": "string" }, "optionId": { "type": "string" } }, "required": [ "kind", "label", "nodeId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "jumpScenario" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "scenarioId": { "type": "string" } }, "required": [ "kind", "label", "scenarioId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mute" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "categoryId": { "type": "string" } }, "required": [ "kind", "label", "categoryId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "addToGroup" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "groupId": { "type": "string" } }, "required": [ "kind", "label", "groupId" ] } ] } }, "lockedReason": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "kind", "title", "actions" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "carousel" ] }, "cards": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "card" ] }, "header": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "title": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "body": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "imageUrl": { "type": "string", "format": "uri" }, "actions": { "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "uri" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "url": { "type": "string", "format": "uri" } }, "required": [ "kind", "label", "url" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "postback" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "data": { "type": "object", "properties": { "v": { "type": "number", "enum": [ 1 ] }, "s": { "type": "string" }, "n": { "type": "string" }, "o": { "type": "string" }, "m": { "type": "string" }, "a": { "type": "string" } }, "required": [ "v" ] } }, "required": [ "kind", "label", "data" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "nextNode" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "nodeId": { "type": "string" }, "optionId": { "type": "string" } }, "required": [ "kind", "label", "nodeId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "jumpScenario" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "scenarioId": { "type": "string" } }, "required": [ "kind", "label", "scenarioId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mute" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "categoryId": { "type": "string" } }, "required": [ "kind", "label", "categoryId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "addToGroup" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "groupId": { "type": "string" } }, "required": [ "kind", "label", "groupId" ] } ] } }, "lockedReason": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "kind", "title", "actions" ] } } }, "required": [ "kind", "cards" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "buttons" ] }, "text": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "actions": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "uri" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "url": { "type": "string", "format": "uri" } }, "required": [ "kind", "label", "url" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "postback" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "data": { "type": "object", "properties": { "v": { "type": "number", "enum": [ 1 ] }, "s": { "type": "string" }, "n": { "type": "string" }, "o": { "type": "string" }, "m": { "type": "string" }, "a": { "type": "string" } }, "required": [ "v" ] } }, "required": [ "kind", "label", "data" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "nextNode" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "nodeId": { "type": "string" }, "optionId": { "type": "string" } }, "required": [ "kind", "label", "nodeId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "jumpScenario" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "scenarioId": { "type": "string" } }, "required": [ "kind", "label", "scenarioId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mute" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "categoryId": { "type": "string" } }, "required": [ "kind", "label", "categoryId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "addToGroup" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "groupId": { "type": "string" } }, "required": [ "kind", "label", "groupId" ] } ] } } }, "required": [ "kind", "text", "actions" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "quickReply" ] }, "text": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "options": { "minItems": 1, "maxItems": 13, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "id", "label" ] } } }, "required": [ "kind", "text", "options" ] } ] } }, "audience": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "all" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "query" ] }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "student", "teacher", "staff" ] } }, "stages": { "type": "array", "items": { "type": "string", "enum": [ "visitor", "lead", "member", "alumni" ] } }, "orgUnits": { "type": "array", "items": { "type": "string" } }, "classIds": { "type": "array", "items": { "type": "string" } }, "groups": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "history": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "registered" ] }, "patternInstanceId": { "type": "string" } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "notRegistered" ] }, "patternInstanceId": { "type": "string" } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "responded" ] }, "patternInstanceId": { "type": "string" } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "notResponded" ] }, "patternInstanceId": { "type": "string" } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "read" ] }, "messageId": { "type": "string" } }, "required": [ "kind", "messageId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "unread" ] }, "messageId": { "type": "string" } }, "required": [ "kind", "messageId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "acked" ] }, "messageId": { "type": "string" } }, "required": [ "kind", "messageId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "notAcked" ] }, "messageId": { "type": "string" } }, "required": [ "kind", "messageId" ] } ] } }, "lists": { "type": "array", "items": { "type": "string" } }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "line", "email", "webpush", "whatsapp", "messenger" ] } }, "locales": { "type": "array", "items": { "type": "string", "enum": [ "zh-TW", "en" ] } }, "flags": { "type": "array", "items": { "type": "string", "enum": [ "isTutor", "isGraduate" ] } }, "exclude": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "all" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "query" ] }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "student", "teacher", "staff" ] } }, "stages": { "type": "array", "items": { "type": "string", "enum": [ "visitor", "lead", "member", "alumni" ] } }, "orgUnits": { "type": "array", "items": { "type": "string" } }, "classIds": { "type": "array", "items": { "type": "string" } }, "groups": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "history": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "registered" ] }, "patternInstanceId": { "type": "string" } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "notRegistered" ] }, "patternInstanceId": { "type": "string" } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "responded" ] }, "patternInstanceId": { "type": "string" } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "notResponded" ] }, "patternInstanceId": { "type": "string" } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "read" ] }, "messageId": { "type": "string" } }, "required": [ "kind", "messageId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "unread" ] }, "messageId": { "type": "string" } }, "required": [ "kind", "messageId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "acked" ] }, "messageId": { "type": "string" } }, "required": [ "kind", "messageId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "notAcked" ] }, "messageId": { "type": "string" } }, "required": [ "kind", "messageId" ] } ] } }, "lists": { "type": "array", "items": { "type": "string" } }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "line", "email", "webpush", "whatsapp", "messenger" ] } }, "locales": { "type": "array", "items": { "type": "string", "enum": [ "zh-TW", "en" ] } }, "flags": { "type": "array", "items": { "type": "string", "enum": [ "isTutor", "isGraduate" ] } } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "individual" ] }, "uids": { "minItems": 1, "maxItems": 5000, "type": "array", "items": { "type": "string" } } }, "required": [ "kind", "uids" ] } ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "individual" ] }, "uids": { "minItems": 1, "maxItems": 5000, "type": "array", "items": { "type": "string" } } }, "required": [ "kind", "uids" ] } ], "description": "Audience is always a query, resolved at send time" }, "scheduleAt": { "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "ISO 8601 date-time" }, "expiresAt": { "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "ISO 8601 date-time" }, "channelPlanOverride": { "type": "object", "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "line", "email", "webpush", "whatsapp", "messenger" ] } }, "fallback": { "type": "array", "items": { "type": "string", "enum": [ "line", "email", "webpush", "whatsapp", "messenger" ] } }, "fallbackWhen": { "type": "array", "items": { "type": "string", "enum": [ "no_address", "permanent_failure", "quota_exhausted" ] } }, "aggregation": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "immediate" ] } }, "required": [ "mode" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "slot" ] }, "slots": { "minItems": 1, "type": "array", "items": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" } } }, "required": [ "mode", "slots" ] } ] }, "emergency": { "type": "boolean" } }, "description": "May only narrow the category plan (narrowChannelPlan)" }, "kind": { "type": "string", "enum": [ "personal", "digest", "campaign", "emergency" ] }, "topicId": { "description": "Channel topic of the unit; recipients who unsubscribed it are excluded", "type": "string" }, "remindAt": { "description": "Send the same content again at this time to everyone who did not answer 不用提醒; must be after the send time", "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "categoryId", "audience" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "idempotency-key", "required": true, "description": "Caller-chosen key; replays return the original resource" } ], "security": [ { "producerKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "draft", "submitted", "approved", "rejected", "scheduled", "sending", "sent", "cancelled", "expired" ] }, "created": { "type": "boolean" } }, "required": [ "id", "state", "created" ], "additionalProperties": false } } } }, "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "draft", "submitted", "approved", "rejected", "scheduled", "sending", "sent", "cancelled", "expired" ] }, "created": { "type": "boolean" } }, "required": [ "id", "state", "created" ], "additionalProperties": false } } } } } }, "get": { "summary": "List a unit’s messages, newest first", "tags": [ "messages" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "unitId", "required": false }, { "schema": { "type": "string", "enum": [ "draft", "submitted", "approved", "rejected", "scheduled", "sending", "sent", "cancelled", "expired" ] }, "in": "query", "name": "state", "required": false }, { "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 500 }, "in": "query", "name": "limit", "required": false } ], "security": [ { "producerKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/messages/{id}/dry-run": { "post": { "summary": "Dry-run: counts, per-channel split, exclusions, quota estimate, violations", "tags": [ "messages" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "producerKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "recipients": { "type": "object", "properties": { "total": { "type": "number" }, "byChannel": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "excluded": { "type": "object", "properties": { "noConsent": { "type": "number" }, "noAddress": { "type": "number" }, "preferenceOff": { "type": "number" }, "blocked": { "type": "number" } }, "required": [ "noConsent", "noAddress", "preferenceOff", "blocked" ], "additionalProperties": false } }, "required": [ "total", "byChannel", "excluded" ], "additionalProperties": false }, "quota": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "estimatedPushes": { "type": "number" }, "unitRemaining": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "poolRemaining": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "wouldExceed": { "type": "boolean" } }, "required": [ "estimatedPushes", "unitRemaining", "poolRemaining", "wouldExceed" ], "additionalProperties": false } }, "violations": { "type": "array", "items": { "type": "string" } } }, "required": [ "recipients", "quota", "violations" ], "additionalProperties": false } } } } } } }, "/v1/messages/{id}/submit": { "post": { "summary": "draft → submitted (stores the dry-run snapshot; refuses policy violations)", "tags": [ "messages" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "producerKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "draft", "submitted", "approved", "rejected", "scheduled", "sending", "sent", "cancelled", "expired" ] } }, "required": [ "id", "state" ], "additionalProperties": false } } } } } } }, "/v1/messages/{id}/approve": { "post": { "summary": "Approve (approver ≠ author; emergency needs two). Producers trigger auto-approval instead.", "tags": [ "messages" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "maxLength": 500 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "producerKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "draft", "submitted", "approved", "rejected", "scheduled", "sending", "sent", "cancelled", "expired" ] }, "approved": { "type": "boolean" }, "approvals": { "type": "number" }, "required": { "type": "number" }, "reason": { "type": "string" } }, "required": [ "id", "state", "approved" ], "additionalProperties": false } } } } } } }, "/v1/messages/{id}/reject": { "post": { "summary": "submitted → rejected with a note", "tags": [ "messages" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "maxLength": 500 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "draft", "submitted", "approved", "rejected", "scheduled", "sending", "sent", "cancelled", "expired" ] } }, "required": [ "id", "state" ], "additionalProperties": false } } } } } } }, "/v1/messages/{id}/cancel": { "post": { "summary": "Cancel before sending (author or approver); releases reserved quota", "tags": [ "messages" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "producerKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "draft", "submitted", "approved", "rejected", "scheduled", "sending", "sent", "cancelled", "expired" ] } }, "required": [ "id", "state" ], "additionalProperties": false } } } } } } }, "/v1/messages/{id}": { "get": { "summary": "Message with dry-run snapshot, delivery statistics and approvals", "tags": [ "messages" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "producerKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/templates": { "get": { "summary": "List a unit’s templates", "tags": [ "templates" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "unitId", "required": false } ], "security": [ { "producerKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Create a template version (needs approval before auto rules apply)", "tags": [ "templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "unitId": { "type": "string" }, "name": { "type": "string", "minLength": 1 }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "categoryId": { "type": "string" }, "variables": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "string", "number", "date", "url" ] }, "required": { "default": false, "type": "boolean" }, "description": { "type": "string" } }, "required": [ "name", "type" ] } }, "messages": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text" ] }, "text": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "kind", "text" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image" ] }, "url": { "type": "string", "format": "uri" }, "alt": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "previewUrl": { "type": "string", "format": "uri" } }, "required": [ "kind", "url", "alt" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sticker" ] }, "packageId": { "type": "string" }, "stickerId": { "type": "string" }, "fallbackText": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "kind", "packageId", "stickerId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "card" ] }, "header": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "title": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "body": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "imageUrl": { "type": "string", "format": "uri" }, "actions": { "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "uri" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "url": { "type": "string", "format": "uri" } }, "required": [ "kind", "label", "url" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "postback" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "data": { "type": "object", "properties": { "v": { "type": "number", "enum": [ 1 ] }, "s": { "type": "string" }, "n": { "type": "string" }, "o": { "type": "string" }, "m": { "type": "string" }, "a": { "type": "string" } }, "required": [ "v" ] } }, "required": [ "kind", "label", "data" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "nextNode" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "nodeId": { "type": "string" }, "optionId": { "type": "string" } }, "required": [ "kind", "label", "nodeId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "jumpScenario" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "scenarioId": { "type": "string" } }, "required": [ "kind", "label", "scenarioId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mute" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "categoryId": { "type": "string" } }, "required": [ "kind", "label", "categoryId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "addToGroup" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "groupId": { "type": "string" } }, "required": [ "kind", "label", "groupId" ] } ] } }, "lockedReason": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "kind", "title", "actions" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "carousel" ] }, "cards": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "card" ] }, "header": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "title": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "body": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "imageUrl": { "type": "string", "format": "uri" }, "actions": { "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "uri" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "url": { "type": "string", "format": "uri" } }, "required": [ "kind", "label", "url" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "postback" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "data": { "type": "object", "properties": { "v": { "type": "number", "enum": [ 1 ] }, "s": { "type": "string" }, "n": { "type": "string" }, "o": { "type": "string" }, "m": { "type": "string" }, "a": { "type": "string" } }, "required": [ "v" ] } }, "required": [ "kind", "label", "data" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "nextNode" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "nodeId": { "type": "string" }, "optionId": { "type": "string" } }, "required": [ "kind", "label", "nodeId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "jumpScenario" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "scenarioId": { "type": "string" } }, "required": [ "kind", "label", "scenarioId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mute" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "categoryId": { "type": "string" } }, "required": [ "kind", "label", "categoryId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "addToGroup" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "groupId": { "type": "string" } }, "required": [ "kind", "label", "groupId" ] } ] } }, "lockedReason": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "kind", "title", "actions" ] } } }, "required": [ "kind", "cards" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "buttons" ] }, "text": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "actions": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "uri" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "url": { "type": "string", "format": "uri" } }, "required": [ "kind", "label", "url" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "postback" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "data": { "type": "object", "properties": { "v": { "type": "number", "enum": [ 1 ] }, "s": { "type": "string" }, "n": { "type": "string" }, "o": { "type": "string" }, "m": { "type": "string" }, "a": { "type": "string" } }, "required": [ "v" ] } }, "required": [ "kind", "label", "data" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "nextNode" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "nodeId": { "type": "string" }, "optionId": { "type": "string" } }, "required": [ "kind", "label", "nodeId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "jumpScenario" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "scenarioId": { "type": "string" } }, "required": [ "kind", "label", "scenarioId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mute" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "categoryId": { "type": "string" } }, "required": [ "kind", "label", "categoryId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "addToGroup" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "groupId": { "type": "string" } }, "required": [ "kind", "label", "groupId" ] } ] } } }, "required": [ "kind", "text", "actions" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "quickReply" ] }, "text": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "options": { "minItems": 1, "maxItems": 13, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "id", "label" ] } } }, "required": [ "kind", "text", "options" ] } ] } } }, "required": [ "name", "messages" ] } } } }, "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/templates/{id}": { "get": { "summary": "One template", "tags": [ "templates" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "producerKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/templates/{id}/approve": { "post": { "summary": "Approve a template (unit admin / approver)", "tags": [ "templates" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/scenarios": { "get": { "summary": "Active scenarios of a unit", "tags": [ "scenarios" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "unitId", "required": false } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Create a scenario; the graph is validated (entry node, edge grammar, singleton triggers)", "tags": [ "scenarios" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "unitId": { "type": "string" }, "name": { "type": "string", "minLength": 1 }, "trigger": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "keyword" ] }, "keywords": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "match": { "type": "string", "enum": [ "exact", "contains", "regex" ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "kind", "keywords", "match", "priority" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "follow" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "error" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "postback" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "event" ] }, "source": { "type": "string" }, "type": { "type": "string" } }, "required": [ "kind", "source", "type" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "schedule" ] } }, "required": [ "kind" ] } ] }, "entryNodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "config": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "message" ] }, "messages": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text" ] }, "text": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "kind", "text" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image" ] }, "url": { "type": "string", "format": "uri" }, "alt": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "previewUrl": { "type": "string", "format": "uri" } }, "required": [ "kind", "url", "alt" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sticker" ] }, "packageId": { "type": "string" }, "stickerId": { "type": "string" }, "fallbackText": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "kind", "packageId", "stickerId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "card" ] }, "header": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "title": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "body": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "imageUrl": { "type": "string", "format": "uri" }, "actions": { "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "uri" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "url": { "type": "string", "format": "uri" } }, "required": [ "kind", "label", "url" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "postback" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "data": { "type": "object", "properties": { "v": { "type": "number", "enum": [ 1 ] }, "s": { "type": "string" }, "n": { "type": "string" }, "o": { "type": "string" }, "m": { "type": "string" }, "a": { "type": "string" } }, "required": [ "v" ] } }, "required": [ "kind", "label", "data" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "nextNode" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "nodeId": { "type": "string" }, "optionId": { "type": "string" } }, "required": [ "kind", "label", "nodeId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "jumpScenario" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "scenarioId": { "type": "string" } }, "required": [ "kind", "label", "scenarioId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mute" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "categoryId": { "type": "string" } }, "required": [ "kind", "label", "categoryId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "addToGroup" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "groupId": { "type": "string" } }, "required": [ "kind", "label", "groupId" ] } ] } }, "lockedReason": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "kind", "title", "actions" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "carousel" ] }, "cards": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "card" ] }, "header": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "title": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "body": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "imageUrl": { "type": "string", "format": "uri" }, "actions": { "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "uri" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "url": { "type": "string", "format": "uri" } }, "required": [ "kind", "label", "url" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "postback" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "data": { "type": "object", "properties": { "v": { "type": "number", "enum": [ 1 ] }, "s": { "type": "string" }, "n": { "type": "string" }, "o": { "type": "string" }, "m": { "type": "string" }, "a": { "type": "string" } }, "required": [ "v" ] } }, "required": [ "kind", "label", "data" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "nextNode" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "nodeId": { "type": "string" }, "optionId": { "type": "string" } }, "required": [ "kind", "label", "nodeId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "jumpScenario" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "scenarioId": { "type": "string" } }, "required": [ "kind", "label", "scenarioId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mute" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "categoryId": { "type": "string" } }, "required": [ "kind", "label", "categoryId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "addToGroup" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "groupId": { "type": "string" } }, "required": [ "kind", "label", "groupId" ] } ] } }, "lockedReason": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "kind", "title", "actions" ] } } }, "required": [ "kind", "cards" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "buttons" ] }, "text": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "actions": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "uri" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "url": { "type": "string", "format": "uri" } }, "required": [ "kind", "label", "url" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "postback" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "data": { "type": "object", "properties": { "v": { "type": "number", "enum": [ 1 ] }, "s": { "type": "string" }, "n": { "type": "string" }, "o": { "type": "string" }, "m": { "type": "string" }, "a": { "type": "string" } }, "required": [ "v" ] } }, "required": [ "kind", "label", "data" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "nextNode" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "nodeId": { "type": "string" }, "optionId": { "type": "string" } }, "required": [ "kind", "label", "nodeId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "jumpScenario" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "scenarioId": { "type": "string" } }, "required": [ "kind", "label", "scenarioId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mute" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "categoryId": { "type": "string" } }, "required": [ "kind", "label", "categoryId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "addToGroup" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "groupId": { "type": "string" } }, "required": [ "kind", "label", "groupId" ] } ] } } }, "required": [ "kind", "text", "actions" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "quickReply" ] }, "text": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "options": { "minItems": 1, "maxItems": 13, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "id", "label" ] } } }, "required": [ "kind", "text", "options" ] } ] } } }, "required": [ "kind", "messages" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "choice" ] }, "prompt": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "id", "label" ] } }, "multi": { "type": "boolean" }, "scale": { "type": "boolean" }, "recordAs": { "type": "string" }, "optionsFrom": { "description": "vars path to dynamic options [{id,label}]", "type": "string", "minLength": 1 }, "promptFrom": { "description": "vars path to a dynamic prompt", "type": "string", "minLength": 1 }, "correctFrom": { "description": "vars path to the correct option id (graded choice)", "type": "string", "minLength": 1 }, "feedback": { "type": "object", "properties": { "correct": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "wrong": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "correct", "wrong" ] }, "scoreAs": { "description": "vars key incremented per correct answer", "type": "string", "minLength": 1 }, "grants": { "description": "choosing optionId records consent scope; already-consented people skip the question", "type": "object", "properties": { "scope": { "type": "string", "minLength": 1 }, "optionId": { "type": "string", "minLength": 1 } }, "required": [ "scope", "optionId" ] } }, "required": [ "kind", "prompt", "options" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "collect" ] }, "field": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text", "number", "date", "email", "phone" ] }, "required": { "type": "boolean" }, "prompt": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "pattern": { "type": "string" }, "maxLength": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "name", "type", "required", "prompt" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "branch" ] }, "on": { "type": "string", "enum": [ "attribute", "answer", "lookup" ] }, "key": { "type": "string" }, "cases": { "type": "array", "items": { "type": "object", "properties": { "equals": { "type": "string" }, "result": { "type": "string" } }, "required": [ "equals", "result" ] } }, "defaultResult": { "type": "string" } }, "required": [ "kind", "on", "key", "cases", "defaultResult" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "lookup" ] }, "endpointId": { "type": "string" }, "into": { "type": "string" }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "args": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "kind", "endpointId", "into" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "delay" ] }, "minutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "onlyIf": { "type": "object", "properties": { "unmet": { "type": "string" } }, "required": [ "unmet" ] } }, "required": [ "kind", "minutes" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "capacity" ] }, "patternInstanceId": { "type": "string" }, "limit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "waitlist": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "patternInstanceId", "limit", "waitlist", "deadline" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "record" ] }, "patternInstanceId": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } }, "addToGroupId": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "anonymous": { "type": "boolean" }, "requiresConsent": { "description": "store nothing without this consent; follow condition:no_consent instead", "type": "string", "minLength": 1 } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "handoff" ] }, "unitId": { "type": "string" }, "note": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "target": { "type": "string", "enum": [ "unit", "avatar" ] }, "avatarServiceUuid": { "type": "string" }, "greeting": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "privateResult": { "description": "avatar summary goes to the person only; nothing stored in memory or the outcome", "type": "boolean" } }, "required": [ "kind", "unitId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "ai" ] }, "providerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "systemPrompt": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "knowledgeSetIds": { "type": "array", "items": { "type": "string" } }, "useMemory": { "type": "boolean" }, "tools": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "lookup" ] }, "endpointId": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "endpointId", "description" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "goto" ] }, "nodeId": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "nodeId", "description" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "handoff" ] }, "unitId": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "unitId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "avatar" ] }, "serviceUuid": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "serviceUuid" ] } ] } }, "maxTurns": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "exitKeywords": { "type": "array", "items": { "type": "string" } }, "opener": { "description": "first message of the node; {{vars}} allowed", "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ] }, "promptVars": { "description": "vars shown to the model as earlier answers", "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1 } }, "summarize": { "description": "on exit, read the most interesting topic into {{ai.interest}}", "type": "boolean" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 } }, "required": [ "kind", "providerId", "systemPrompt", "knowledgeSetIds", "useMemory", "tools", "maxTurns" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "report" ] }, "patternInstanceId": { "type": "string" } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "end" ] } }, "required": [ "kind" ] } ] }, "tags": { "default": [], "type": "array", "items": { "type": "string" } } }, "required": [ "id", "label", "config" ] } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "from": { "type": "string" }, "to": { "type": "string" }, "on": { "type": "string", "pattern": "^(default|timeout|option:.+|condition:.+)$" } }, "required": [ "id", "from", "to", "on" ] } } }, "required": [ "name", "trigger", "entryNodeId", "nodes", "edges" ] } } } }, "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/scenarios/{id}": { "get": { "summary": "Scenario with its nodes and edges", "tags": [ "scenarios" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } }, "put": { "summary": "Replace a scenario graph in place", "tags": [ "scenarios" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "unitId": { "type": "string" }, "name": { "type": "string", "minLength": 1 }, "trigger": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "keyword" ] }, "keywords": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "match": { "type": "string", "enum": [ "exact", "contains", "regex" ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "kind", "keywords", "match", "priority" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "follow" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "error" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "postback" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "event" ] }, "source": { "type": "string" }, "type": { "type": "string" } }, "required": [ "kind", "source", "type" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "schedule" ] } }, "required": [ "kind" ] } ] }, "entryNodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "config": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "message" ] }, "messages": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text" ] }, "text": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "kind", "text" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image" ] }, "url": { "type": "string", "format": "uri" }, "alt": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "previewUrl": { "type": "string", "format": "uri" } }, "required": [ "kind", "url", "alt" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sticker" ] }, "packageId": { "type": "string" }, "stickerId": { "type": "string" }, "fallbackText": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "kind", "packageId", "stickerId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "card" ] }, "header": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "title": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "body": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "imageUrl": { "type": "string", "format": "uri" }, "actions": { "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "uri" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "url": { "type": "string", "format": "uri" } }, "required": [ "kind", "label", "url" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "postback" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "data": { "type": "object", "properties": { "v": { "type": "number", "enum": [ 1 ] }, "s": { "type": "string" }, "n": { "type": "string" }, "o": { "type": "string" }, "m": { "type": "string" }, "a": { "type": "string" } }, "required": [ "v" ] } }, "required": [ "kind", "label", "data" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "nextNode" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "nodeId": { "type": "string" }, "optionId": { "type": "string" } }, "required": [ "kind", "label", "nodeId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "jumpScenario" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "scenarioId": { "type": "string" } }, "required": [ "kind", "label", "scenarioId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mute" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "categoryId": { "type": "string" } }, "required": [ "kind", "label", "categoryId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "addToGroup" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "groupId": { "type": "string" } }, "required": [ "kind", "label", "groupId" ] } ] } }, "lockedReason": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "kind", "title", "actions" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "carousel" ] }, "cards": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "card" ] }, "header": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "title": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "body": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "imageUrl": { "type": "string", "format": "uri" }, "actions": { "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "uri" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "url": { "type": "string", "format": "uri" } }, "required": [ "kind", "label", "url" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "postback" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "data": { "type": "object", "properties": { "v": { "type": "number", "enum": [ 1 ] }, "s": { "type": "string" }, "n": { "type": "string" }, "o": { "type": "string" }, "m": { "type": "string" }, "a": { "type": "string" } }, "required": [ "v" ] } }, "required": [ "kind", "label", "data" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "nextNode" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "nodeId": { "type": "string" }, "optionId": { "type": "string" } }, "required": [ "kind", "label", "nodeId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "jumpScenario" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "scenarioId": { "type": "string" } }, "required": [ "kind", "label", "scenarioId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mute" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "categoryId": { "type": "string" } }, "required": [ "kind", "label", "categoryId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "addToGroup" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "groupId": { "type": "string" } }, "required": [ "kind", "label", "groupId" ] } ] } }, "lockedReason": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "kind", "title", "actions" ] } } }, "required": [ "kind", "cards" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "buttons" ] }, "text": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "actions": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "uri" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "url": { "type": "string", "format": "uri" } }, "required": [ "kind", "label", "url" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "postback" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "data": { "type": "object", "properties": { "v": { "type": "number", "enum": [ 1 ] }, "s": { "type": "string" }, "n": { "type": "string" }, "o": { "type": "string" }, "m": { "type": "string" }, "a": { "type": "string" } }, "required": [ "v" ] } }, "required": [ "kind", "label", "data" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "nextNode" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "nodeId": { "type": "string" }, "optionId": { "type": "string" } }, "required": [ "kind", "label", "nodeId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "jumpScenario" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "scenarioId": { "type": "string" } }, "required": [ "kind", "label", "scenarioId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mute" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "categoryId": { "type": "string" } }, "required": [ "kind", "label", "categoryId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "addToGroup" ] }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "groupId": { "type": "string" } }, "required": [ "kind", "label", "groupId" ] } ] } } }, "required": [ "kind", "text", "actions" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "quickReply" ] }, "text": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "options": { "minItems": 1, "maxItems": 13, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "id", "label" ] } } }, "required": [ "kind", "text", "options" ] } ] } } }, "required": [ "kind", "messages" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "choice" ] }, "prompt": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "id", "label" ] } }, "multi": { "type": "boolean" }, "scale": { "type": "boolean" }, "recordAs": { "type": "string" }, "optionsFrom": { "description": "vars path to dynamic options [{id,label}]", "type": "string", "minLength": 1 }, "promptFrom": { "description": "vars path to a dynamic prompt", "type": "string", "minLength": 1 }, "correctFrom": { "description": "vars path to the correct option id (graded choice)", "type": "string", "minLength": 1 }, "feedback": { "type": "object", "properties": { "correct": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "wrong": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" } }, "required": [ "correct", "wrong" ] }, "scoreAs": { "description": "vars key incremented per correct answer", "type": "string", "minLength": 1 }, "grants": { "description": "choosing optionId records consent scope; already-consented people skip the question", "type": "object", "properties": { "scope": { "type": "string", "minLength": 1 }, "optionId": { "type": "string", "minLength": 1 } }, "required": [ "scope", "optionId" ] } }, "required": [ "kind", "prompt", "options" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "collect" ] }, "field": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text", "number", "date", "email", "phone" ] }, "required": { "type": "boolean" }, "prompt": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "pattern": { "type": "string" }, "maxLength": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "name", "type", "required", "prompt" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "branch" ] }, "on": { "type": "string", "enum": [ "attribute", "answer", "lookup" ] }, "key": { "type": "string" }, "cases": { "type": "array", "items": { "type": "object", "properties": { "equals": { "type": "string" }, "result": { "type": "string" } }, "required": [ "equals", "result" ] } }, "defaultResult": { "type": "string" } }, "required": [ "kind", "on", "key", "cases", "defaultResult" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "lookup" ] }, "endpointId": { "type": "string" }, "into": { "type": "string" }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "args": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "kind", "endpointId", "into" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "delay" ] }, "minutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "onlyIf": { "type": "object", "properties": { "unmet": { "type": "string" } }, "required": [ "unmet" ] } }, "required": [ "kind", "minutes" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "capacity" ] }, "patternInstanceId": { "type": "string" }, "limit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "waitlist": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "patternInstanceId", "limit", "waitlist", "deadline" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "record" ] }, "patternInstanceId": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } }, "addToGroupId": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "anonymous": { "type": "boolean" }, "requiresConsent": { "description": "store nothing without this consent; follow condition:no_consent instead", "type": "string", "minLength": 1 } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "handoff" ] }, "unitId": { "type": "string" }, "note": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "target": { "type": "string", "enum": [ "unit", "avatar" ] }, "avatarServiceUuid": { "type": "string" }, "greeting": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "privateResult": { "description": "avatar summary goes to the person only; nothing stored in memory or the outcome", "type": "boolean" } }, "required": [ "kind", "unitId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "ai" ] }, "providerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "systemPrompt": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "knowledgeSetIds": { "type": "array", "items": { "type": "string" } }, "useMemory": { "type": "boolean" }, "tools": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "lookup" ] }, "endpointId": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "endpointId", "description" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "goto" ] }, "nodeId": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "nodeId", "description" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "handoff" ] }, "unitId": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "unitId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "avatar" ] }, "serviceUuid": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "serviceUuid" ] } ] } }, "maxTurns": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "exitKeywords": { "type": "array", "items": { "type": "string" } }, "opener": { "description": "first message of the node; {{vars}} allowed", "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ] }, "promptVars": { "description": "vars shown to the model as earlier answers", "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1 } }, "summarize": { "description": "on exit, read the most interesting topic into {{ai.interest}}", "type": "boolean" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 } }, "required": [ "kind", "providerId", "systemPrompt", "knowledgeSetIds", "useMemory", "tools", "maxTurns" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "report" ] }, "patternInstanceId": { "type": "string" } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "end" ] } }, "required": [ "kind" ] } ] }, "tags": { "default": [], "type": "array", "items": { "type": "string" } } }, "required": [ "id", "label", "config" ] } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "from": { "type": "string" }, "to": { "type": "string" }, "on": { "type": "string", "pattern": "^(default|timeout|option:.+|condition:.+)$" } }, "required": [ "id", "from", "to", "on" ] } } }, "required": [ "name", "trigger", "entryNodeId", "nodes", "edges" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/patterns": { "post": { "summary": "Build a scenario + pattern instance from a wizard config", "tags": [ "patterns" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "unitId": { "type": "string" }, "id": { "description": "Rebuild an existing instance in place", "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "survey", "vote", "event_registration", "acknowledgement", "drip", "menu", "faq", "handoff", "approval", "learning_companion" ] }, "config": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "survey", "vote", "event_registration", "acknowledgement", "drip", "menu", "faq", "handoff", "approval", "learning_companion" ] } }, "required": [ "kind" ], "additionalProperties": {} } }, "required": [ "config" ] } } } }, "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/patterns/{id}/report": { "get": { "summary": "Completion / distribution report of a pattern instance (counts only)", "tags": [ "patterns" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/patterns/{id}/learners": { "get": { "summary": "學習夥伴: enrolled learners with streak, last completion and average quiz score (view on the unit)", "tags": [ "patterns" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/patterns/{id}/learners/{subjectId}": { "get": { "summary": "學習夥伴: one learner's progress (last 14 completions)", "tags": [ "patterns" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "subjectId", "required": true } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/patterns/{id}/applications": { "get": { "summary": "申請與簽核: applications of an approval pattern (approver+ of the unit)", "tags": [ "patterns" ], "parameters": [ { "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "withdrawn" ] }, "in": "query", "name": "state", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/patterns/{id}/applications/{applicationId}/decide": { "post": { "summary": "申請與簽核: approve / reject one application (a listed approver, or a producer of the approving unit)", "tags": [ "patterns" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "minLength": 1, "description": "Decision option id, e.g. approve / reject" }, "comment": { "type": "string", "maxLength": 500 } }, "required": [ "decision" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "applicationId", "required": true } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/groups": { "get": { "summary": "Groups of a unit", "tags": [ "groups" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "unitId", "required": false } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Create a group (static groups need legalBasis)", "tags": [ "groups" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "unitId": { "type": "string" }, "parentId": { "type": "string" }, "name": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "dynamic", "static" ] }, "query": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "all" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "query" ] }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "student", "teacher", "staff" ] } }, "stages": { "type": "array", "items": { "type": "string", "enum": [ "visitor", "lead", "member", "alumni" ] } }, "orgUnits": { "type": "array", "items": { "type": "string" } }, "classIds": { "type": "array", "items": { "type": "string" } }, "groups": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "history": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "registered" ] }, "patternInstanceId": { "type": "string" } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "notRegistered" ] }, "patternInstanceId": { "type": "string" } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "responded" ] }, "patternInstanceId": { "type": "string" } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "notResponded" ] }, "patternInstanceId": { "type": "string" } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "read" ] }, "messageId": { "type": "string" } }, "required": [ "kind", "messageId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "unread" ] }, "messageId": { "type": "string" } }, "required": [ "kind", "messageId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "acked" ] }, "messageId": { "type": "string" } }, "required": [ "kind", "messageId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "notAcked" ] }, "messageId": { "type": "string" } }, "required": [ "kind", "messageId" ] } ] } }, "lists": { "type": "array", "items": { "type": "string" } }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "line", "email", "webpush", "whatsapp", "messenger" ] } }, "locales": { "type": "array", "items": { "type": "string", "enum": [ "zh-TW", "en" ] } }, "flags": { "type": "array", "items": { "type": "string", "enum": [ "isTutor", "isGraduate" ] } }, "exclude": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "all" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "query" ] }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "student", "teacher", "staff" ] } }, "stages": { "type": "array", "items": { "type": "string", "enum": [ "visitor", "lead", "member", "alumni" ] } }, "orgUnits": { "type": "array", "items": { "type": "string" } }, "classIds": { "type": "array", "items": { "type": "string" } }, "groups": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "history": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "registered" ] }, "patternInstanceId": { "type": "string" } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "notRegistered" ] }, "patternInstanceId": { "type": "string" } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "responded" ] }, "patternInstanceId": { "type": "string" } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "notResponded" ] }, "patternInstanceId": { "type": "string" } }, "required": [ "kind", "patternInstanceId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "read" ] }, "messageId": { "type": "string" } }, "required": [ "kind", "messageId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "unread" ] }, "messageId": { "type": "string" } }, "required": [ "kind", "messageId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "acked" ] }, "messageId": { "type": "string" } }, "required": [ "kind", "messageId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "notAcked" ] }, "messageId": { "type": "string" } }, "required": [ "kind", "messageId" ] } ] } }, "lists": { "type": "array", "items": { "type": "string" } }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "line", "email", "webpush", "whatsapp", "messenger" ] } }, "locales": { "type": "array", "items": { "type": "string", "enum": [ "zh-TW", "en" ] } }, "flags": { "type": "array", "items": { "type": "string", "enum": [ "isTutor", "isGraduate" ] } } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "individual" ] }, "uids": { "minItems": 1, "maxItems": 5000, "type": "array", "items": { "type": "string" } } }, "required": [ "kind", "uids" ] } ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "individual" ] }, "uids": { "minItems": 1, "maxItems": 5000, "type": "array", "items": { "type": "string" } } }, "required": [ "kind", "uids" ] } ], "description": "Audience is always a query, resolved at send time" }, "legalBasis": { "description": "Required for static groups: why the unit holds this list", "type": "string", "minLength": 1 }, "validTo": { "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "ISO 8601 date-time" } }, "required": [ "name", "kind" ] } } } }, "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/groups/{id}/members": { "post": { "summary": "Add members to a static group; members must be inside the parent (409 otherwise)", "tags": [ "groups" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subjectIds": { "minItems": 1, "maxItems": 5000, "type": "array", "items": { "type": "string", "minLength": 1 } }, "source": { "default": "console", "type": "string" } }, "required": [ "subjectIds" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/schedules": { "get": { "summary": "Schedules by state (unit-visible ones only)", "tags": [ "schedules" ], "parameters": [ { "schema": { "default": "active", "type": "string", "enum": [ "active", "paused", "done" ] }, "in": "query", "name": "state", "required": false }, { "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 500 }, "in": "query", "name": "limit", "required": false } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Create a once / delay / recurring schedule for a message or scenario", "tags": [ "schedules" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spec": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "once" ] }, "runAt": { "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "ISO 8601 date-time" } }, "required": [ "kind", "runAt" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "delay" ] }, "minutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "onlyIfUnmet": { "type": "string" } }, "required": [ "kind", "minutes" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "recurring" ] }, "cron": { "type": "string", "minLength": 9 } }, "required": [ "kind", "cron" ] } ] }, "target": { "anyOf": [ { "type": "object", "properties": { "messageId": { "type": "string" } }, "required": [ "messageId" ] }, { "type": "object", "properties": { "scenarioId": { "type": "string" }, "subjectId": { "type": "string" }, "nodeId": { "type": "string" } }, "required": [ "scenarioId" ] } ] } }, "required": [ "spec", "target" ] } } } }, "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/categories": { "get": { "summary": "Active categories (layer, consent scope, plan, approval rule)", "tags": [ "catalogue" ], "security": [ { "producerKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/units/{id}": { "get": { "summary": "Unit with members, this month’s LINE quota rows and threshold state", "tags": [ "catalogue" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/audit": { "get": { "summary": "Recent audit entries (approver+ of the unit, or admin)", "tags": [ "catalogue" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "unitId", "required": false }, { "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 500 }, "in": "query", "name": "limit", "required": false } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/health": { "get": { "summary": "Readiness: database ping, every adapter’s healthCheck, and which peer services (violet-context, Avatar) this deployment is wired to", "tags": [ "catalogue" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/events/{source}": { "post": { "summary": "校務系統 event (HMAC-signed); the binding decides category, template and audience", "tags": [ "events" ], "description": "Headers: X-Herald-Key-Id, X-Herald-Timestamp (unix seconds, ±300 s), X-Herald-Signature: v1=HMAC-SHA256(secret, ts + \".\" + rawBody). Replays (same signature or same eventId) return 202 with duplicate=true. Keys: EVENT_SIGNING_KEYS (single-tenant) or the tenant’s `events` credential (hosted; also reachable as /t/{slug}/v1/events/{source}).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "minLength": 1, "maxLength": 200 }, "occurredAt": { "type": "string" }, "subjectUids": { "type": "array", "items": { "type": "string" } }, "audience": { "type": "object", "properties": { "uids": { "type": "array", "items": { "type": "string" } } }, "required": [ "uids" ] }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "eventId", "type" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "source", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-herald-key-id", "required": true, "description": "Signing key id (EVENT_SIGNING_KEYS)" }, { "schema": { "type": "string" }, "in": "header", "name": "x-herald-timestamp", "required": true, "description": "Unix seconds when the request was signed" }, { "schema": { "type": "string" }, "in": "header", "name": "x-herald-signature", "required": true, "description": "v1=" } ], "security": [ { "hmac": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "duplicate": { "type": "boolean" }, "eventId": { "type": "string" }, "messageId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "accepted", "duplicate", "eventId" ], "additionalProperties": false } } } } } } }, "/v1/webhooks/{adapterId}": { "get": { "summary": "Meta subscription handshake (hub.challenge)", "tags": [ "webhooks" ], "description": "WhatsApp Cloud API and Messenger verify the callback URL with GET ?hub.mode=subscribe&hub.verify_token=…&hub.challenge=…; the adapter checks the token (constant-time) and the challenge is echoed as text/plain. Adapters without a handshake → 404, wrong token → 403.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "hub.mode", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "hub.verify_token", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "hub.challenge", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "adapterId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "post": { "summary": "Provider callback; the adapter verifies the signature and normalises events", "tags": [ "webhooks" ], "description": "LINE expects a reply within about a second, so each event is handled inline (reply-token first) and nothing is queued; long work is pushed afterwards by the engine. Hosted: the tenant is the subdomain, X-Herald-Tenant, or the /t/{slug}/v1/webhooks/{adapterId} prefix, and the adapter is built from that tenant’s credentials; a `follow` that would exceed the plan’s subject ceiling is skipped (counted in received, not handled).", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "adapterId", "required": true } ], "security": [ { "adapterSignature": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "number" }, "handled": { "type": "number" } }, "required": [ "received", "handled" ], "additionalProperties": false } } } } } } }, "/v1/subjects/{campusUid}/addresses/{channel}": { "put": { "summary": "Bind (or re-bind) a channel address to a campus identity", "tags": [ "identity" ], "description": "Upserts the subject by campus uid, makes the address the live primary for the channel, retires any earlier address on that channel in the same request (換手機) and writes an audit entry.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "minLength": 1, "maxLength": 320 }, "providerHint": { "type": "string", "maxLength": 120 }, "verified": { "default": true, "type": "boolean" }, "source": { "default": "bind", "type": "string", "maxLength": 40 }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "student", "teacher", "staff" ] } }, "orgUnit": { "type": "string", "maxLength": 64 }, "classId": { "type": "string", "maxLength": 64 }, "preferredLocale": { "type": "string", "enum": [ "zh-TW", "en" ] }, "displayName": { "type": "string", "maxLength": 120 }, "stage": { "type": "string", "enum": [ "visitor", "lead", "member", "alumni" ] }, "acquisition": { "type": "object", "properties": { "source": { "type": "string", "minLength": 1, "maxLength": 40 }, "ref": { "type": "string", "maxLength": 120 } }, "required": [ "source" ], "description": "Where this person came from: liff, directory, import, event:, … plus the campaign / QR / activity ref" } }, "required": [ "address" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "campusUid", "required": true }, { "schema": { "type": "string", "enum": [ "line", "email", "webpush", "whatsapp", "messenger" ] }, "in": "path", "name": "channel", "required": true } ], "security": [ { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "summary": "Unbind: disable every live address on the channel (history kept)", "tags": [ "identity" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "campusUid", "required": true }, { "schema": { "type": "string", "enum": [ "line", "email", "webpush", "whatsapp", "messenger" ] }, "in": "path", "name": "channel", "required": true } ], "security": [ { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/subjects/{campusUid}/consents": { "post": { "summary": "Record consent for a scope (version defaults to CONSENT_VERSION)", "tags": [ "identity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "minLength": 1, "maxLength": 64 }, "version": { "type": "string", "maxLength": 64 }, "source": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "scope", "source" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "campusUid", "required": true } ], "security": [ { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/subjects/{campusUid}/consents/{scope}": { "delete": { "summary": "Withdraw consent for a scope (effective at the next audience resolution)", "tags": [ "identity" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "campusUid", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "scope", "required": true } ], "security": [ { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/subjects/{campusUid}/link": { "post": { "summary": "Give a subject known only by an address (a LINE follower) this external identity", "tags": [ "identity" ], "description": "For a lookup endpoint that just learned who the person in a chat is (docs/27 §4.6): `subjectId` is the `subject` the lookup call carried. When another subject already holds the uid (created from the CRM side with only an e-mail) it is folded in: addresses on channels this subject lacks move over, tags and live consents are copied, the later stage wins. 409 `linked_elsewhere` when the subject already carries a different uid.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subjectId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Herald's internal subject id — what a `lookup` call sends as `subject`" } }, "required": [ "subjectId" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "campusUid", "required": true } ], "security": [ { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/subjects/{campusUid}": { "patch": { "summary": "CRM sync: advance the stage, refresh profile fields, record first-touch attribution, add / remove tags", "tags": [ "identity" ], "description": "For an external CRM or alumni system. Stage only moves forward; `acquisition` is written once; tags follow the interest:/source:/cohort: conventions so the executive view can count them.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stage": { "description": "Only moves forward (visitor → lead → member → alumni); a backwards value is ignored", "type": "string", "enum": [ "visitor", "lead", "member", "alumni" ] }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "student", "teacher", "staff" ] } }, "orgUnit": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "classId": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "displayName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "preferredLocale": { "type": "string", "enum": [ "zh-TW", "en" ] }, "isTutor": { "type": "boolean" }, "isGraduate": { "type": "boolean" }, "acquisition": { "type": "object", "properties": { "source": { "type": "string", "minLength": 1, "maxLength": 40 }, "ref": { "type": "string", "maxLength": 120 } }, "required": [ "source" ], "description": "Where this person came from: liff, directory, import, event:, … plus the campaign / QR / activity ref" }, "tags": { "description": "Tag conventions: interest:, source:, cohort: (docs/25)", "type": "object", "properties": { "add": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[A-Za-z0-9_:.-]+$" } }, "remove": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[A-Za-z0-9_:.-]+$" } } } } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "campusUid", "required": true } ], "security": [ { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } }, "get": { "summary": "Minimal view: stage, which channels are bound, active consent scopes (no address values)", "tags": [ "identity" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "campusUid", "required": true } ], "security": [ { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/me/inbox": { "get": { "summary": "Message centre: this person’s inbox items, newest first", "tags": [ "me" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "unitId", "required": false }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "unread", "required": false }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "before", "required": false } ], "security": [ { "lineIdToken": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/me/inbox/{id}/read": { "post": { "summary": "Mark one inbox item read (scoped to the owner)", "tags": [ "me" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "lineIdToken": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/me/preferences": { "get": { "summary": "Category / unit / topic preferences and quiet hours; fixed-layer categories are locked", "tags": [ "me" ], "security": [ { "lineIdToken": [] } ], "responses": { "200": { "description": "Default Response" } } }, "put": { "summary": "Update preferences; disabling a fixed-layer category is refused (400)", "tags": [ "me" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "id", "enabled" ] } }, "units": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "id", "enabled" ] } }, "topics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "id", "enabled" ] } }, "quietHours": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "start": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "end": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" } }, "required": [ "enabled", "start", "end" ] } } } } } }, "security": [ { "lineIdToken": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/me/act": { "get": { "summary": "Email action link: run a postback for this person as if it came from LINE, then redirect to the inbox", "tags": [ "me" ], "parameters": [ { "schema": { "type": "string", "minLength": 2, "maxLength": 2000 }, "in": "query", "name": "d", "required": true, "description": "Postback JSON (encodePostback)" } ], "security": [ { "lineIdToken": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/auth/login": { "post": { "summary": "Mock login (SSO_MOCK only): become a seeded unit member", "tags": [ "auth" ], "description": "Refused unless SSO_MOCK is on; production logs in through /auth/sso/start.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "uid": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "uid" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/v1/auth/sso/start": { "get": { "summary": "Begin the campus SSO (OIDC) authorisation; redirects to the IdP", "tags": [ "auth" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "returnTo", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/auth/sso/callback": { "get": { "summary": "OIDC callback: exchange the code, verify the id token, open a session", "tags": [ "auth" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "code", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "state", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "error", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/auth/logout": { "post": { "summary": "End the console session", "tags": [ "auth" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/auth/me": { "get": { "summary": "The signed-in console user and their unit roles", "tags": [ "auth" ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/llm/providers/kinds": { "get": { "summary": "Provider kinds with default base URLs and example models", "tags": [ "llm" ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/llm/providers": { "get": { "summary": "LLM providers of a unit plus the globals (keys never returned; `hasKey` only)", "tags": [ "llm" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "unitId", "required": false } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Create a provider (manage_unit of the unit, or admin for a global one)", "tags": [ "llm" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "unitId": { "description": "Omit or null for a global provider (admin only)", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "kind": { "type": "string", "enum": [ "openai_compatible", "anthropic", "google", "mock" ] }, "baseUrl": { "anyOf": [ { "type": "string", "maxLength": 500, "pattern": "^https?:\\/\\/\\S+$" }, { "type": "null" } ] }, "model": { "type": "string", "minLength": 1, "maxLength": 120 }, "embedModel": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "apiKey": { "description": "Write-only; stored encrypted", "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] }, "headers": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 100 }, "additionalProperties": { "type": "string", "maxLength": 2000 } }, { "type": "null" } ] }, "isDefault": { "type": "boolean" } }, "required": [ "name", "kind", "model" ] } } } }, "security": [ { "session": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/llm/providers/{id}": { "put": { "summary": "Update a provider; omit apiKey to keep the stored one", "tags": [ "llm" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "kind": { "type": "string", "enum": [ "openai_compatible", "anthropic", "google", "mock" ] }, "baseUrl": { "anyOf": [ { "type": "string", "maxLength": 500, "pattern": "^https?:\\/\\/\\S+$" }, { "type": "null" } ] }, "model": { "type": "string", "minLength": 1, "maxLength": 120 }, "embedModel": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "apiKey": { "description": "Omit to keep, empty/null to clear", "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] }, "headers": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 100 }, "additionalProperties": { "type": "string", "maxLength": 2000 } }, { "type": "null" } ] }, "isDefault": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "summary": "Delete a provider (usage rows are kept)", "tags": [ "llm" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/llm/providers/{id}/test": { "post": { "summary": "healthCheck + a tiny chat (「回覆 OK」), metered with purpose=test", "tags": [ "llm" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/llm/usage": { "get": { "summary": "Month totals (calls, tokens, by purpose) and recent calls of a unit; admin without unitId sees the whole hub", "tags": [ "llm" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "unitId", "required": false }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "in": "query", "name": "month", "required": false }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/knowledge/sets": { "get": { "summary": "Knowledge sets of a unit", "tags": [ "knowledge" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "unitId", "required": false } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Create a knowledge set", "tags": [ "knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "unitId": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 500 } }, "required": [ "name" ] } } } }, "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/knowledge/sets/{id}/sources": { "get": { "summary": "Sources of a set with published/draft version info", "tags": [ "knowledge" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/knowledge/sources": { "post": { "summary": "Create a source (text / faq / url) with its draft version 1", "tags": [ "knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "setId": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "text", "faq", "url" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "uri": { "type": "string", "format": "uri" }, "content": { "description": "Required for text/faq; for url sources it is fetched when omitted", "type": "string", "minLength": 1, "maxLength": 200000 }, "owner": { "description": "Defaults to the caller", "type": "string", "minLength": 1, "maxLength": 64 }, "note": { "type": "string", "maxLength": 500 }, "validFrom": { "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "ISO 8601 date-time" }, "validTo": { "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "ISO 8601 date-time" }, "refreshHours": { "description": "url sources: re-fetch cadence", "type": "integer", "exclusiveMinimum": 0, "maximum": 2160 } }, "required": [ "setId", "kind", "title" ] } } } }, "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/knowledge/sources/{id}": { "get": { "summary": "One source with its version history (content included)", "tags": [ "knowledge" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/knowledge/sources/{id}/versions": { "post": { "summary": "Add a draft version (no-op when the content hash is unchanged)", "tags": [ "knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 200000 }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "content" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/knowledge/sources/{id}/publish": { "post": { "summary": "Publish a version (unit approver); embeddings are computed when the unit has an embedding provider", "tags": [ "knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "version" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/knowledge/sources/{id}/rollback": { "post": { "summary": "Roll back = publish an older version (unit approver)", "tags": [ "knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "version" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/knowledge/sources/{id}/archive": { "post": { "summary": "Archive a source: never retrievable again until a new version is published", "tags": [ "knowledge" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/knowledge/search": { "post": { "summary": "Hybrid search over published, in-window chunks of the given sets; returns chunks with citations", "tags": [ "knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "setIds": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1 } }, "query": { "type": "string", "minLength": 1, "maxLength": 500 }, "k": { "default": 6, "type": "integer", "minimum": 1, "maximum": 20 }, "context": { "default": false, "type": "boolean" } }, "required": [ "setIds", "query" ] } } } }, "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/context/{subjectId}": { "get": { "summary": "Subject context for the avatar ContextProvider: profile (no addresses), memory, summaries, tags, recent interactions, consent scopes", "tags": [ "memory" ], "description": "Administrative-unit credential or administrator session for any subject; a LINE id token reads its own context only.", "parameters": [ { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "includeProfile", "required": false }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "includeMemory", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "maxFacts", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "subjectId", "required": true } ], "security": [ { "producerKey": [] }, { "session": [] }, { "lineIdToken": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/subjects/{campusUid}/memory": { "get": { "summary": "What Herald remembers about a person (administrative units only); ?all=true includes superseded / revoked facts", "tags": [ "memory" ], "parameters": [ { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "all", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "campusUid", "required": true } ], "security": [ { "producerKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Add a manual fact; grades, amounts and ID numbers are refused (400 memory_rejected)", "tags": [ "memory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "preference", "fact", "interest", "constraint", "profile", "intent" ] }, "key": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "content": { "type": "string", "minLength": 1, "maxLength": 300 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "validTo": { "anyOf": [ { "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "ISO 8601 date-time" }, { "type": "null" } ] } }, "required": [ "category", "content" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "campusUid", "required": true } ], "security": [ { "producerKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "summary": "Forget everything remembered about a person (facts, summaries, mem: tags); audited", "tags": [ "memory" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "campusUid", "required": true } ], "security": [ { "producerKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/subjects/{campusUid}/memory/{factId}": { "delete": { "summary": "撤銷 one fact (its validity ends now; the row stays until the retention purge)", "tags": [ "memory" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "campusUid", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "factId", "required": true } ], "security": [ { "producerKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/me/memory": { "get": { "summary": "What Herald remembers about me (live facts and summaries)", "tags": [ "me" ], "security": [ { "lineIdToken": [] } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "summary": "Forget everything remembered about me", "tags": [ "me" ], "security": [ { "lineIdToken": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/me/memory/{factId}": { "delete": { "summary": "Delete one fact remembered about me", "tags": [ "me" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "factId", "required": true } ], "security": [ { "lineIdToken": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/handoffs/{id}": { "get": { "summary": "Avatar handoff context (docs/12 §3); the first read marks it opened", "tags": [ "webhooks" ], "description": "Authenticate with `X-Handoff-Key` (shared key, env HANDOFF_KEY) or the LINE id token of the person the handoff belongs to. 410 once expired, completed or abandoned. `?authId=` / `?firebaseUid=` (optional) name the person on the avatar side; with violet-context configured the two subjects are linked (best-effort, `subject.linked`).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "authId", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "firebaseUid", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-handoff-key", "required": false, "description": "Shared key between the avatar BFF and Herald (HANDOFF_KEY)" } ], "security": [ { "lineIdToken": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "subject": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "locale": { "type": "string" }, "authId": { "type": "string" }, "linked": { "type": "boolean" } }, "required": [ "id", "displayName", "locale", "authId", "linked" ], "additionalProperties": false }, "serviceUuid": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scenario": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "nodeId" ], "additionalProperties": false }, "vars": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "facts": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "content": { "type": "string" } }, "required": [ "category", "content" ], "additionalProperties": false } }, "greeting": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "callback": { "type": "object", "properties": { "url": { "type": "string" }, "keyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "url", "keyId" ], "additionalProperties": false }, "expiresAt": { "type": "string" } }, "required": [ "id", "state", "subject", "serviceUuid", "scenario", "vars", "facts", "greeting", "callback", "expiresAt" ], "additionalProperties": false } } } } } } }, "/v1/webhooks/avatar": { "post": { "summary": "Avatar session callback (HMAC-signed like campus events): started → in_session, ended → outcome, facts, scenario continues", "tags": [ "webhooks" ], "description": "Headers: X-Herald-Key-Id, X-Herald-Timestamp (unix seconds, ±300 s), X-Herald-Signature: v1=HMAC-SHA256(secret, ts + \".\" + rawBody). Replays return 202 with duplicate=true.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "enum": [ "avatar.session.started", "avatar.session.ended" ] }, "handoffId": { "type": "string", "minLength": 1 }, "roomName": { "type": "string" }, "occurredAt": { "type": "string" }, "durationSeconds": { "type": "number", "minimum": 0 }, "status": { "type": "string", "enum": [ "completed", "abandoned" ] }, "summary": { "type": "string", "maxLength": 4000 }, "facts": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "minLength": 1, "maxLength": 64 }, "key": { "type": "string", "maxLength": 120 }, "content": { "type": "string", "minLength": 1, "maxLength": 2000 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "category", "content" ] } }, "outcome": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "registration", "booking", "none" ] }, "patternInstanceId": { "type": "string" }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "kind" ] }, "transcriptRef": { "type": "string" }, "avatarAuthId": { "type": "string", "minLength": 1, "maxLength": 200 }, "firebaseUid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "eventId", "type", "handoffId" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "x-herald-key-id", "required": true, "description": "Signing key id (EVENT_SIGNING_KEYS, e.g. avatar-2027)" }, { "schema": { "type": "string" }, "in": "header", "name": "x-herald-timestamp", "required": true, "description": "Unix seconds when the request was signed" }, { "schema": { "type": "string" }, "in": "header", "name": "x-herald-signature", "required": true, "description": "v1=" } ], "security": [ { "hmac": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "duplicate": { "type": "boolean" }, "handoffId": { "type": "string" }, "state": { "type": "string" }, "resumed": { "type": "boolean" }, "identityLinked": { "type": "boolean" } }, "required": [ "accepted", "duplicate", "handoffId" ], "additionalProperties": false } } } } } } }, "/v1/tls/ask": { "get": { "summary": "Hosted: Caddy on-demand TLS `ask` — 200 only for an active tenant's own subdomain", "tags": [ "tenants" ], "description": "TENANCY_MODE=multi only. The edge proxy asks here before requesting a certificate for ``; anything but `.` is 404, so a stray DNS record pointed at this IP cannot make us issue certificates (docs/22 §3).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 253 }, "in": "query", "name": "domain", "required": true, "description": "The hostname Caddy is about to obtain a certificate for" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "slug": { "type": "string" } }, "required": [ "ok", "slug" ], "additionalProperties": false } } } } } } }, "/v1/auth/signup": { "post": { "summary": "Hosted: create an organisation (trial tenant) and mail its owner a signup magic link", "tags": [ "tenants" ], "description": "TENANCY_MODE=multi only. Provisions `t_` at once (plan trial, 14 days) with the e-mail as owner, then mails a single-use link to `GET /v1/auth/consume`. Outside production the response also carries `magicLink`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "orgName": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "description": "Derived from orgName (or the e-mail domain) when absent; must be unique", "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{2,30}$" } }, "required": [ "email", "orgName" ] } } } }, "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "slug": { "type": "string" }, "email": { "type": "string" }, "expiresAt": { "type": "string" }, "magicLink": { "description": "Only outside production (dev / mock mail): the link that was mailed", "type": "string" } }, "required": [ "accepted", "email" ], "additionalProperties": false } } } } } } }, "/v1/auth/magic": { "post": { "summary": "Hosted: mail a login magic link to an existing tenant user", "tags": [ "tenants" ], "description": "Always 202 (no account enumeration). With several tenants for the e-mail and no `slug` → 400 `slug_required` listing them. Outside production the response carries `magicLink` when one was issued.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "slug": { "description": "Required when the e-mail belongs to more than one tenant", "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{2,30}$" } }, "required": [ "email" ] } } } }, "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "slug": { "type": "string" }, "email": { "type": "string" }, "expiresAt": { "type": "string" }, "magicLink": { "description": "Only outside production (dev / mock mail): the link that was mailed", "type": "string" } }, "required": [ "accepted", "email" ], "additionalProperties": false } } } } } } }, "/v1/auth/consume": { "get": { "summary": "Hosted: consume a magic link → session cookie → redirect to the console", "tags": [ "tenants" ], "description": "Single use. Opens a session bound to the link’s tenant (`uid` = e-mail, tenant role owner/admin/member) and redirects to `CONSOLE_URL`. Unknown / used / expired → 401 `magic_link_invalid`.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "token", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/tenants/me": { "get": { "summary": "Hosted: the tenant of this session — plan, trial, limits, this month’s usage, your tenant role", "tags": [ "tenants" ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/topics": { "get": { "summary": "Topics of a unit (active only unless all=true)", "tags": [ "topics" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "unitId", "required": false }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "in": "query", "name": "all", "required": false, "description": "Include inactive topics" } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "unitId": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "unitId": { "type": "string" }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "additionalProperties": false, "description": "Localised text; zh-TW is mandatory" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "createdBy": { "type": "string" }, "createdAt": { "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))$" }, "updatedAt": { "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))$" } }, "required": [ "id", "unitId", "label", "description", "active", "createdBy", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "unitId", "items" ], "additionalProperties": false } } } } } }, "post": { "summary": "Create a topic for the unit (composer+)", "tags": [ "topics" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "unitId": { "description": "Console users with several units pick one; producers are pinned to their credential", "type": "string" }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "description": { "type": "string", "maxLength": 200 } }, "required": [ "label" ] } } } }, "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "unitId": { "type": "string" }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "additionalProperties": false, "description": "Localised text; zh-TW is mandatory" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "createdBy": { "type": "string" }, "createdAt": { "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))$" }, "updatedAt": { "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))$" } }, "required": [ "id", "unitId", "label", "description", "active", "createdBy", "createdAt", "updatedAt" ], "additionalProperties": false } } } } } } }, "/v1/topics/{id}": { "get": { "summary": "One topic", "tags": [ "topics" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "unitId": { "type": "string" }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "additionalProperties": false, "description": "Localised text; zh-TW is mandatory" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "createdBy": { "type": "string" }, "createdAt": { "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))$" }, "updatedAt": { "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))$" } }, "required": [ "id", "unitId", "label", "description", "active", "createdBy", "createdAt", "updatedAt" ], "additionalProperties": false } } } } } }, "patch": { "summary": "Rename, describe or deactivate a topic (composer+); an inactive topic cannot be used for new messages", "tags": [ "topics" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "description": "Localised text; zh-TW is mandatory" }, "description": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "active": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "unitId": { "type": "string" }, "label": { "type": "object", "properties": { "zh-TW": { "type": "string" }, "en": { "type": "string" } }, "required": [ "zh-TW" ], "additionalProperties": false, "description": "Localised text; zh-TW is mandatory" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "createdBy": { "type": "string" }, "createdAt": { "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))$" }, "updatedAt": { "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))$" } }, "required": [ "id", "unitId", "label", "description", "active", "createdBy", "createdAt", "updatedAt" ], "additionalProperties": false } } } } } } }, "/v1/metrics/executive": { "get": { "summary": "Executive metrics: reach, opt-outs, response status, pattern completion, funnel, interests, alumni (counts only)", "tags": [ "metrics" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "unitId", "required": false, "description": "One unit (approver+ there, or the producer credential’s unit); omit for the organisation (system administrators)" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 365 }, "in": "query", "name": "days", "required": false, "description": "Window in days (default 30)" } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/metrics/trend": { "get": { "summary": "Nightly metric points for a scope, oldest first (from hub_metric_snapshot)", "tags": [ "metrics" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "unitId", "required": false, "description": "One unit (approver+ there, or the producer credential’s unit); omit for the organisation (system administrators)" }, { "schema": { "default": 30, "type": "integer", "minimum": 1, "maximum": 365 }, "in": "query", "name": "days", "required": false, "description": "How many nightly points to return" } ], "security": [ { "session": [] }, { "producerKey": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/metrics/snapshot": { "post": { "summary": "Write today’s metric point for every scope now (system administrator); the worker does this nightly", "tags": [ "metrics" ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/site/events": { "post": { "summary": "Marketing-site beacon: record one anonymous page view / CTA click / form request", "tags": [ "site" ], "description": "TENANCY_MODE=multi only (404 otherwise). JSON body `{kind, path?, ref?, source?, lang?}` — kind ∈ view | line_click | trial_request | demo_request; sent as `text/plain` by sendBeacon, so it is parsed here rather than by the content-type parser. Crawlers are acknowledged but not stored. Always 204.", "responses": { "200": { "description": "Default Response" } } } } }, "servers": [ { "url": "http://localhost:8090" } ], "tags": [ { "name": "messages", "description": "Producer API: message intents, dry-run and the approval state machine" }, { "name": "templates", "description": "Unit templates with typed variables" }, { "name": "scenarios", "description": "Conversation scenarios (DAG of primitives)" }, { "name": "patterns", "description": "Pattern wizard: build a scenario from a config; reports" }, { "name": "groups", "description": "Groups and static member lists" }, { "name": "schedules", "description": "once / delay / recurring schedules" }, { "name": "topics", "description": "Channel topics（主題）of a unit; recipients unsubscribe per topic" }, { "name": "metrics", "description": "Executive view（戰情室）: counts only, for BI / CRM pulls" }, { "name": "catalogue", "description": "Categories, units, quota, audit, health" }, { "name": "events", "description": "校務系統 events (HMAC)" }, { "name": "webhooks", "description": "Provider callbacks (LINE, email, mock)" }, { "name": "identity", "description": "Identity API for liff: addresses and consents" }, { "name": "me", "description": "End-user inbox and preferences (LIFF)" }, { "name": "auth", "description": "Console login (SSO or mock) and sessions" }, { "name": "llm", "description": "User-configured LLM providers and usage" }, { "name": "knowledge", "description": "Versioned knowledge sets, sources, publish/rollback, hybrid search" }, { "name": "memory", "description": "Subject memory (facts, summaries) and the composed context" }, { "name": "handoffs", "description": "Avatar handoff context and session callbacks" }, { "name": "tenants", "description": "Hosted multi-tenant (TENANCY_MODE=multi): self-serve signup, magic-link login, the current tenant" } ] }