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: $ref: ./schemas.yaml#/Idea Journey: $ref: ./schemas.yaml#/Journey Survey: $ref: ./schemas.yaml#/Survey Error: $ref: ./schemas.yaml#/Error IdeaMutation: $ref: ./schemas.yaml#/IdeaMutation JourneyMutation: $ref: ./schemas.yaml#/JourneyMutation SopWriteBody: $ref: ./schemas.yaml#/SopWriteBody Sop: $ref: ./schemas.yaml#/Sop Webhook: $ref: ./schemas.yaml#/Webhook WebhookWrite: $ref: ./schemas.yaml#/WebhookWrite Pagination: $ref: ./schemas.yaml#/Pagination IdeaWrite: $ref: ./schemas.yaml#/IdeaWrite IdeaPublication: $ref: ./schemas.yaml#/IdeaPublication KbLink: $ref: ./schemas.yaml#/KbLink KbBlock: $ref: ./schemas.yaml#/KbBlock KbCategory: $ref: ./schemas.yaml#/KbCategory KbCategoryWrite: $ref: ./schemas.yaml#/KbCategoryWrite KbArticleWrite: $ref: ./schemas.yaml#/KbArticleWrite KbArticle: $ref: ./schemas.yaml#/KbArticle JourneyContent: $ref: ./schemas.yaml#/JourneyContent JourneyVersion: $ref: ./schemas.yaml#/JourneyVersion JourneyVersionWrite: $ref: ./schemas.yaml#/JourneyVersionWrite JourneyPublish: $ref: ./schemas.yaml#/JourneyPublish SurveyCondition: $ref: ./schemas.yaml#/SurveyCondition SurveyVisibility: $ref: ./schemas.yaml#/SurveyVisibility SurveyQuestionOptions: $ref: ./schemas.yaml#/SurveyQuestionOptions SurveyQuestion: $ref: ./schemas.yaml#/SurveyQuestion SurveyVersion: $ref: ./schemas.yaml#/SurveyVersion SurveyDesign: $ref: ./schemas.yaml#/SurveyDesign SurveyResult: $ref: ./schemas.yaml#/SurveyResult SurveyResponse: $ref: ./schemas.yaml#/SurveyResponse SopCategories: $ref: ./schemas.yaml#/SopCategories SopComment: $ref: ./schemas.yaml#/SopComment 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