Dixa Knowledge API

openapi: 3.0.3
info:
  title: Dixa Agents Knowledge API
  version: beta
servers:
- url: https://dev.dixa.io
security:
- ApiKeyAuth: []
tags:
- name: Knowledge
paths:
  /beta/knowledge/collections/{collectionId}:
    get:
      tags:
      - Knowledge
      summary: Get collection
      description: Get a knowledge collection by id
      operationId: getKnowledgeCollectionsCollectionid
      parameters:
      - name: collectionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The knowledge collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetKnowledgeCollectionOutput'
              example:
                data:
                  id: 78dfb531-2e1e-4ffc-bd18-fdad68cd2419
                  title: Test Collection
                  description: This is a test collection
                  internalKbEnabled: true
                  restrictions:
                    isRestricted: true
                    inheritedRestrictions:
                    - fromCollection: 78dfb531-2e1e-4ffc-bd18-fdad68cd2419
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              example:
                message: Decoding failure in request
        '404':
          description: An entity in this request could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              example:
                message: The requested resource could not be found
        '500':
          description: Internal failure during request processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
              example:
                message: There was an internal server error while processing the request
  /beta/knowledge/collections/{collectionId}/catalog:
    get:
      tags:
      - Knowledge
      summary: Get collection catalog
      description: Get collection catalog, including all categories and articles
      operationId: getKnowledgeCollectionsCollectionidCatalog
      parameters:
      - name: collectionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: language
        in: query
        description: Language in which the article translations will be returned. If not provided, the default language will be used.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: The knowledge collection catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetKnowledgeCollectionCatalogOutput'
              example:
                data:
                  categories:
                  - id: 123e4567-e89b-12d3-a456-426614174000
                    title:
                      languageId: en
                      title: Getting Started
                    categories:
                    - id: 123e4567-e89b-12d3-a456-426614174000
                      title:
                        languageId: en
                        title: Getting Started
                      categories: []
                      articles:
                      - id: 5f2640d8-631c-4472-8d48-3de0cfd21cd0
                        title:
                          languageId: en
                          title: Getting Started
                    articles:
                    - id: 5f2640d8-631c-4472-8d48-3de0cfd21cd0
                      title:
                        languageId: en
                        title: Getting Started
                  articles:
                  - id: 5f2640d8-631c-4472-8d48-3de0cfd21cd0
                    title:
                      languageId: en
                      title: Getting Started
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              example:
                message: Decoding failure in request
        '404':
          description: An entity in this request could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              example:
                message: The requested resource could not be found
        '500':
          description: Internal failure during request processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
              example:
                message: There was an internal server error while processing the request
  /beta/knowledge/categories/{categoryId}:
    get:
      tags:
      - Knowledge
      summary: Get category
      description: Get a knowledge category by id
      operationId: getKnowledgeCategoriesCategoryid
      parameters:
      - name: categoryId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: language
        in: query
        description: Language in which the article translations will be returned. If not provided, the default language will be used.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: The category
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetKnowledgeCategoryOutput'
              example:
                data:
                  id: 123e4567-e89b-12d3-a456-426614174000
                  title:
                    languageId: en
                    title: Getting Started
                  isDefaultLocation: true
                  isLocked: false
                  restrictions:
                    isRestricted: true
                    inheritedRestrictions:
                    - fromCollection: 78dfb531-2e1e-4ffc-bd18-fdad68cd2419
                  parentCategory: 222e4567-e89b-12d3-a456-426614174111
                  parentCollections:
                  - 78dfb531-2e1e-4ffc-bd18-fdad68cd2419
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              example:
                message: Decoding failure in request
        '404':
          description: An entity in this request could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              example:
                message: The requested resource could not be found
        '500':
          description: Internal failure during request processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
              example:
                message: There was an internal server error while processing the request
  /beta/knowledge/categories/{categoryId}/translations:
    get:
      tags:
      - Knowledge
      summary: Get category translations
      description: Get the knowledge category translations
      operationId: getKnowledgeCategoriesCategoryidTranslations
      parameters:
      - name: categoryId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The category translations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetKnowledgeCategoryTranslationsOutput'
              example:
                data:
                  titles:
                  - languageId: en
                    title: Getting Started
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              example:
                message: Decoding failure in request
        '404':
          description: An entity in this request could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              example:
                message: The requested resource could not be found
        '500':
          description: Internal failure during request processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
              example:
                message: There was an internal server error while processing the request
  /beta/knowledge/articles/{articleId}:
    get:
      tags:
      - Knowledge
      summary: Get article
      description: Get a knowledge article by id
      operationId: getKnowledgeArticlesArticleid
      parameters:
      - name: articleId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: language
        in: query
        description: Language in which the article translations will be returned. If not provided, the default language will be used.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: The knowledge article
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetKnowledgeArticleOutput'
              example:
                data:
                  id: 123e4567-e89b-12d3-a456-426614174000
                  isDefaultLocation: true
                  translation:
                    draft:
                      language: en
                      title: Getting Started
                      isIndexedVersion: true
                      contents:
                        html: <p>HTML content</p>
                        plaintext: plaintext content
                      availableAt:
                        helpCenterLinks:
                        - id: 112b5b9c-926a-4338-8963-0dc73d29dec7
                          name: Dixa Help Center
                          url: https://help.dixa.com
                      createdAt: 2021-12-01T12:46:36.581Z[GMT]
                      updatedAt: 2021-12-01T12:46:36.581Z[GMT]
                      createdBy: 123e4567-e89b-12d3-a456-426614174000
                      updatedBy: 123e4567-e89b-12d3-a456-426614174000
                    published:
                      language: en
                      title: Getting Started
                      isIndexedVersion: true
                      contents:
                        html: <p>HTML content</p>
                        plaintext: plaintext content
                      availableAt:
                        helpCenterLinks:
                        - id: 112b5b9c-926a-4338-8963-0dc73d29dec7
                          name: Dixa Help Center
                          url: https://help.dixa.com
                      createdAt: 2021-12-01T12:46:36.581Z[GMT]
                      updatedAt: 2021-12-01T12:46:36.581Z[GMT]
                      createdBy: 123e4567-e89b-12d3-a456-426614174000
                      updatedBy: 123e4567-e89b-12d3-a456-426614174000
                  tags:
                  - f6020a03-5a7a-4d9e-81e6-f1b76a855a5e
                  createdAt: 2021-12-01T12:46:36.581Z[GMT]
                  updatedAt: 2021-12-01T12:46:36.581Z[GMT]
                  indexedAt: 2021-12-01T12:46:36.581Z[GMT]
                  createdBy: 123e4567-e89b-12d3-a456-426614174000
                  updatedBy: 123e4567-e89b-12d3-a456-426614174000
                  ownedBy: 123e4567-e89b-12d3-a456-426614174000
                  indexedBy: 123e4567-e89b-12d3-a456-426614174000
                  restrictions:
                    isRestricted: true
                    inheritedRestrictions:
                    - fromCollection: 78dfb531-2e1e-4ffc-bd18-fdad68cd2419
                  parentCategory: 123e4567-e89b-12d3-a456-426614174000
                  parentCollections:
                  - 78dfb531-2e1e-4ffc-bd18-fdad68cd2419
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              example:
                message: Decoding failure in request
        '404':
          description: An entity in this request could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              example:
                message: The requested resource could not be found
        '500':
          description: Internal failure during request processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
              example:
                message: There was an internal server error while processing the request
    delete:
      tags:
      - Knowledge
      summary: Delete article
      description: Delete a knowledge article
      operationId: deleteKnowledgeArticlesArticleid
      parameters:
      - name: articleId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              example:
                message: Decoding failure in request
        '404':
          description: An entity in this request could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              example:
                message: The requested resource could not be found
        '500':
          description: Internal failure during request processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
              example:
                message: There was an internal server error while processing the request
    patch:
      tags:
      - Knowledge
      summary: Update article
      description: Update a knowledge article
      operationId: patchKnowledgeArticlesArticleid
      parameters:
      - name: articleId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: The knowledge article fields to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateKnowledgeArticleInput'
            example:
              ownedBy: 123e4567-e89b-12d3-a456-426614174000
              tags:
                add:
                - tag-id-1
              preRelease: false
        required: true
      responses:
        '200':
          description: The updated knowledge article
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateKnowledgeArticleOutput'
              example:
                data:
                  id: 123e4567-e89b-12d3-a456-426614174000
                  isDefaultLocation: true
                  translation:
                    draft:
                      language: en
                      title: Getting Started
                      isIndexedVersion: true
                      contents:
                        html: <p>HTML content</p>
                        plaintext: plaintext content
                      availableAt:
                        helpCenterLinks:
                        - id: 112b5b9c-926a-4338-8963-0dc73d29dec7
                          name: Dixa Help Center
                          url: https://help.dixa.com
                      createdAt: 2021-12-01T12:46:36.581Z[GMT]
                      updatedAt: 2021-12-01T12:46:36.581Z[GMT]
                      createdBy: 123e4567-e89b-12d3-a456-426614174000
                      updatedBy: 123e4567-e89b-12d3-a456-426614174000
                    published:
                      language: en
                      title: Getting Started
                      isIndexedVersion: true
                      contents:
                        html: <p>HTML content</p>
                        plaintext: plaintext content
                      availableAt:
                        helpCenterLinks:
                        - id: 112b5b9c-926a-4338-8963-0dc73d29dec7
                          name: Dixa Help Center
                          url: https://help.dixa.com
                      createdAt: 2021-12-01T12:46:36.581Z[GMT]
                      updatedAt: 2021-12-01T12:46:36.581Z[GMT]
                      createdBy: 123e4567-e89b-12d3-a456-426614174000
                      updatedBy: 123e4567-e89b-12d3-a456-426614174000
                  tags:
                  - f6020a03-5a7a-4d9e-81e6-f1b76a855a5e
                  createdAt: 2021-12-01T12:46:36.581Z[GMT]
                  updatedAt: 2021-12-01T12:46:36.581Z[GMT]
                  indexedAt: 2021-12-01T12:46:36.581Z[GMT]
                  createdBy: 123e4567-e89b-12d3-a456-426614174000
                  updatedBy: 123e4567-e89b-12d3-a456-426614174000
                  ownedBy: 123e4567-e89b-12d3-a456-426614174000
                  indexedBy: 123e4567-e89b-12d3-a456-426614174000
                  restrictions:
                    isRestricted: true
                    inheritedRestrictions:
                    - fromCollection: 78dfb531-2e1e-4ffc-bd18-fdad68cd2419
                  parentCategory: 123e4567-e89b-12d3-a456-426614174000
                  parentCollections:
                  - 78dfb531-2e1e-4ffc-bd18-fdad68cd2419
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              example:
                message: Decoding failure in request
        '404':
          description: An entity in this request could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              example:
                message: The requested resource could not be found
        '500':
          description: Internal failure during request processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
              example:
                message: There was an internal server error while processing the request
  /beta/knowledge/articles/{articleId}/translations:
    get:
      tags:
      - Knowledge
      summary: Get article translations
      description: Get a knowledge article translations
      operationId: getKnowledgeArticlesArticleidTranslations
      parameters:
      - name: articleId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The article translations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetKnowledgeArticleTranslationsOutput'
              example:
                data:
                  translations:
                    draft:
                    - language: en
                      title: Getting Started
                      isIndexedVersion: true
                      contents:
                        html: <p>HTML content</p>
                        plaintext: plaintext content
                      availableAt:
                        helpCenterLinks:
                        - id: 112b5b9c-926a-4338-8963-0dc73d29dec7
                          name: Dixa Help Center
                          url: https://help.dixa.com
                      createdAt: 2021-12-01T12:46:36.581Z[GMT]
                      updatedAt: 2021-12-01T12:46:36.581Z[GMT]
                      createdBy: 123e4567-e89b-12d3-a456-426614174000
                      updatedBy: 123e4567-e89b-12d3-a456-426614174000
                    published:
                    - language: en
                      title: Getting Started
                      isIndexedVersion: true
                      contents:
                        html: <p>HTML content</p>
                        plaintext: plaintext content
                      availableAt:
                        helpCenterLinks:
                        - id: 112b5b9c-926a-4338-8963-0dc73d29dec7
                          name: Dixa Help Center
                          url: https://help.dixa.com
                      createdAt: 2021-12-01T12:46:36.581Z[GMT]
                      updatedAt: 2021-12-01T12:46:36.581Z[GMT]
                      createdBy: 123e4567-e89b-12d3-a456-426614174000
                      updatedBy: 123e4567-e89b-12d3-a456-426614174000
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              example:
                message: Decoding failure in request
        '404':
          description: An entity in this request could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              example:
                message: The requested resource could not be found
        '500':
          description: Internal failure during request processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
              example:
                message: There was an internal server error while processing the request
    patch:
      tags:
      - Knowledge
      summary: Update article translations
      description: Update translations for a knowledge article. Supports partial success.
      operationId: patchKnowledgeArticlesArticleidTranslations
      parameters:
      - name: articleId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: The translations to update for the article
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTranslationsInput'
            example:
              translations:
              - languageId: en
                title: My Article
                content: <p>Hello world</p>
        required: true
      responses:
        '200':
          description: The updated translations, with partial errors if any
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateTranslationsOutput'
              example:
                data:
                - language: en
                  title: Getting Started
                  isIndexedVersion: true
                  contents:
                    html: <p>HTML content</p>
                    plaintext: plaintext content
                  availableAt:
                    helpCenterLinks:
                    - id: 112b5b9c-926a-4338-8963-0dc73d29dec7
                      name: Dixa Help Center
                      url: https://help.dixa.com
                  createdAt: 2021-12-01T12:46:36.581Z[GMT]
                  updatedAt: 2021-12-01T12:46:36.581Z[GMT]
                  createdBy: 123e4567-e89b-12d3-a456-426614174000
                  updatedBy: 123e4567-e89b-12d3-a456-426614174000
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              example:
                message: Decoding failure in request
        '404':
          description: An entity in this request could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              example:
                message: The requested resource could not be found
        '500':
          description: Internal failure during request processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
              example:
                message: There was an internal server error while processing the request
  /beta/knowledge/articles:
    post:
      tags:
      - Knowledge
      summary: Create article
      description: Create a knowledge article
      operationId: postKnowledgeArticles
      requestBody:
        description: The knowledge article to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateKnowledgeArticleInput'
            example:
              translations:
              - languageId: en
                title: My Article
                content: <p>Content</p>
              parentId: 123e4567-e89b-12d3-a456-426614174000
              tags:
              - f6020a03-5a7a-4d9e-81e6-f1b76a855a5e
              preRelease: false
        required: true
      responses:
        '200':
          description: The created knowledge article
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateKnowledgeArticleOutput'
              example:
                data:
                  id: 123e4567-e89b-12d3-a456-426614174000
                  isDefaultLocation: true
                  translation:
                    draft:
                      language: en
                      title: Getting Started
                      isIndexedVersion: true
                      contents:
                        html: <p>HTML content</p>
                        plaintext: plaintext content
                      availableAt:
                        helpCenterLinks:
                        - id: 112b5b9c-926a-4338-8963-0dc73d29dec7
                          name: Dixa Help Center
                          url: https://help.dixa.com
                      createdAt: 2021-12-01T12:46:36.581Z[GMT]
                      updatedAt: 2021-12-01T12:46:36.581Z[GMT]
                      createdBy: 123e4567-e89b-12d3-a456-426614174000
                      updatedBy: 123e4567-e89b-12d3-a456-426614174000
                    published:
                      language: en
                      title: Getting Started
                      isIndexedVersion: true
                      contents:
                        html: <p>HTML content</p>
                        plaintext: plaintext content
                      availableAt:
                        helpCenterLinks:
                        - id: 112b5b9c-926a-4338-8963-0dc73d29dec7
                          name: Dixa Help Center
                          url: https://help.dixa.com
                      createdAt: 2021-12-01T12:46:36.581Z[GMT]
                      updatedAt: 2021-12-01T12:46:36.581Z[GMT]
                      createdBy: 123e4567-e89b-12d3-a456-426614174000
                      updatedBy: 123e4567-e89b-12d3-a456-426614174000
                  tags:
                  - f6020a03-5a7a-4d9e-81e6-f1b76a855a5e
                  createdAt: 2021-12-01T12:46:36.581Z[GMT]
                  updatedAt: 2021-12-01T12:46:36.581Z[GMT]
                  indexedAt: 2021-12-01T12:46:36.581Z[GMT]
                  createdBy: 123e4567-e89b-12d3-a456-426614174000
                  updatedBy: 123e4567-e89b-12d3-a456-426614174000
                  ownedBy: 123e4567-e89b-12d3-a456-426614174000
                  indexedBy: 123e4567-e89b-12d3-a456-426614174000
                  restrictions:
                    isRestricted: true
                    inheritedRestrictions:
                    - fromCollection: 78dfb531-2e1e-4ffc-bd18-fdad68cd2419
                  parentCategory: 123e4567-e89b-12d3-a456-426614174000
                  parentCollections:
                  - 78dfb531-2e1e-4ffc-bd18-fdad68cd2419
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              example:
                message: Decoding failure in request
        '404':
          description: An entity in this request could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              example:
                message: The requested resource could not be found
        '500':
          description: Internal failure during request processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
              example:
                message: There was an internal server error while processing the request
  /beta/knowledge/articles/{articleId}/translations/{languageId}/publish:
    post:
      tags:
      - Knowledge
      summary: Publish translation
      description: Publish a specific translation for search
      operationId: postKnowledgeArticlesArticleidTranslationsLanguageidPublish
      parameters:
      - name: articleId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: languageId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              example:
                message: Decoding failure in request
        '404':
          description: An entity in this request could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              example:
                message: The requested resource could not be found
        '500':
          description: Internal failure during request processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
              example:
                message: There was an internal server error while processing the request
  /beta/knowledge/articles/{articleId}/translations/{languageId}/unpublish:
    post:
      tags:
      - Knowledge
      summary: Unpublish translation
      description: Mark a specific translation as unpublished
      operationId: postKnowledgeArticlesArticleidTranslationsLanguageidUnpublish
      parameters:
      - name: articleId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: languageId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              example:
                message: Decoding failure in request
        '404':
          description: An entity in this request could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              example:
                message: The requested resource could not be found
        '500':
          description: Internal failure during request processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
              example:
                message: There was an internal server error while processing the request
  /beta/knowledge/articles/{articleId}/translations/{languageId}:
    delete:
      tags:
      - Knowledge
      summary: Delete article translation
      description: Delete all versions of a knowledge article translation
      operationId: deleteKnowledgeArticlesArticleidTranslationsLanguageid
      parameters:
      - name: articleId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: languageId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: ''
        '400':
          des

# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dixa/refs/heads/main/openapi/dixa-knowledge-api-openapi.yml