{ "openapi": "3.1.1", "info": { "title": "Lumi CX Portal API", "version": "1.0.0", "description": "Workspace-bound external business API. Every operation requires an unexpired, unrevoked Developer key and its listed permission. Keys default to read-only. Workspace owners control issuance. Login, portal configuration and platform administration are not exposed through these keys." }, "servers": [ { "url": "https://api.lumi-cx.com/api/v1", "description": "Shared API edge. X-Luma-Workspace-Host selects the workspace; the Bearer key must belong to it." }, { "url": "https://{workspace}.lumi-cx.com/api/v1", "description": "Workspace-host routing (requires your deployment to route /api to this service)", "variables": { "workspace": { "default": "your-workspace", "description": "Your workspace slug" } } } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Introduction" }, { "name": "Ideas" }, { "name": "Journeys" }, { "name": "Surveys" }, { "name": "SOPs" }, { "name": "Webhooks" }, { "name": "Knowledge Bank" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Lumi API key", "description": "Use an unexpired Developer key with the operation's x-required-scopes permissions. Workspace host must match. Rotation invalidates the previous secret; revocation is immediate for subsequent requests." } }, "parameters": { "id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, "limit": { "name": "limit", "in": "query", "description": "Maximum records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "offset": { "name": "offset", "in": "query", "description": "Number of records to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0, "maximum": 2147483647 } }, "workspaceHost": { "name": "X-Luma-Workspace-Host", "in": "header", "description": "Your workspace host, e.g. acme.lumi-cx.com. Required on api.lumi-cx.com. This header never grants access: the Bearer key must belong to the selected workspace.", "schema": { "type": "string" }, "required": true, "example": "acme.lumi-cx.com" } }, "schemas": { "Idea": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "titleAr": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "module": { "type": "string" }, "moderationStatus": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "visibility": { "type": "string", "enum": [ "private", "published" ] }, "votes": { "type": "integer" }, "officialUpdate": { "type": "string" }, "effortScore": { "type": "number" }, "benefitScore": { "type": "number" }, "priorityScore": { "type": "number" }, "priorityBand": { "type": "string" }, "internalTags": { "type": "array", "items": { "type": "string" } }, "rejectionReason": { "type": "string" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Journey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "titleEn": { "type": "string" }, "titleAr": { "type": "string" }, "publishedVersionId": { "type": [ "string", "null" ], "format": "uuid" }, "pairId": { "type": [ "string", "null" ], "format": "uuid" }, "pairVariant": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Survey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "nameAr": { "type": "string" }, "team": { "type": "string" }, "createdBy": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "themeLogoUrl": { "type": "string" }, "themePrimaryColor": { "type": "string" }, "targetingRules": { "type": "object", "properties": {} }, "designId": { "type": [ "string", "null" ], "format": "uuid" }, "currentVersionId": { "type": [ "string", "null" ], "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Error": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "invalid_body" }, "message": { "type": "string" } } }, "IdeaMutation": { "type": "object", "properties": { "id": { "type": "string" }, "title_en": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "module": { "type": "string" }, "votes": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } }, "JourneyMutation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title_en": { "type": "string" }, "title_ar": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SopWriteBody": { "type": "object", "required": [ "ticketDescription", "infoToCollect", "actionsToTakeFrontline", "ticketOwner", "actionsToTakeOwner", "caseType", "accountableTeam", "closureApproval" ], "description": "At least one of titleEn/titleAr is required. escalationLevel1 is required except for inquiry. Directory references come from GET /sops/directory. PUT replaces editable content, not a partial patch. Legacy user/role references remain accepted by the service.", "properties": { "titleEn": { "type": "string", "example": "Customer refund review" }, "titleAr": { "type": "string", "example": "" }, "ticketDescription": { "type": "string", "minLength": 30, "example": "Review the customer's refund request and verify the original payment details." }, "infoToCollect": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "text": { "type": "string" }, "children": { "type": "array", "items": { "type": "string" } } } } ] }, "example": [ "Verify the customer details" ] }, "actionsToTakeFrontline": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "text": { "type": "string" }, "children": { "type": "array", "items": { "type": "string" } } } } ] }, "example": [ "Verify the customer details" ] }, "ticketOwner": { "type": "object", "required": [ "kind", "id", "label" ], "properties": { "kind": { "type": "string", "enum": [ "person", "team" ] }, "id": { "type": "string" }, "label": { "type": "string" } }, "example": { "kind": "person", "id": "replace-with-directory-id", "label": "Directory member" } }, "actionsToTakeOwner": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "text": { "type": "string" }, "children": { "type": "array", "items": { "type": "string" } } } } ] }, "example": [ "Verify the customer details" ] }, "caseType": { "type": "string", "enum": [ "complaint", "inquiry", "suggestion", "request", "internal_ticket" ], "example": "complaint" }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium" }, "slaValue": { "type": "integer", "minimum": 1, "maximum": 2147483647, "default": 24 }, "slaUnit": { "type": "string", "enum": [ "hours", "days" ], "default": "hours" }, "accountableTeam": { "type": "object", "required": [ "kind", "id", "label" ], "properties": { "kind": { "type": "string", "enum": [ "person", "team" ] }, "id": { "type": "string" }, "label": { "type": "string" } }, "example": { "kind": "team", "id": "replace-with-directory-id", "label": "Support" } }, "escalationLevel1": { "type": "object", "required": [ "kind", "id", "label" ], "properties": { "kind": { "type": "string", "enum": [ "person", "team" ] }, "id": { "type": "string" }, "label": { "type": "string" } }, "example": { "kind": "person", "id": "replace-with-directory-id", "label": "Directory member" } }, "escalationLevel2": { "type": "object", "required": [ "kind", "id", "label" ], "properties": { "kind": { "type": "string", "enum": [ "person", "team" ] }, "id": { "type": "string" }, "label": { "type": "string" } }, "example": { "kind": "person", "id": "replace-with-directory-id", "label": "Directory member" } }, "closureApproval": { "type": "object", "required": [ "kind", "id", "label" ], "properties": { "kind": { "type": "string", "enum": [ "person", "team" ] }, "id": { "type": "string" }, "label": { "type": "string" } }, "example": { "kind": "person", "id": "replace-with-directory-id", "label": "Directory member" } }, "department": { "type": "string", "enum": [ "", "cx", "tech_support", "csm", "sales", "pm", "management" ], "default": "tech_support" }, "notifyOnCreation": { "type": "array", "items": { "type": "object", "required": [ "kind", "id", "label" ], "properties": { "kind": { "type": "string", "enum": [ "person", "team" ] }, "id": { "type": "string" }, "label": { "type": "string" } }, "example": { "kind": "person", "id": "replace-with-directory-id", "label": "Directory member" } }, "example": [] }, "ticketCategory": { "type": "object", "properties": { "l1": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" } } }, "l2": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" } } }, "l3": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" } } } }, "example": { "l1": null, "l2": null, "l3": null } }, "smsNotifications": { "type": "array", "items": { "type": "string", "enum": [ "open", "delay", "resolution" ] }, "example": [] }, "followUpCall": { "type": "boolean", "default": false }, "csatSurvey": { "type": "boolean", "default": false }, "notes": { "type": "string", "example": "" } } }, "Sop": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serial": { "type": "string", "example": "TS-0001" }, "status": { "type": "string", "enum": [ "draft", "under_review", "published" ], "example": "draft" }, "titleEn": { "type": "string", "example": "Customer refund review" }, "titleAr": { "type": "string", "example": "" }, "ticketDescription": { "type": "string", "minLength": 30, "example": "Review the customer's refund request and verify the original payment details." }, "infoToCollect": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "text": { "type": "string" }, "children": { "type": "array", "items": { "type": "string" } } } } ] }, "example": [ "Verify the customer details" ] }, "actionsToTakeFrontline": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "text": { "type": "string" }, "children": { "type": "array", "items": { "type": "string" } } } } ] }, "example": [ "Verify the customer details" ] }, "ticketOwner": { "type": "object", "required": [ "kind", "id", "label" ], "properties": { "kind": { "type": "string", "enum": [ "person", "team" ] }, "id": { "type": "string" }, "label": { "type": "string" } }, "example": { "kind": "person", "id": "replace-with-directory-id", "label": "Directory member" } }, "actionsToTakeOwner": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "text": { "type": "string" }, "children": { "type": "array", "items": { "type": "string" } } } } ] }, "example": [ "Verify the customer details" ] }, "caseType": { "type": "string", "enum": [ "complaint", "inquiry", "suggestion", "request", "internal_ticket" ], "example": "complaint" }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium" }, "slaValue": { "type": "integer", "minimum": 1, "maximum": 2147483647, "default": 24 }, "slaUnit": { "type": "string", "enum": [ "hours", "days" ], "default": "hours" }, "accountableTeam": { "type": "object", "required": [ "kind", "id", "label" ], "properties": { "kind": { "type": "string", "enum": [ "person", "team" ] }, "id": { "type": "string" }, "label": { "type": "string" } }, "example": { "kind": "team", "id": "replace-with-directory-id", "label": "Support" } }, "escalationLevel1": { "type": "object", "required": [ "kind", "id", "label" ], "properties": { "kind": { "type": "string", "enum": [ "person", "team" ] }, "id": { "type": "string" }, "label": { "type": "string" } }, "example": { "kind": "person", "id": "replace-with-directory-id", "label": "Directory member" } }, "escalationLevel2": { "type": "object", "required": [ "kind", "id", "label" ], "properties": { "kind": { "type": "string", "enum": [ "person", "team" ] }, "id": { "type": "string" }, "label": { "type": "string" } }, "example": { "kind": "person", "id": "replace-with-directory-id", "label": "Directory member" } }, "closureApproval": { "type": "object", "required": [ "kind", "id", "label" ], "properties": { "kind": { "type": "string", "enum": [ "person", "team" ] }, "id": { "type": "string" }, "label": { "type": "string" } }, "example": { "kind": "person", "id": "replace-with-directory-id", "label": "Directory member" } }, "department": { "type": "string", "enum": [ "", "cx", "tech_support", "csm", "sales", "pm", "management" ], "default": "tech_support" }, "notifyOnCreation": { "type": "array", "items": { "type": "object", "required": [ "kind", "id", "label" ], "properties": { "kind": { "type": "string", "enum": [ "person", "team" ] }, "id": { "type": "string" }, "label": { "type": "string" } }, "example": { "kind": "person", "id": "replace-with-directory-id", "label": "Directory member" } }, "example": [] }, "ticketCategory": { "type": "object", "properties": { "l1": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" } } }, "l2": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" } } }, "l3": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" } } } }, "example": { "l1": null, "l2": null, "l3": null } }, "smsNotifications": { "type": "array", "items": { "type": "string", "enum": [ "open", "delay", "resolution" ] }, "example": [] }, "followUpCall": { "type": "boolean", "default": false }, "csatSurvey": { "type": "boolean", "default": false }, "notes": { "type": "string", "example": "" }, "createdBy": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "localization": { "type": "object", "additionalProperties": true } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Idea notifications" }, "url": { "type": "string", "format": "uri", "example": "https://receiver.example.com/webhooks/lumi" }, "secretPrefix": { "type": "string", "example": "whsec_EXAMPLE" }, "authenticationConfigured": { "type": "boolean", "example": true }, "events": { "type": "array", "items": { "type": "string", "enum": [ "idea.submitted", "idea.published", "idea.status_changed", "idea.official_update_added", "idea.comment_added", "idea.voted", "idea.followed" ] } }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "WebhookWrite": { "type": "object", "required": [ "url", "events" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Include to update a webhook in this workspace; omit to create." }, "name": { "type": "string", "maxLength": 120, "default": "Webhook" }, "url": { "type": "string", "format": "uri", "description": "Public HTTPS endpoint. Private addresses and redirects are rejected." }, "events": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "idea.submitted", "idea.published", "idea.status_changed", "idea.official_update_added", "idea.comment_added", "idea.voted", "idea.followed" ] } }, "enabled": { "type": "boolean", "default": false, "description": "Creation, URL changes and secret rotation disable delivery. Set true in a later update after configuring the receiver." } }, "example": { "name": "Idea notifications", "url": "https://receiver.example.com/webhooks/lumi", "events": [ "idea.published" ], "enabled": false } }, "Pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "offset", "total", "hasMore" ], "example": { "limit": 25, "offset": 0, "total": 1, "hasMore": false } }, "IdeaWrite": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 160 }, "titleAr": { "type": "string", "maxLength": 160 }, "description": { "type": "string", "maxLength": 4000 }, "status": { "type": "string", "maxLength": 100, "description": "Configured status value from /ideas/labels." }, "module": { "type": "string", "maxLength": 100, "description": "Configured module value from /ideas/labels." } }, "required": [ "title" ], "example": { "title": "Improve the onboarding guide", "description": "Add a checklist for the first setup." } }, "IdeaPublication": { "type": "object", "properties": { "moderationStatus": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "visibility": { "type": "string", "enum": [ "private", "published" ] }, "officialUpdate": { "type": "string", "maxLength": 2000 }, "category": { "type": "string" }, "module": { "type": "string" }, "status": { "type": "string" }, "effortScore": { "type": "number", "minimum": 1, "maximum": 5 }, "benefitScore": { "type": "number", "minimum": 1, "maximum": 5 }, "internalTags": { "type": "array", "items": { "type": "string" } }, "rejectionReason": { "type": "string" } } }, "KbLink": { "type": "object", "properties": { "start": { "type": "integer" }, "end": { "type": "integer" }, "url": { "type": "string" } } }, "KbBlock": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "heading1", "heading2", "heading3", "paragraph", "listItem", "note", "callout", "image", "video", "file", "table", "divider", "unsupported" ] }, "text": { "type": "string" }, "html": { "type": "string" }, "note": { "type": "string" }, "dir": { "type": "string", "enum": [ "ltr", "rtl" ] }, "src": { "type": "string" }, "url": { "type": "string" }, "alt": { "type": "string" }, "mediaType": { "type": "string", "enum": [ "image", "video", "file" ] }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/KbLink" } }, "rows": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/KbLink" } }, "images": { "type": "array", "items": { "type": "string" } } } } } } }, "required": [ "type" ], "example": { "type": "paragraph", "text": "Follow these steps to get started." } }, "KbCategory": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "parentId": { "type": [ "string", "null" ], "format": "uuid" }, "nameEn": { "type": "string" }, "nameAr": { "type": "string" }, "slug": { "type": "string" }, "icon": { "type": "string" }, "sortOrder": { "type": "integer" }, "active": { "type": "boolean" }, "articleCount": { "type": "integer" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/KbCategory" }, "example": [] } } }, "KbCategoryWrite": { "type": "object", "properties": { "parentId": { "type": [ "string", "null" ], "format": "uuid" }, "nameEn": { "type": "string", "maxLength": 160 }, "nameAr": { "type": "string", "maxLength": 160 }, "slug": { "type": "string" }, "icon": { "type": "string" }, "sortOrder": { "type": "integer" }, "active": { "type": "boolean" } }, "example": { "nameEn": "Getting started", "nameAr": "البدء", "active": true } }, "KbArticleWrite": { "type": "object", "properties": { "categoryId": { "type": [ "string", "null" ], "format": "uuid" }, "titleEn": { "type": "string", "maxLength": 240 }, "titleAr": { "type": "string", "maxLength": 240 }, "summaryEn": { "type": "string", "maxLength": 600 }, "summaryAr": { "type": "string", "maxLength": 600 }, "contentBlocksEn": { "type": "array", "items": { "$ref": "#/components/schemas/KbBlock" }, "maxItems": 500 }, "contentBlocksAr": { "type": "array", "items": { "$ref": "#/components/schemas/KbBlock" }, "maxItems": 500 }, "active": { "type": "boolean" }, "revision": { "type": "integer", "minimum": 1, "description": "Required for edits; use the latest revision returned by GET." } }, "example": { "titleEn": "Welcome guide", "contentBlocksEn": [ { "type": "paragraph", "text": "Follow these steps to get started." } ], "active": true } }, "KbArticle": { "type": "object", "properties": { "categoryId": { "type": [ "string", "null" ], "format": "uuid" }, "titleEn": { "type": "string", "maxLength": 240 }, "titleAr": { "type": "string", "maxLength": 240 }, "summaryEn": { "type": "string", "maxLength": 600 }, "summaryAr": { "type": "string", "maxLength": 600 }, "contentBlocksEn": { "type": "array", "items": { "$ref": "#/components/schemas/KbBlock" }, "maxItems": 500 }, "contentBlocksAr": { "type": "array", "items": { "$ref": "#/components/schemas/KbBlock" }, "maxItems": 500 }, "active": { "type": "boolean" }, "revision": { "type": "integer" }, "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "contentBlocks": { "type": "array", "items": { "$ref": "#/components/schemas/KbBlock" } }, "createdBy": { "type": "string" }, "updatedBy": { "type": "string" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "openCount30d": { "type": "integer" }, "openCountAll": { "type": "integer" } } }, "JourneyContent": { "type": "object", "description": "Complete macro (schema: 2) or micro (schema: micro-v1) document. Read-modify-write the returned document to retain all fields. Micro content includes scenarios, step messages, choices, connector rules, timing and support documents.", "properties": { "schema": { "oneOf": [ { "type": "integer", "const": 2 }, { "type": "string", "const": "micro-v1" } ] }, "schemaRevision": { "type": "integer" }, "stages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "titleEn": { "type": "string" }, "titleAr": { "type": "string" }, "microJourneyPairs": { "type": "array", "items": { "type": "object", "properties": { "pairId": { "type": "string", "format": "uuid" }, "titleEn": { "type": "string" }, "titleAr": { "type": "string" } } } } } } }, "rows": { "type": "array", "items": { "type": "object", "properties": {} } }, "cells": { "type": "object", "properties": {} }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "titleEn": { "type": "string" }, "titleAr": { "type": "string" }, "descEn": { "type": "string" }, "descAr": { "type": "string" }, "channelIcon": { "type": [ "string", "null" ], "enum": [ "whatsapp", "web", "app", "email", null ] }, "channelMessageEn": { "type": "string" }, "channelMessageAr": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "question", "manual", "customer", "action" ] }, "waitDays": { "type": "number" }, "noteEn": { "type": "string" }, "noteAr": { "type": "string" }, "ownerTeams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" } } } }, "order": { "type": "integer" } } } }, "connectors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fromId": { "type": "string" }, "toId": { "type": "string" }, "labelEn": { "type": "string" }, "labelAr": { "type": "string" }, "arrow": { "type": "string", "enum": [ "end", "both", "none" ] }, "customerReply": { "type": "boolean" }, "scenarioIds": { "type": "array", "items": { "type": "string" } } } } }, "scenarios": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "labelEn": { "type": "string" }, "labelAr": { "type": "string" }, "color": { "type": "string" } } } }, "supportDocuments": { "type": "array", "items": { "type": "object", "properties": {} } } }, "additionalProperties": true, "example": { "schema": 2, "stages": [ { "id": "onboarding", "titleEn": "Onboarding", "titleAr": "", "microJourneyPairs": [] } ], "rows": [], "cells": {} } }, "JourneyVersion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "journeyId": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "parentVersionId": { "type": [ "string", "null" ], "format": "uuid" }, "content": { "$ref": "#/components/schemas/JourneyContent" }, "createdBy": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revision": { "type": "integer" }, "sourceRevision": { "type": [ "integer", "null" ] }, "legacyOrigin": { "type": [ "string", "null" ] }, "diagnostics": { "type": "array", "items": { "type": "object", "properties": { "severity": { "type": "string" }, "message": { "type": "string" } } } } } }, "JourneyVersionWrite": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/JourneyContent" }, "versionId": { "type": "string", "format": "uuid" }, "parentVersionId": { "type": "string", "format": "uuid" }, "label": { "type": "string", "maxLength": 120 }, "expectedRevision": { "type": "integer", "minimum": 1 }, "contentContractVersion": { "type": "integer", "const": 2 }, "requestId": { "type": "string", "format": "uuid", "description": "Unique request identifier required for enhanced creation/restoration; reuse only for retrying the identical request." }, "allowStaleSource": { "type": "boolean" } }, "required": [ "content" ], "example": { "label": "Version 2", "content": { "schema": 2, "stages": [ { "id": "onboarding", "titleEn": "Onboarding", "titleAr": "", "microJourneyPairs": [] } ], "rows": [], "cells": {} } } }, "JourneyPublish": { "type": "object", "properties": { "expectedRevision": { "type": "integer" }, "contentContractVersion": { "type": "integer", "const": 2 }, "microSelections": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid" }, "revision": { "type": "integer" } }, "required": [ "versionId", "revision" ] } } } } }, "SurveyCondition": { "type": "object", "properties": { "operator": { "type": "string", "description": "Type-specific operator; numeric comparisons, text matching, date comparisons, multi-choice membership/count, or known/unknown." }, "value": {}, "row": { "type": "string" } }, "required": [ "operator" ] }, "SurveyVisibility": { "type": "object", "properties": { "effect": { "type": "string", "enum": [ "show", "hide" ] }, "match": { "type": "string", "enum": [ "all", "any" ] }, "conditions": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/SurveyCondition" }, { "type": "object", "properties": { "questionId": { "type": "string" } }, "required": [ "questionId" ] } ] } } }, "required": [ "effect", "match", "conditions" ] }, "SurveyQuestionOptions": { "type": "object", "properties": { "choices": { "type": "array", "items": { "type": "string" } }, "choicesEn": { "type": "array", "items": { "type": "string" } }, "choicesAr": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "string" } }, "columns": { "type": "array", "items": { "type": "string" } }, "min": { "type": "number" }, "max": { "type": "number" }, "visibility": { "$ref": "#/components/schemas/SurveyVisibility" }, "optionFilters": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/SurveyVisibility" }, { "type": "object", "properties": { "choice": { "type": "string" } }, "required": [ "choice" ] } ] } } }, "additionalProperties": true }, "SurveyQuestion": { "type": "object", "properties": { "id": { "type": "string" }, "orderIndex": { "type": "integer" }, "type": { "type": "string", "enum": [ "welcome", "statement", "end", "redirect", "text", "email", "number", "date", "yesno", "rating", "nps", "justRight", "choice", "singleChoice", "multiChoice", "dropdown", "matrix" ] }, "promptEn": { "type": "string" }, "promptAr": { "type": "string" }, "options": { "$ref": "#/components/schemas/SurveyQuestionOptions" }, "required": { "type": "boolean" }, "routes": { "type": "array", "items": { "type": "object", "properties": { "condition": { "$ref": "#/components/schemas/SurveyCondition" }, "nextQuestionId": { "type": "string" } }, "required": [ "condition", "nextQuestionId" ] } } }, "required": [ "type", "options" ], "anyOf": [ { "required": [ "promptEn" ] }, { "required": [ "promptAr" ] } ] }, "SurveyVersion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "surveyId": { "type": "string", "format": "uuid" }, "versionNumber": { "type": "integer" }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyQuestion" } } } }, "SurveyDesign": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "team": { "type": "string" }, "name": { "type": "string" }, "config": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SurveyResult": { "type": "object", "properties": { "questionId": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "count": { "type": "integer" }, "average": { "type": "number" }, "distribution": { "type": "object", "additionalProperties": { "type": "integer" } }, "textAnswers": { "type": "array", "items": { "type": "string" } } } }, "SurveyResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "submittedAt": { "type": "string", "format": "date-time" }, "versionId": { "type": "string", "format": "uuid" }, "versionNumber": { "type": "integer" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "questionId": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "value": {} }, "required": [ "questionId", "type", "value" ] } } } }, "SopCategories": { "type": "object", "properties": { "l1": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "order": { "type": "integer" } } } }, "l2": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "order": { "type": "integer" } } } }, "l3": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "order": { "type": "integer" } } } }, "l1l2": { "type": "array", "items": { "type": "object", "properties": { "l1Id": { "type": "string" }, "l2Id": { "type": "string" } } } }, "l2l3": { "type": "array", "items": { "type": "object", "properties": { "l2Id": { "type": "string" }, "l3Id": { "type": "string" } } } } } }, "SopComment": { "type": "object", "properties": { "id": { "type": "string" }, "sopId": { "type": "string" }, "authorEmail": { "type": "string" }, "authorName": { "type": "string" }, "body": { "type": "string" }, "action": { "type": "string", "enum": [ "comment", "sent_back", "approved" ] }, "createdAt": { "type": "string", "format": "date-time" } } } }, "responses": { "Unauthorized": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "The resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/me": { "get": { "tags": [ "Introduction" ], "summary": "Check the current API key", "operationId": "getCurrentWorkspace", "responses": { "200": { "description": "The key is valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "workspace": { "type": "string" }, "authenticated": { "type": "boolean" } } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/workspaceHost" } ], "x-required-scopes": [] } }, "/ideas": { "get": { "tags": [ "Ideas" ], "summary": "List ideas", "description": "Paginated workspace ideas with descriptions, moderation, visibility, priority and timestamps. Submitter identities are omitted.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Idea" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "ok", "data", "pagination" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "ideas:read" ], "operationId": "get_ideas" }, "post": { "tags": [ "Ideas" ], "summary": "Create an idea", "description": "Creates or updates the editable idea fields. New ideas are private and pending moderation. Creation and status changes queue identifier-only webhooks after commit.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" } ], "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Idea" } }, "required": [ "ok", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdeaWrite" } } } }, "x-required-scopes": [ "ideas:write" ], "operationId": "post_ideas" } }, "/ideas/{id}": { "put": { "tags": [ "Ideas" ], "summary": "Replace an idea", "description": "Creates or updates the editable idea fields. New ideas are private and pending moderation. Creation and status changes queue identifier-only webhooks after commit.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Idea" } }, "required": [ "ok", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdeaWrite" } } } }, "x-required-scopes": [ "ideas:write" ], "operationId": "put_ideas_id_" }, "patch": { "tags": [ "Ideas" ], "summary": "Update an idea", "description": "Creates or updates the editable idea fields. New ideas are private and pending moderation. Creation and status changes queue identifier-only webhooks after commit.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Idea" } }, "required": [ "ok", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 160 }, "titleAr": { "type": "string", "maxLength": 160 }, "description": { "type": "string", "maxLength": 4000 }, "status": { "type": "string", "maxLength": 100, "description": "Configured status value from /ideas/labels." }, "module": { "type": "string", "maxLength": 100, "description": "Configured module value from /ideas/labels." } }, "required": [], "example": { "title": "Improve the onboarding guide", "description": "Add a checklist for the first setup." } } } } }, "x-required-scopes": [ "ideas:write" ], "operationId": "patch_ideas_id_" }, "delete": { "tags": [ "Ideas" ], "summary": "Delete an idea", "description": "Operates only on the authenticated workspace. The response includes the resulting resource fields.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "ideas:delete" ], "operationId": "delete_ideas_id_" }, "get": { "tags": [ "Ideas" ], "summary": "Read an idea", "description": "Read complete idea business fields. Submitter emails, identity hashes and customer context are omitted.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Idea" } }, "required": [ "ok", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "ideas:read" ], "operationId": "get_ideas_id_" } }, "/journeys": { "get": { "tags": [ "Journeys" ], "summary": "List journeys", "description": "Paginated macro and micro journey metadata. Use the detail endpoint to retrieve all versions and full paths.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "journeys": { "type": "array", "items": { "$ref": "#/components/schemas/Journey" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "ok", "journeys", "pagination" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "journeys:read" ], "operationId": "get_journeys" }, "post": { "tags": [ "Journeys" ], "summary": "Create a journey", "description": "Create a macro journey and its first draft. At least one title is required.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "journeyId": { "type": "string", "format": "uuid" }, "version": { "$ref": "#/components/schemas/JourneyVersion" } }, "required": [ "ok", "journeyId", "version" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "titleEn": { "type": "string" }, "titleAr": { "type": "string" }, "title": { "type": "string", "description": "Compatibility alias for titleEn." } } } } } }, "x-required-scopes": [ "journeys:write" ], "operationId": "post_journeys" } }, "/surveys": { "get": { "tags": [ "Surveys" ], "summary": "List surveys", "description": "Return paginated active survey metadata, including drafts. Archived surveys are omitted.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "surveys": { "type": "array", "items": { "$ref": "#/components/schemas/Survey" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "ok", "surveys", "pagination" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "surveys:read" ], "operationId": "get_surveys" }, "post": { "tags": [ "Surveys" ], "summary": "Create a survey", "description": "Create a survey with its initial draft version and default design.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "survey": { "$ref": "#/components/schemas/Survey" }, "version": { "$ref": "#/components/schemas/SurveyVersion" }, "designs": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyDesign" } } }, "required": [ "ok", "survey", "version", "designs" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "language": { "type": "string", "enum": [ "en", "ar" ], "default": "en" } }, "required": [ "name" ] } } } }, "x-required-scopes": [ "surveys:write" ], "operationId": "post_surveys" } }, "/surveys/{id}": { "patch": { "tags": [ "Surveys" ], "summary": "Update survey settings", "description": "Update metadata, appearance and validated audience targeting. Status changes require publication or archival endpoints.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "survey": { "$ref": "#/components/schemas/Survey" } }, "required": [ "ok", "survey" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "nameAr": { "type": "string" }, "themeLogoUrl": { "type": "string" }, "themePrimaryColor": { "type": "string" }, "designId": { "type": "string", "format": "uuid" }, "targetingRules": { "type": "object", "properties": {} } } } } } }, "x-required-scopes": [ "surveys:write" ], "operationId": "patch_surveys_id_" }, "delete": { "tags": [ "Surveys" ], "summary": "Archive a survey", "description": "Archive the survey while retaining its versions and historical responses.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "surveys:delete" ], "operationId": "delete_surveys_id_" }, "get": { "tags": [ "Surveys" ], "summary": "Read a survey", "description": "Return all versions, full questions, type-specific options, routing, question visibility and option filtering. Does not include respondent answers.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "survey": { "$ref": "#/components/schemas/Survey" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyVersion" } }, "designs": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyDesign" } } }, "required": [ "ok", "survey", "versions", "designs" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "surveys:read" ], "operationId": "get_surveys_id_" } }, "/sops": { "get": { "tags": [ "SOPs" ], "summary": "List SOPs", "description": "Read-only keys see published SOPs. Keys also holding sops:write or sops:approve can see drafts and reviews.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "sops": { "type": "array", "items": { "$ref": "#/components/schemas/Sop" } } } } } } }, "400": { "description": "Invalid body or workflow state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SOP not found or not accessible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "sops:read" ], "operationId": "get_sops" }, "post": { "tags": [ "SOPs" ], "summary": "Create an SOP", "description": "Create a draft and assign its department serial. At least one of titleEn/titleAr is required. escalationLevel1 is required except for inquiry. Directory references come from GET /sops/directory. PUT replaces editable content, not a partial patch. Legacy user/role references remain accepted by the service.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "sop": { "$ref": "#/components/schemas/Sop" } } } } } }, "400": { "description": "Invalid body or workflow state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SOP not found or not accessible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SopWriteBody" } } } }, "x-required-scopes": [ "sops:write" ], "operationId": "post_sops" } }, "/sops/directory": { "get": { "tags": [ "SOPs" ], "summary": "Read SOP directory", "description": "Read selectable employees and departments synchronized from Company Profile. Use these stable directory IDs in SOP references.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "people": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "active": { "type": "boolean" }, "sourceUserId": { "type": "string", "format": "uuid" } } } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "sourceDepartmentId": { "type": "string", "format": "uuid" } } } } } } } } }, "400": { "description": "Invalid body or workflow state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SOP not found or not accessible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "sops:read" ], "operationId": "get_sops_directory" } }, "/sops/{id}": { "get": { "tags": [ "SOPs" ], "summary": "Read an SOP", "description": "Read an accessible SOP. Review comments are omitted for read-only keys.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "sop": { "$ref": "#/components/schemas/Sop" }, "comments": { "type": "array", "items": { "$ref": "#/components/schemas/SopComment" }, "example": [] } } } } } }, "400": { "description": "Invalid body or workflow state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SOP not found or not accessible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "sops:read" ], "operationId": "get_sops_id_" }, "put": { "tags": [ "SOPs" ], "summary": "Replace an SOP", "description": "Replace editable content; published SOPs return to draft. Under-review edits are rejected. At least one of titleEn/titleAr is required. escalationLevel1 is required except for inquiry. Directory references come from GET /sops/directory. PUT replaces editable content, not a partial patch. Legacy user/role references remain accepted by the service.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "sop": { "$ref": "#/components/schemas/Sop" } } } } } }, "400": { "description": "Invalid body or workflow state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SOP not found or not accessible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SopWriteBody" } } } }, "x-required-scopes": [ "sops:write" ], "operationId": "put_sops_id_" }, "delete": { "tags": [ "SOPs" ], "summary": "Delete an SOP", "description": "Delete an SOP. This action requires the separate sops:delete permission.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Invalid body or workflow state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SOP not found or not accessible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "sops:delete" ], "operationId": "delete_sops_id_" } }, "/sops/{id}/submit": { "post": { "tags": [ "SOPs" ], "summary": "Submit an SOP for review", "description": "Move a draft to under_review. Other starting states return 400.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "sop": { "$ref": "#/components/schemas/Sop" } } } } } }, "400": { "description": "Invalid body or workflow state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SOP not found or not accessible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "sops:write" ], "operationId": "post_sops_id_submit" } }, "/sops/{id}/approve": { "post": { "tags": [ "SOPs" ], "summary": "Approve an SOP", "description": "Publish an under-review SOP and record its approval. The separate sops:approve permission is required.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "sop": { "$ref": "#/components/schemas/Sop" } } } } } }, "400": { "description": "Invalid body or workflow state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SOP not found or not accessible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "sops:approve" ], "operationId": "post_sops_id_approve" } }, "/sops/{id}/send-back": { "post": { "tags": [ "SOPs" ], "summary": "Send an SOP back", "description": "Return an under-review SOP to draft and record required review feedback.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "sop": { "$ref": "#/components/schemas/Sop" } } } } } }, "400": { "description": "Invalid body or workflow state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SOP not found or not accessible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "type": "string", "minLength": 1, "example": "Add verification details before publication." } } } } } }, "x-required-scopes": [ "sops:approve" ], "operationId": "post_sops_id_send_back" } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "description": "Manage only this workspace's idea events. Creation and rotation return a Bearer secret once and disable delivery. Changing the URL also disables delivery; enable explicitly after configuring authentication. At most 50 webhooks per workspace.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "availableEvents": { "type": "array", "items": { "type": "string", "enum": [ "idea.submitted", "idea.published", "idea.status_changed", "idea.official_update_added", "idea.comment_added", "idea.voted", "idea.followed" ] } }, "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "webhooks:read" ], "operationId": "get_webhooks" }, "post": { "tags": [ "Webhooks" ], "summary": "Register or update a webhook", "description": "Manage only this workspace's idea events. Creation and rotation return a Bearer secret once and disable delivery. Changing the URL also disables delivery; enable explicitly after configuring authentication. At most 50 webhooks per workspace.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "webhook": { "$ref": "#/components/schemas/Webhook" } } } } } }, "201": { "description": "Created disabled; secret returned once", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "example": "whsec_EXAMPLE_NOT_A_REAL_CREDENTIAL", "description": "Returned once on creation/rotation. Save in a secret manager. Never present in list responses." } } } ] } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWrite" } } } }, "x-required-scopes": [ "webhooks:write", "ideas:read" ], "operationId": "post_webhooks" } }, "/webhooks/{id}": { "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook", "description": "Manage only this workspace's idea events. Creation and rotation return a Bearer secret once and disable delivery. Changing the URL also disables delivery; enable explicitly after configuring authentication. At most 50 webhooks per workspace.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "webhooks:delete" ], "operationId": "delete_webhooks_id_" } }, "/webhooks/{id}/rotate": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate webhook authentication", "description": "Manage only this workspace's idea events. Creation and rotation return a Bearer secret once and disable delivery. Changing the URL also disables delivery; enable explicitly after configuring authentication. At most 50 webhooks per workspace.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "example": "whsec_EXAMPLE_NOT_A_REAL_CREDENTIAL", "description": "Returned once on creation/rotation. Save in a secret manager. Never present in list responses." } } } ] } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "webhooks:write", "ideas:read" ], "operationId": "post_webhooks_id_rotate" } }, "/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Send a test event", "description": "Send synthetic data only. HTTP 200 reports the receiver outcome in delivered/status, or ok:false on network failure. No redirects are followed.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "delivered": { "type": "boolean" }, "status": { "type": "integer" }, "details": { "type": "string" }, "hint": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "webhooks:test", "ideas:read" ], "operationId": "post_webhooks_id_test" } }, "/ideas/labels": { "get": { "tags": [ "Ideas" ], "summary": "Read idea labels", "description": "Read configured label values and translations for status, module and internal tags.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "labels": { "type": "object", "additionalProperties": true } }, "required": [ "ok", "labels" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "ideas:read" ], "operationId": "get_ideas_labels" } }, "/ideas/{id}/publication": { "patch": { "tags": [ "Ideas" ], "summary": "Moderate or publish an idea", "description": "Update moderation, publication, priority, configured labels and official updates. Rejection requires a reason. Returns the affected publication fields; GET /ideas/{id} returns full details.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "idea": { "type": "object", "properties": { "id": { "type": "string" }, "moderation_status": { "type": "string" }, "visibility": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "module": { "type": "string" }, "official_update": { "type": "string" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "effort_score": { "type": "number" }, "benefit_score": { "type": "number" }, "priority_score": { "type": "number" }, "priority_band": { "type": "string" }, "internal_tags": { "type": "array", "items": { "type": "string" } }, "rejection_reason": { "type": "string" } } } }, "required": [ "ok", "idea" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdeaPublication" } } } }, "x-required-scopes": [ "ideas:write" ], "operationId": "patch_ideas_id_publication" } }, "/ideas/{id}/comments": { "get": { "tags": [ "Ideas" ], "summary": "Read idea comments", "description": "Paginated content history. Author identities and credentials are omitted; text can contain customer-provided information.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "visible", "hidden" ] } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "ok", "comments", "pagination" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "ideas:read" ], "operationId": "get_ideas_id_comments" } }, "/ideas/{id}/updates": { "get": { "tags": [ "Ideas" ], "summary": "Read idea updates", "description": "Paginated content history. Author identities and credentials are omitted; text can contain customer-provided information.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "updates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "ok", "updates", "pagination" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "ideas:read" ], "operationId": "get_ideas_id_updates" } }, "/sops/categories": { "get": { "tags": [ "SOPs" ], "summary": "Read SOP categories", "description": "Read the category hierarchy used to author SOPs.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "categories": { "$ref": "#/components/schemas/SopCategories" } } } } } }, "400": { "description": "Invalid body or workflow state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SOP not found or not accessible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "sops:read" ], "operationId": "get_sops_categories" } }, "/kb/categories": { "get": { "tags": [ "Knowledge Bank" ], "summary": "List knowledge categories", "description": "Return the category tree, active flags and article counts. Includes inactive categories for integration management.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/KbCategory" } } }, "required": [ "ok", "categories" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "kb:read" ], "operationId": "get_kb_categories" }, "post": { "tags": [ "Knowledge Bank" ], "summary": "Create a knowledge category", "description": "Create or partially update a category. Parent categories must belong to this workspace; cycles are rejected. Use active:false to deactivate.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" } ], "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "category": { "$ref": "#/components/schemas/KbCategory" } }, "required": [ "ok", "category" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbCategoryWrite" } } } }, "x-required-scopes": [ "kb:write" ], "operationId": "post_kb_categories" } }, "/kb/categories/{id}": { "patch": { "tags": [ "Knowledge Bank" ], "summary": "Update a knowledge category", "description": "Create or partially update a category. Parent categories must belong to this workspace; cycles are rejected. Use active:false to deactivate.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "category": { "$ref": "#/components/schemas/KbCategory" } }, "required": [ "ok", "category" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbCategoryWrite" } } } }, "x-required-scopes": [ "kb:write" ], "operationId": "patch_kb_categories_id_" } }, "/kb/articles": { "get": { "tags": [ "Knowledge Bank" ], "summary": "List knowledge articles", "description": "Search and paginate draft, published and archived articles with both language content blocks and current revisions. API reads do not increment human view counts.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "in": "query", "name": "query", "schema": { "type": "string" }, "description": "Search titles and summaries." }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "description": "Filter article status." }, { "in": "query", "name": "categoryId", "schema": { "type": "string", "format": "uuid" }, "description": "Filter by a category in this workspace." } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "articles": { "type": "array", "items": { "$ref": "#/components/schemas/KbArticle" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "ok", "articles", "pagination" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "kb:read" ], "operationId": "get_kb_articles" }, "post": { "tags": [ "Knowledge Bank" ], "summary": "Create a knowledge article", "description": "Create or partially update a draft. At least one title is required; edits require the current revision. Content HTML is sanitized. Status changes use explicit lifecycle endpoints.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" } ], "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "article": { "$ref": "#/components/schemas/KbArticle" } }, "required": [ "ok", "article" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbArticleWrite" } } } }, "x-required-scopes": [ "kb:write" ], "operationId": "post_kb_articles" } }, "/kb/articles/{id}": { "get": { "tags": [ "Knowledge Bank" ], "summary": "Read a knowledge article", "description": "Return bilingual content, category, status, revision, timestamps and view counts. Does not register a human view.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "article": { "$ref": "#/components/schemas/KbArticle" } }, "required": [ "ok", "article" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "kb:read" ], "operationId": "get_kb_articles_id_" }, "patch": { "tags": [ "Knowledge Bank" ], "summary": "Update a knowledge article", "description": "Create or partially update a draft. At least one title is required; edits require the current revision. Content HTML is sanitized. Status changes use explicit lifecycle endpoints.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "article": { "$ref": "#/components/schemas/KbArticle" } }, "required": [ "ok", "article" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "categoryId": { "type": [ "string", "null" ], "format": "uuid" }, "titleEn": { "type": "string", "maxLength": 240 }, "titleAr": { "type": "string", "maxLength": 240 }, "summaryEn": { "type": "string", "maxLength": 600 }, "summaryAr": { "type": "string", "maxLength": 600 }, "contentBlocksEn": { "type": "array", "items": { "$ref": "#/components/schemas/KbBlock" }, "maxItems": 500 }, "contentBlocksAr": { "type": "array", "items": { "$ref": "#/components/schemas/KbBlock" }, "maxItems": 500 }, "active": { "type": "boolean" }, "revision": { "type": "integer", "minimum": 1, "description": "Required for edits; use the latest revision returned by GET." } }, "example": { "revision": 1, "titleEn": "Updated welcome guide" }, "required": [ "revision" ] } } } }, "x-required-scopes": [ "kb:write" ], "operationId": "patch_kb_articles_id_" } }, "/kb/articles/{id}/publish": { "post": { "tags": [ "Knowledge Bank" ], "summary": "Publish a knowledge article", "description": "Supply the latest revision to prevent lost updates. Publishing requires an active draft with content. Archiving retains content; returning to draft removes it from published views.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "article": { "$ref": "#/components/schemas/KbArticle" } }, "required": [ "ok", "article" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 1 } }, "required": [ "revision" ] } } } }, "x-required-scopes": [ "kb:publish" ], "operationId": "post_kb_articles_id_publish" } }, "/kb/articles/{id}/archive": { "post": { "tags": [ "Knowledge Bank" ], "summary": "Archive a knowledge article", "description": "Supply the latest revision to prevent lost updates. Publishing requires an active draft with content. Archiving retains content; returning to draft removes it from published views.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "article": { "$ref": "#/components/schemas/KbArticle" } }, "required": [ "ok", "article" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 1 } }, "required": [ "revision" ] } } } }, "x-required-scopes": [ "kb:delete" ], "operationId": "post_kb_articles_id_archive" } }, "/kb/articles/{id}/draft": { "post": { "tags": [ "Knowledge Bank" ], "summary": "Return a knowledge article to draft", "description": "Supply the latest revision to prevent lost updates. Publishing requires an active draft with content. Archiving retains content; returning to draft removes it from published views.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "article": { "$ref": "#/components/schemas/KbArticle" } }, "required": [ "ok", "article" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 1 } }, "required": [ "revision" ] } } } }, "x-required-scopes": [ "kb:write" ], "operationId": "post_kb_articles_id_draft" } }, "/journeys/capabilities": { "get": { "tags": [ "Journeys" ], "summary": "Read journey capabilities", "description": "Check whether this workspace supports enhanced micro journey contracts.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "enhanced": { "type": "boolean" } }, "required": [ "ok", "enhanced" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "journeys:read" ], "operationId": "get_journeys_capabilities" } }, "/journeys/micro": { "get": { "tags": [ "Journeys" ], "summary": "List micro journeys", "description": "Operates only on the authenticated workspace. The response includes the resulting resource fields.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "journeys": { "type": "array", "items": { "type": "object", "properties": { "pairId": { "type": "string", "format": "uuid" }, "titleEn": { "type": "string" }, "titleAr": { "type": "string" } } } } }, "required": [ "ok", "journeys" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "journeys:read" ], "operationId": "get_journeys_micro" }, "post": { "tags": [ "Journeys" ], "summary": "Create a micro journey", "description": "Create a micro journey and initial named version. Enhanced workspaces require contentContractVersion:2 and a unique requestId. Optional parent links are saved atomically.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" } ], "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "microJourneyId": { "type": "string", "format": "uuid" }, "version": { "$ref": "#/components/schemas/JourneyVersion" }, "parentVersion": { "oneOf": [ { "$ref": "#/components/schemas/JourneyVersion" }, { "type": "null" } ] } }, "required": [ "ok", "microJourneyId", "version", "parentVersion" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "titleEn": { "type": "string" }, "titleAr": { "type": "string" }, "layout": { "type": "string", "enum": [ "flow", "road" ] }, "contentContractVersion": { "type": "integer", "const": 2 }, "requestId": { "type": "string", "format": "uuid" }, "parent": { "type": "object", "properties": { "journeyId": { "type": "string", "format": "uuid" }, "versionId": { "type": "string", "format": "uuid" }, "stageId": { "type": "string" }, "content": { "$ref": "#/components/schemas/JourneyContent" }, "expectedRevision": { "type": "integer" } } } } } } } }, "x-required-scopes": [ "journeys:write" ], "operationId": "post_journeys_micro" } }, "/journeys/micro/{pairId}/versions": { "get": { "tags": [ "Journeys" ], "summary": "Read micro journey versions", "description": "Return the version catalog for a micro journey. Optional parent context resolves its published snapshot.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "pairId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "draft", "published" ] }, "description": "Choose draft or published scope." }, { "in": "query", "name": "parentJourneyId", "schema": { "type": "string", "format": "uuid" }, "description": "Parent journey identifier." }, { "in": "query", "name": "parentVersionId", "schema": { "type": "string", "format": "uuid" }, "description": "Parent version identifier." } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "enhanced": { "type": "boolean" }, "requiresContext": { "type": "boolean" }, "contexts": { "type": "array", "items": { "type": "object", "properties": { "journeyId": { "type": "string", "format": "uuid" }, "versionId": { "type": "string", "format": "uuid" }, "titleEn": { "type": "string" }, "titleAr": { "type": "string" }, "pins": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } }, "context": { "type": [ "object", "null" ] }, "pins": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/JourneyVersion" } } }, "required": [ "ok", "enhanced", "requiresContext", "contexts", "context", "pins", "versions" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "journeys:read" ], "operationId": "get_journeys_micro_pairId_versions" } }, "/journeys/pairs/{pairId}/title": { "patch": { "tags": [ "Journeys" ], "summary": "Rename a micro journey", "description": "Operates only on the authenticated workspace. The response includes the resulting resource fields.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "pairId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "titleEn": { "type": "string" }, "titleAr": { "type": "string" } } } } } }, "x-required-scopes": [ "journeys:write" ], "operationId": "patch_journeys_pairs_pairId_title" } }, "/journeys/pairs/{pairId}": { "delete": { "tags": [ "Journeys" ], "summary": "Delete a micro journey", "description": "Requires unlinking the micro journey from all saved parent versions first.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "pairId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "journeys:delete" ], "operationId": "delete_journeys_pairs_pairId_" } }, "/journeys/{journeyId}": { "get": { "tags": [ "Journeys" ], "summary": "Read a journey", "description": "Return all named versions with complete macro or micro content, including steps, messages, scenarios, choices, connectors and timing. Includes drafts.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "journeyId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "journey": { "$ref": "#/components/schemas/Journey" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/JourneyVersion" } } }, "required": [ "ok", "journey", "versions" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "journeys:read" ], "operationId": "get_journeys_journeyId_" }, "patch": { "tags": [ "Journeys" ], "summary": "Update journey titles", "description": "Updates metadata only. Use version endpoints to save or publish journey content.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "journeyId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title_en": { "type": "string" }, "title_ar": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "required": [ "ok", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 160 }, "titleAr": { "type": "string", "maxLength": 160 } } } } } }, "x-required-scopes": [ "journeys:write" ], "operationId": "patch_journeys_journeyId_" }, "put": { "tags": [ "Journeys" ], "summary": "Replace journey titles", "description": "Updates metadata only. Use version endpoints to save or publish journey content.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "journeyId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title_en": { "type": "string" }, "title_ar": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "required": [ "ok", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 160 }, "titleAr": { "type": "string", "maxLength": 160 } }, "required": [ "title" ] } } } }, "x-required-scopes": [ "journeys:write" ], "operationId": "put_journeys_journeyId_" }, "delete": { "tags": [ "Journeys" ], "summary": "Delete a journey", "description": "Delete a macro journey. Micro journeys must use the pair deletion endpoint; linked micro journeys cannot be deleted.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "journeyId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "journeys:delete" ], "operationId": "delete_journeys_journeyId_" } }, "/journeys/{journeyId}/versions": { "get": { "tags": [ "Journeys" ], "summary": "List journey versions", "description": "Return every named version and its complete content, including drafts.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "journeyId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/JourneyVersion" } } }, "required": [ "ok", "versions" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "journeys:read" ], "operationId": "get_journeys_journeyId_versions" }, "post": { "tags": [ "Journeys" ], "summary": "Save or branch a journey version", "description": "Save a draft or create a branch. Enhanced contracts require contentContractVersion:2, expectedRevision for an existing source, and requestId for creation. Published versions are immutable and edits create a draft.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "journeyId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "version": { "$ref": "#/components/schemas/JourneyVersion" } }, "required": [ "ok", "version" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyVersionWrite" } } } }, "x-required-scopes": [ "journeys:write" ], "operationId": "post_journeys_journeyId_versions" } }, "/journeys/{journeyId}/versions/{versionId}": { "get": { "tags": [ "Journeys" ], "summary": "Read a journey version", "description": "The version must belong to the specified journey and authenticated workspace.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "journeyId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "versionId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "version": { "$ref": "#/components/schemas/JourneyVersion" } }, "required": [ "ok", "version" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "journeys:read" ], "operationId": "get_journeys_journeyId_versions_versionId_" } }, "/journeys/{journeyId}/versions/{versionId}/history": { "get": { "tags": [ "Journeys" ], "summary": "Read journey revision history", "description": "Operates only on the authenticated workspace. The response includes the resulting resource fields.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "journeyId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "versionId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "history": { "type": "array", "items": { "type": "object", "properties": { "revision": { "type": "integer" }, "label": { "type": "string" }, "actor": { "type": "string" }, "action": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } }, "required": [ "ok", "history" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "journeys:read" ], "operationId": "get_journeys_journeyId_versions_versionId_history" } }, "/journeys/{journeyId}/versions/{versionId}/restore": { "post": { "tags": [ "Journeys" ], "summary": "Restore a journey revision", "description": "Operates only on the authenticated workspace. The response includes the resulting resource fields.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "journeyId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "versionId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "version": { "$ref": "#/components/schemas/JourneyVersion" } }, "required": [ "ok", "version" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "restoreRevision": { "type": "integer" }, "expectedRevision": { "type": "integer" }, "contentContractVersion": { "type": "integer", "const": 2 }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "restoreRevision", "expectedRevision", "contentContractVersion", "requestId" ] } } } }, "x-required-scopes": [ "journeys:write" ], "operationId": "post_journeys_journeyId_versions_versionId_restore" } }, "/journeys/{journeyId}/versions/{versionId}/publish": { "post": { "tags": [ "Journeys" ], "summary": "Publish a journey version", "description": "Publish a macro version and pin selected micro versions. Enhanced workspaces require matching revisions and selections for every linked micro journey.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "journeyId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "versionId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "version": { "$ref": "#/components/schemas/JourneyVersion" } }, "required": [ "ok", "version" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyPublish" } } } }, "x-required-scopes": [ "journeys:publish" ], "operationId": "post_journeys_journeyId_versions_versionId_publish" } }, "/journeys/versions/{versionId}": { "delete": { "tags": [ "Journeys" ], "summary": "Delete a journey draft", "description": "Published snapshots, drafts with dependent branches and the last version cannot be deleted.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "versionId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "journeys:delete" ], "operationId": "delete_journeys_versions_versionId_" } }, "/surveys/{id}/versions": { "post": { "tags": [ "Surveys" ], "summary": "Branch a survey version", "description": "Create a draft from the currently published version. Returns copied questions with newly assigned IDs and remapped routing and filtering references.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "version": { "$ref": "#/components/schemas/SurveyVersion" } }, "required": [ "ok", "version" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "surveys:write" ], "operationId": "post_surveys_id_versions" } }, "/surveys/{id}/versions/{versionId}/questions": { "put": { "tags": [ "Surveys" ], "summary": "Save survey questions and logic", "description": "Replace all questions in a draft. Validates conditions against each question type and remaps routing/filter references. Returns the saved version and newly assigned question IDs; use those IDs for later operations.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "versionId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "version": { "$ref": "#/components/schemas/SurveyVersion" } }, "required": [ "ok", "version" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "questions": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyQuestion" } } }, "required": [ "questions" ], "example": { "questions": [ { "id": "question-1", "type": "yesno", "orderIndex": 0, "promptEn": "Was this helpful?", "required": true, "options": {}, "routes": [] } ] } } } } }, "x-required-scopes": [ "surveys:write" ], "operationId": "put_surveys_id_versions_versionId_questions" } }, "/surveys/{id}/versions/{versionId}/publish": { "post": { "tags": [ "Surveys" ], "summary": "Publish a survey version", "description": "Publish a validated nonempty draft. Archives the previous published version and revokes its live links. Requires surveys:publish.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "versionId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "version": { "$ref": "#/components/schemas/SurveyVersion" } }, "required": [ "ok", "version" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "surveys:publish" ], "operationId": "post_surveys_id_versions_versionId_publish" } }, "/surveys/{id}/versions/{versionId}/test-link": { "post": { "tags": [ "Surveys" ], "summary": "Create a test survey link", "description": "Returns a respondent token once. Replaces the previous active link of this kind. Test links support drafts and published versions; live links require publication. Treat the token as a secret.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "versionId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "token": { "type": "string" }, "kind": { "type": "string", "enum": [ "test" ] }, "versionId": { "type": "string", "format": "uuid" }, "scope": { "type": "object", "properties": { "space": { "type": "string" }, "generation": { "type": "integer" } } } }, "required": [ "ok", "token", "kind", "versionId", "scope" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "surveys:links:write" ], "operationId": "post_surveys_id_versions_versionId_test_link" } }, "/surveys/{id}/versions/{versionId}/live-link": { "post": { "tags": [ "Surveys" ], "summary": "Create a live survey link", "description": "Returns a respondent token once. Replaces the previous active link of this kind. Test links support drafts and published versions; live links require publication. Treat the token as a secret.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "versionId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "token": { "type": "string" }, "kind": { "type": "string", "enum": [ "live" ] }, "versionId": { "type": "string", "format": "uuid" }, "scope": { "type": "object", "properties": { "space": { "type": "string" }, "generation": { "type": "integer" } } } }, "required": [ "ok", "token", "kind", "versionId", "scope" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "surveys:links:write" ], "operationId": "post_surveys_id_versions_versionId_live_link" } }, "/surveys/{id}/designs": { "post": { "tags": [ "Surveys" ], "summary": "Create a survey design", "description": "Manage a design within the survey team. Designs may be shared by surveys in the same team.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "design": { "$ref": "#/components/schemas/SurveyDesign" } }, "required": [ "ok", "design" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "config": { "type": "object", "additionalProperties": true } } } } } }, "x-required-scopes": [ "surveys:write" ], "operationId": "post_surveys_id_designs" } }, "/surveys/{id}/designs/{designId}": { "patch": { "tags": [ "Surveys" ], "summary": "Update a survey design", "description": "Manage a design within the survey team. Designs may be shared by surveys in the same team.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "designId", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "design": { "$ref": "#/components/schemas/SurveyDesign" } }, "required": [ "ok", "design" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "config": { "type": "object", "additionalProperties": true } } } } } }, "x-required-scopes": [ "surveys:write" ], "operationId": "patch_surveys_id_designs_designId_" } }, "/surveys/{id}/responses": { "post": { "tags": [ "Surveys" ], "summary": "Submit survey answers", "description": "Submit answers to a published version. Required answers, types, routing and filtered choices are validated; skipped or foreign questions are rejected. Retries are not deduplicated.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "responseId": { "type": "string", "format": "uuid" } }, "required": [ "ok", "responseId" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid" }, "respondentRef": { "type": "string", "maxLength": 200 }, "answers": { "type": "array", "items": { "type": "object", "properties": { "questionId": { "type": "string", "format": "uuid" }, "value": {} }, "required": [ "questionId", "value" ] }, "maxItems": 200, "minItems": 1 } }, "required": [ "versionId", "answers" ] } } } }, "x-required-scopes": [ "surveys:responses:write" ], "operationId": "post_surveys_id_responses" } }, "/surveys/{id}/results": { "get": { "tags": [ "Surveys" ], "summary": "Read survey results", "description": "Return aggregate results by question. Requires the separate surveys:results:read scope.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "versionId", "schema": { "type": "string", "format": "uuid" }, "description": "Optionally restrict results to one survey version." } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "responseCount": { "type": "integer" }, "summary": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyResult" } } }, "required": [ "ok", "responseCount", "summary" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "surveys:results:read" ], "operationId": "get_surveys_id_results" } }, "/surveys/{id}/analytics": { "get": { "tags": [ "Surveys" ], "summary": "Read survey response analytics", "description": "Return answer-level response data without respondent identity fields. Answer text can contain personal information; requires surveys:results:read.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "in": "query", "name": "versionId", "schema": { "type": "string", "format": "uuid" }, "description": "Optionally restrict results to one survey version." }, { "in": "query", "name": "dateFrom", "schema": { "type": "string", "format": "date" }, "description": "First included date (YYYY-MM-DD)." }, { "in": "query", "name": "dateTo", "schema": { "type": "string", "format": "date" }, "description": "Last included date (YYYY-MM-DD)." } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "responses": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyResponse" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "ok", "responses", "pagination" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "surveys:results:read" ], "operationId": "get_surveys_id_analytics" } }, "/surveys/{id}/dashboard": { "get": { "tags": [ "Surveys" ], "summary": "Read survey dashboard", "description": "Read or save dashboard layout configuration. This endpoint does not return survey answers.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "dashboard": { "type": "object", "properties": { "widgets": { "type": "array", "items": { "type": "object", "properties": {} } }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "required": [ "ok", "dashboard" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "surveys:read" ], "operationId": "get_surveys_id_dashboard" }, "put": { "tags": [ "Surveys" ], "summary": "Save survey dashboard", "description": "Read or save dashboard layout configuration. This endpoint does not return survey answers.", "parameters": [ { "$ref": "#/components/parameters/workspaceHost" }, { "in": "path", "name": "id", "required": true, "description": "Record identifier in this workspace.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "dashboard": { "type": "object", "properties": { "widgets": { "type": "array", "items": { "type": "object", "properties": {} } }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "required": [ "ok", "dashboard" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired, revoked or wrong-workspace key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required key permission missing, module unavailable, or workspace suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record, workspace or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version changed or the resource is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream or unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dashboard": { "type": "object", "properties": { "widgets": { "type": "array", "items": { "type": "object", "properties": {} } } } } }, "required": [ "dashboard" ] } } } }, "x-required-scopes": [ "surveys:write" ], "operationId": "put_surveys_id_dashboard" } } } }