openapi: 3.0.0
info:
  title: 'REST API for phpMyFAQ 4.1'
  description: 'phpMyFAQ includes a REST API and offers APIs for various services like fetching the phpMyFAQ version or doing a search against the phpMyFAQ installation.'
  contact:
    name: 'phpMyFAQ Team'
    email: support@phpmyfaq.de
  license:
    name: 'Mozilla Public Licence 2.0'
    url: 'https://www.mozilla.org/MPL/2.0/'
  version: '3.1'
servers:
  - url: 'https://localhost'
    description: 'Local dockerized server'
paths:
  '/api/v3.1/attachments/{faqId}':
    get:
      tags:
        - 'Public Endpoints'
      description: 'Returns a list of attachments for a given FAQ record ID.'
      operationId: getAttachments
      parameters:
        - name: faqId
          in: path
          description: 'The FAQ record ID.'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'If the FAQ has at least one attached file.'
          headers:
            Accept-Language:
              description: 'The language code for the attachment.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: "\n        [\n            {\n                \"filename\": \"attachment-1.pdf\",\n                \"url\": \"https://www.example.org/index.php?action=attachment&id=1\"\n            },\n            {\n                \"filename\": \"attachment-2.pdf\",\n                \"url\": \"https://www.example.org/index.php?action=attachment&id=2\"\n            }\n        ]"
        '404':
          description: 'If the FAQ has no attachments.'
          headers:
            Accept-Language:
              description: 'The language code for the attachment.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: []
  '/api/v3.1/backup/{type}':
    get:
      tags:
        - 'Endpoints with Authentication'
      operationId: createBackup
      parameters:
        - name: type
          in: path
          description: 'The backup type. Can be "data", "logs" or "content".'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'The current backup as a file or a ZipArchive in case of "content"-type.'
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
          content:
            'application/octet-stream or application/zip':
              schema:
                type: string
        '400':
          description: 'If the backup type is wrong or an internal error occurred'
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
          content:
            application/octet-stream:
              schema:
                type: string
        '401':
          description: 'If the user is not authenticated and/or does not have sufficient permissions.'
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
  /api/v3.1/categories:
    get:
      tags:
        - 'Public Endpoints'
      operationId: getCategories
      responses:
        '200':
          description: 'Returns the the categories for the given language provided by "Accept-Language".'
          headers:
            Accept-Language:
              description: 'The language code for the categories.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: "\n        [\n            {\n                \"id\": 1,\n                \"lang\": \"en\",\n                \"parent_id\": 0,\n                \"name\": \"Test\",\n                \"description\": \"Hello, World! Hello, Tests!\",\n                \"user_id\": 1,\n                \"group_id\": 1,\n                \"active\": 1,\n                \"show_home\": 1,\n                \"image\": \"category-1-en.png\",\n                \"level\": 1\n              }\n        ]"
        '404':
          description: 'If no categories are found for the given language.'
          headers:
            Accept-Language:
              description: 'The language code for the categories.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: []
  /api/v3.1/category:
    post:
      tags:
        - 'Endpoints with Authentication'
      operationId: createCategory
      requestBody:
        description: 'The parent category ID is a required value, the parent category name is optional. If the parent category name is present and the ID can be mapped, the parent category ID from the name will be used. If the parent category name cannot be mapped, a 409 error is thrown'
        required: true
        content:
          application/json:
            schema:
              required:
                - language
                - parent-id
                - parent-category-name
                - category-name
                - description
                - user-id
                - group-id
                - is-active
                - show-on-homepage
              properties:
                language:
                  type: string
                parent-id:
                  type: integer
                parent-category-name:
                  type: string
                category-name:
                  type: string
                description:
                  type: string
                user-id:
                  type: integer
                group-id:
                  type: integer
                is-active:
                  type: boolean
                show-on-homepage:
                  type: boolean
              type: object
            example: "{\n                \"language\": \"en\",\n                \"parent-id\": 1,\n                \"parent-category-name\": \"Test\",\n                \"category-name\": \"Test 2\",\n                \"description\": \"Hello, World! Hello, Tests!\",\n                \"user-id\": 1,\n                \"group-id\": 1,\n                \"is-active\": true,\n                \"show-on-homepage\": true\n            }"
      responses:
        '201':
          description: 'If all posted data is correct.'
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: '{ "stored": true }'
        '400':
          description: "If something didn't worked out."
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: '{ "stored": false, "error": "Cannot add category" }'
        '409':
          description: 'If the parent category name cannot be mapped.'
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: '{ "stored": false, "error": "The given parent category name was not found." }'
        '401':
          description: 'If the user is not authenticated.'
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
  '/api/v3.1/comments/{faqId}':
    get:
      tags:
        - 'Public Endpoints'
      description: 'Returns a list of comments for a given FAQ record ID.'
      operationId: getComments
      parameters:
        - name: faqId
          in: path
          description: 'The FAQ record ID.'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'If the FAQ has at least one comment.'
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: "\n        [\n            {\n                \"id\": 2,\n                \"recordId\": 142,\n                \"categoryId\": null,\n                \"type\": \"faq\",\n                \"username\": \"phpMyFAQ User\",\n                \"email\": \"user@example.org\",\n                \"comment\": \"Foo! Bar?\",\n                \"date\": \"2019-12-24T12:24:57+0100\",\n                \"helped\": null\n            }\n        ]"
        '404':
          description: 'If the FAQ has no comments.'
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: []
  '/api/v3.1/faqs/{categoryId}':
    get:
      tags:
        - 'Public Endpoints'
      description: 'This endpoint returns all the FAQs with a preview of the answer for the given category ID and the language provided by "Accept-Language".'
      operationId: getByCategoryId
      parameters:
        - name: categoryId
          in: path
          description: 'The category ID.'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'If the category returns at least one FAQ.'
          headers:
            Accept-Language:
              description: 'The language code for the FAQ.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: "[\n            {\n                \"record_id\": 1,\n                \"record_lang\": \"en\",\n                \"category_id\": 1,\n                \"record_title\": \"Is there life after death?\",\n                \"record_preview\": \"Maybe!\",\n                \"record_link\": \"/phpmyfaq/phpmyfaq/index.php?action=faq&cat=1&id=1&artlang=en\",\n                \"record_updated\": \"20191010175452\",\n                \"visits\": 3,\n                \"record_created\": \"2018-09-03T21:30:17+02:00\"\n            }\n        ]"
        '404':
          description: 'If the category has no FAQs.'
          headers:
            Accept-Language:
              description: 'The language code for the FAQ.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: []
  '/api/v3.1/faq/{categoryId}/{faqId}':
    get:
      tags:
        - 'Public Endpoints'
      description: 'This endpoint returns the FAQ for the given FAQ ID and the language provided by "Accept-Language".'
      operationId: getFaqById
      parameters:
        - name: categoryId
          in: path
          description: 'The category ID.'
          required: true
          schema:
            type: integer
        - name: faqId
          in: path
          description: 'The FAQ ID.'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'If the FAQ exists.'
          headers:
            Accept-Language:
              description: 'The language code for the FAQ.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: "{\n            \"id\": 1,\n            \"lang\": \"en\",\n            \"solution_id\": 1000,\n            \"revision_id\": 0,\n            \"active\": \"yes\",\n            \"sticky\": 0,\n            \"keywords\": \"\",\n            \"title\": \"Is there life after death?\",\n            \"content\": \"Maybe!\",\n            \"author\": \"phpMyFAQ User\",\n            \"email\": \"user@example.org\",\n            \"comment\": \"y\",\n            \"date\": \"2019-10-10 17:54\",\n            \"dateStart\": \"00000000000000\",\n            \"dateEnd\": \"99991231235959\",\n            \"created\": \"2019-09-03T21:30:17+02:00\"\n        }"
        '404':
          description: 'If there are no FAQs for the given FAQ ID.'
          headers:
            Accept-Language:
              description: 'The language code for the FAQ.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: []
  '/api/v3.1/faqs/tags/{tagId}':
    get:
      tags:
        - 'Public Endpoints'
      description: "This endpoint returns all the FAQs for the given tag ID and the language provided by \n        \"Accept-Language\""
      operationId: getByTagId
      parameters:
        - name: tagId
          in: path
          description: 'The tag ID.'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'If the tag ID returns at least one FAQ.'
          headers:
            Accept-Language:
              description: 'The language code for the FAQ.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: "[\n            {\n                \"record_id\": 1,\n                \"record_lang\": \"en\",\n                \"category_id\": 1,\n                \"record_title\": \"Is there life after death?\",\n                \"record_preview\": \"Maybe!\",\n                \"record_link\": \"/phpmyfaq/phpmyfaq/index.php?action=faq&cat=1&id=1&artlang=en\",\n                \"record_updated\": \"20191010175452\",\n                \"visits\": 3,\n                \"record_created\": \"2018-09-03T21:30:17+02:00\"\n            }\n        ]"
        '404':
          description: 'If the tag ID has no FAQs.'
          headers:
            Accept-Language:
              description: 'The language code for the FAQ.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: []
  /api/v3.1/faqs/popular:
    get:
      tags:
        - 'Public Endpoints'
      description: 'This endpoint returns the popular FAQs for the given language provided by "Accept-Language".'
      operationId: getPopular
      responses:
        '200':
          description: "If there's at least one popular FAQ."
          headers:
            Accept-Language:
              description: 'The language code for the FAQ.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: "[\n            {\n                \"date\": \"2019-07-13T11:28:00+0200\",\n                \"question\": \"How can I survive without phpMyFAQ?\",\n                \"answer\": \"A good question!\",\n                \"visits\": 10,\n                \"url\": \"https://www.example.org/index.php?action=faq&cat=1&id=36&artlang=de\"\n            }\n        ]"
        '404':
          description: "If there's not a single popular FAQ."
          headers:
            Accept-Language:
              description: 'The language code for the FAQ.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: []
  /api/v3.1/faqs/latest:
    get:
      tags:
        - 'Public Endpoints'
      description: 'This endpoint returns the latest FAQs for the given language provided by "Accept-Language".'
      operationId: getLatest
      responses:
        '200':
          description: "If there's at least one latest FAQ."
          headers:
            Accept-Language:
              description: 'The language code for the FAQ.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: "[\n            {\n                \"date\": \"2019-07-13T11:28:00+0200\",\n                \"question\": \"How can I survive without phpMyFAQ?\",\n                \"answer\": \"A good question!\",\n                \"visits\": 10,\n                \"url\": \"https://www.example.org/index.php?action=faq&cat=1&id=36&artlang=de\"\n            }\n        ]"
        '404':
          description: "If there's not one latest FAQ."
          headers:
            Accept-Language:
              description: 'The language code for the FAQ.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: []
  /api/v3.1/faqs/trending:
    get:
      tags:
        - 'Public Endpoints'
      description: 'This endpoint returns the trending FAQs for the given language provided by "Accept-Language".'
      operationId: getTrending
      responses:
        '200':
          description: "If there's at least one trending FAQ."
          headers:
            Accept-Language:
              description: 'The language code for the FAQ.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: "[\n            {\n                \"date\": \"2019-07-13T11:28:00+0200\",\n                \"question\": \"How can I survive without phpMyFAQ?\",\n                \"answer\": \"A good question!\",\n                \"visits\": 10,\n                \"url\": \"https://www.example.org/index.php?action=faq&cat=1&id=36&artlang=de\"\n            }\n        ]"
        '404':
          description: "If there's not a single trending FAQ."
          headers:
            Accept-Language:
              description: 'The language code for the FAQ.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: []
  /api/v3.1/faqs/sticky:
    get:
      tags:
        - 'Public Endpoints'
      description: 'This endpoint returns the sticky FAQs for the given language provided by "Accept-Language".'
      operationId: getSticky
      responses:
        '200':
          description: "If there's at least one sticky FAQ."
          headers:
            Accept-Language:
              description: 'The language code for the FAQ.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: "[\n            {\n                \"question\": \"How can I survive without phpMyFAQ?\",\n                \"url\": \"https://www.example.org/index.php?action=faq&cat=1&id=36&artlang=de\",\n                \"id\": 8,\n                \"order\": 1\n            },\n            {\n                \"question\": \"Is there life after death?\",\n                \"url\": \"https://www.example.org/index.php?action=faq&cat=1&id=1&artlang=en\",\n                \"id\": 10,\n                \"order\": 2\n            }\n        ]"
        '404':
          description: "If there's not one sticky FAQ."
          headers:
            Accept-Language:
              description: 'The language code for the FAQ.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: []
  /api/v3.1/faqs:
    get:
      tags:
        - 'Public Endpoints'
      description: 'This endpoint returns all the FAQs for the given language provided by "Accept-Language".'
      operationId: getAll
      responses:
        '200':
          description: "If there's at least one FAQ."
          headers:
            Accept-Language:
              description: 'The language code for the FAQ.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: "[\n            {\n                \"id\": \"1\",\n                \"lang\": \"en\",\n                \"solution_id\": \"1000\",\n                \"revision_id\": \"0\",\n                \"active\": \"yes\",\n                \"sticky\": \"0\",\n                \"keywords\": \"\",\n                \"title\": \"Is there life after death?\",\n                \"content\": \"Maybe!\",\n                \"author\": \"phpMyFAQ User\",\n                \"email\": \"user@example.org\",\n                \"comment\": \"y\",\n                \"updated\": \"2009-10-10 17:54:00\",\n                \"dateStart\": \"00000000000000\",\n                \"dateEnd\": \"99991231235959\",\n                \"created\": \"2008-09-03T21:30:17+02:00\",\n                \"notes\": \"\"\n            }\n        ]"
        '404':
          description: "If there's not one single FAQ."
          headers:
            Accept-Language:
              description: 'The language code for the FAQ.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: []
  /api/v3.1/faq/create:
    post:
      tags:
        - 'Endpoints with Authentication'
      operationId: createFaq
      requestBody:
        description: 'The category ID is a required value, the category name is optional. If the category name is present and the ID can be mapped, the category ID from the name will be used. If the category name cannot be mapped, a 409 error is thrown.'
        required: true
        content:
          application/json:
            schema:
              required:
                - language
                - category-id
                - category-name
                - question
                - answer
                - keywords
                - author
                - email
                - is-active
                - is-sticky
              properties:
                language:
                  type: string
                category-id:
                  type: integer
                category-name:
                  type: string
                question:
                  type: string
                answer:
                  type: string
                keywords:
                  type: string
                author:
                  type: string
                email:
                  type: string
                is-active:
                  type: boolean
                is-sticky:
                  type: boolean
              type: object
            example: "{\n                \"language\": \"de\",\n                \"category-id\": 1,\n                \"category-name\": \"Queen Songs\",\n                \"question\": \"Is this the world we created?\",\n                \"answer\": \"What did we do it for, is this the world we invaded, against the law, so it seems in the end, is this what we're all living for today\",\n                \"keywords\": \"phpMyFAQ, FAQ, Foo, Bar\",\n                \"author\": \"Freddie Mercury\",\n                \"email\": \"freddie.mercury@example.org\",\n                \"is-active\": \"true\",\n                \"is-sticky\": \"false\"\n            }"
      responses:
        '201':
          description: 'If all posted data is correct.'
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: '{ "stored": true }'
        '400':
          description: "If something didn't worked out."
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: '{ "stored": false, "error": "It is not allowed, that the question title contains a hash." }'
        '409':
          description: 'If the parent category name cannot be mapped.'
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: '{ "stored": false, "error": "The given category name was not found" }'
        '401':
          description: 'If the user is not authenticated.'
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
  /api/v3.1/faq/update:
    put:
      tags:
        - 'Endpoints with Authentication'
      description: 'Used to update a FAQ in one existing category.'
      operationId: updateFaq
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - faq-id
                - language
                - category-id
                - question
                - answer
                - keywords
                - author
                - email
                - is-active
                - is-sticky
              properties:
                faq-id:
                  type: integer
                language:
                  type: string
                category-id:
                  type: integer
                question:
                  type: string
                answer:
                  type: string
                keywords:
                  type: string
                author:
                  type: string
                email:
                  type: string
                is-active:
                  type: boolean
                is-sticky:
                  type: boolean
              type: object
            example: "{\n                \"faq-id\": 1,\n                \"language\": \"de\",\n                \"category-id\": 1,\n                \"question\": \"Is this the world we updated?\",\n                \"answer\": \"What did we do it for, is this the world we invaded, against the law, so it seems in the \" .\n                    \"end, is this what we're all living for today\",\n                \"keywords\": \"phpMyFAQ, FAQ, Foo, Bar\",\n                \"author\": \"Freddie Mercury\",\n                \"email\": \"freddie.mercury@example.org\",\n                \"is-active\": \"true\",\n                \"is-sticky\": \"false\"\n            }"
      responses:
        '200':
          description: 'If all posted data is correct.'
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: '{ "stored": true }'
        '400':
          description: "If something didn't worked out."
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: '{ "stored": false, "error": "It is not allowed, that the question title contains a hash." }'
        '401':
          description: 'If the user is not authenticated.'
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
  /api/v3.1/groups:
    get:
      tags:
        - 'Endpoints with Authentication'
      description: 'Used to fetch all group IDs.'
      operationId: getGroups
      responses:
        '200':
          description: 'Returns a list of group IDs.'
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: "\n        [\n            {\n                \"group-id\": 1\n            },\n            {\n                \"group-id\": 2\n            }\n        ]"
        '401':
          description: 'If the user is not authenticated.'
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
  /api/v3.1/language:
    get:
      tags:
        - 'Public Endpoints'
      operationId: getLanguage
      responses:
        '200':
          description: 'Returns the default language as language code.'
          content:
            application/json:
              schema: {}
              example: '"en"'
  /api/v3.1/login:
    post:
      tags:
        - 'Public Endpoints'
      operationId: login
      requestBody:
        description: 'The username and password for the login.'
        required: true
        content:
          application/json:
            schema:
              required:
                - username
                - password
              properties:
                username:
                  type: string
                password:
                  type: string
              type: object
      responses:
        '200':
          description: 'If "username" and "password" combination are correct.'
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: '{ "loggedin": true }'
        '400':
          description: 'If "username" and "password" combination are wrong.'
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: '{ "loggedin": false, "error": "Wrong username or password." }'
  /api/v3.1/news:
    get:
      tags:
        - 'Public Endpoints'
      operationId: getNews
      responses:
        '200':
          description: 'Returns the news for the given language provided by "Accept-Language".'
          headers:
            Accept-Language:
              description: 'The language code for the open questions.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: "\n        [\n            {\n                \"id\": 1,\n                \"lang\": \"en\",\n                \"date\": \"2019-08-23T20:43:00+0200\",\n                \"header\": \"Hallo, World!\",\n                \"content\": \"Hello, phpMyFAQ!\",\n                \"authorName\": \"phpMyFAQ User\",\n                \"authorEmail\": \"user@example.org\",\n                \"dateStart\": \"0\",\n                \"dateEnd\": \"99991231235959\",\n                \"active\": true,\n                \"allowComments\": true,\n                \"link\": \"\",\n                \"linkTitle\": \"\",\n                \"target\": \"\",\n                \"url\": \"https://www.example.org/?action=news&newsid=1&newslang=de\"\n              }\n        ]"
        '404':
          description: 'If no news are stored.'
          headers:
            Accept-Language:
              description: 'The language code for the open questions.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: []
  /api/v3.1/open-questions:
    get:
      tags:
        - 'Public Endpoints'
      operationId: getOpenQuestions
      responses:
        '200':
          description: 'Returns the open questions for the given language provided by "Accept-Language".'
          headers:
            Accept-Language:
              description: 'The language code for the open questions.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: "\n        [\n            {\n                \"id\": 1,\n                \"lang\": \"en\",\n                \"username\": \"phpMyFAQ User\",\n                \"email\": \"user@example.org\",\n                \"categoryId\": 3,\n                \"question\": \"Foo? Bar? Baz?\",\n                \"created\": \"20190106180429\",\n                \"answerId\": 0,\n                \"isVisible\": \"N\"\n              }\n        ]"
        '404':
          description: 'If no open questions are stored.'
          headers:
            Accept-Language:
              description: 'The language code for the open questions.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: []
  '/api/v3.1/pdf/{categoryId}/{faqId}':
    get:
      tags:
        - 'Public Endpoints'
      description: 'This endpoint returns the URL to the PDF of FAQ for the given FAQ ID and the language provided by "Accept-Language".'
      operationId: getPdfById
      parameters:
        - name: categoryId
          in: path
          description: 'The category ID.'
          required: true
          schema:
            type: integer
        - name: faqId
          in: path
          description: 'The FAQ ID.'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'If the PDF of the FAQ exists.'
          headers:
            Accept-Language:
              description: 'The language code for the FAQ.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: '"https://www.example.org/pdf.php?cat=3&id=142&artlang=de"'
        '404':
          description: "If there's no FAQ and PDF for the given FAQ ID."
          headers:
            Accept-Language:
              description: 'The language code for the FAQ.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: []
  /api/v3.1/question:
    post:
      tags:
        - 'Endpoints with Authentication'
      operationId: createQuestion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - category-id
                - question
                - author
                - email
              properties:
                category-id:
                  type: integer
                question:
                  type: string
                author:
                  type: string
                email:
                  type: string
              type: object
            example: "{\n                \"category-id\": \"1\",\n                \"question\": \"Is this the world we created?\",\n                \"author\": \"Freddie Mercury\",\n                \"email\": \"freddie.mercury@example.org\"\n            }"
      responses:
        '201':
          description: 'Used to add a new question in one existing category.'
          headers:
            Accept-Language:
              description: 'The language code for the question.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: '{ "stored": true }'
        '401':
          description: 'If the user is not authenticated.'
          headers:
            Accept-Language:
              description: 'The language code for the question.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
  /api/v3.1/register:
    post:
      tags:
        - 'Endpoints with Authentication'
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - username
                - fullname
                - email
                - is-visible
              properties:
                username:
                  type: string
                fullname:
                  type: string
                email:
                  type: string
                is-visible:
                  type: boolean
              type: object
            example: "{\n                \"username\": \"ada\",\n                \"fullname\": \"Ada Lovelace\",\n                \"email\": \"ada.lovelace@example.org\",\n                \"is-visible\": false\n            }"
      responses:
        '201':
          description: 'If "username", "fullname", "email", and "is-visible" combination is correct.'
          headers:
            Accept-Language:
              description: 'The language code for the question.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: '{ "registered": true, "success": "User created."}'
        '400':
          description: 'If "username", "fullname", "email", and "is-visible" combination is not correct.'
          headers:
            Accept-Language:
              description: 'The language code for the question.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: '{ "registered": false, "error": "Error message"}'
        '409':
          description: 'If the domain of the email address is not allowed.'
          headers:
            Accept-Language:
              description: 'The language code for the question.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: '{ "registered": false, "error": "The domain is not allowed."}'
        '401':
          description: 'If the user is not authenticated.'
          headers:
            Accept-Language:
              description: 'The language code for the question.'
              schema:
                type: string
            x-pmf-token:
              description: 'phpMyFAQ client API Token, generated in admin backend'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: '{ "registered": false }'
  /api/v3.1/search:
    get:
      tags:
        - 'Public Endpoints'
      operationId: getSearch
      parameters:
        - name: q
          in: query
          description: 'The search term'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Returns the results for the query string search term.'
          content:
            application/json:
              schema: {}
              example: "\n        [\n            {\n                \"id\": \"1\",\n                \"lang\": \"en\",\n                \"category_id\": \"15\",\n                \"question\": \"Why are you using phpMyFAQ?\",\n                \"answer\": \"Because it is cool!\",\n                \"link\": \"https://www.example.org/index.php?action=faq&cat=15&id=1&artlang=en\"\n            }\n        ]"
        '404':
          description: 'If the search returns no results'
          content:
            application/json:
              schema: {}
              example: []
  /api/v3.1/searches/popular:
    get:
      tags:
        - 'Public Endpoints'
      operationId: getPopularSearch
      responses:
        '200':
          description: 'Returns the popular search terms for the given language provided by "Accept-Language"'
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: "\n        [\n            {\n                \"id\": 3,\n                \"searchterm\": \"mac\",\n                \"number\": \"18\",\n                \"lang\": \"en\"\n            },\n            {\n                \"id\": 7,\n                \"searchterm\": \"test\",\n                \"number\": 9,\n                \"lang\": \"en\"\n            }\n        ]"
        '404':
          description: 'If the popular search returns no results.'
          headers:
            Accept-Language:
              description: 'The language code for the login.'
              schema:
                type: string
          content:
            application/json:
              schema: {}
              example: []
  /api/v3.1/tags:
    get:
      tags:
        - 'Public Endpoints'
      operationId: getTags
      responses:
        '200':
          description: 'Returns the tags for the given language provided by "Accept-Language".'
          content:
            application/json:
              schema: {}
              example: "[\n            {\"tagId\": 4, \"tagName\": \"phpMyFAQ\", \"tagFrequency\": 3 },\n            {\"tagId\": 1, \"tagName\": \"PHP 8\", \"tagFrequency\": 2 }\n        ]"
        '404':
          description: 'If no tags are stored.'
          content:
            application/json:
              schema: {}
              example: []
  /api/v3.1/title:
    get:
      tags:
        - 'Public Endpoints'
      operationId: getTitle
      responses:
        '200':
          description: 'Returns the title of the phpMyFAQ instance as a string.'
          content:
            application/json:
              schema: {}
              example: 'phpMyFAQ Codename Porus'
  /api/v3.1/version:
    get:
      tags:
        - 'Public Endpoints'
      operationId: getVersion
      responses:
        '200':
          description: 'Returns the phpMyFAQ version number as string.'
          content:
            application/json:
              schema: {}
              example: 4.0.0
tags:
  - name: 'Public Endpoints'
    description: 'Public Endpoints'
  - name: 'Endpoints with Authentication'
    description: 'Endpoints with Authentication'
