Hello, how can we help you?

  1. Home page
  2. Return to search
  3. 05. Integrations
  4. API's
Movidesk API - Knowledge Base Articles Query
14 min
Created by Marileia Barboza dos Santos on 4/20/2023 10:47 AM
Updated by Maria Malheiros on 10/31/2024 11:53 AM

The Movidesk API offers features that allow you to consult information from the Knowledge Base directly via HTTP requests. With this API, it is possible to integrate the search for articles into your system, automating queries and retrieving specific content.

API Administration

To use the API, a Authentication Token, which must be sent in all requests via the header. This token can be obtained from the Movidesk control panel by following these steps:

  1. Go to the Configuration menu.

  2. Vá até Account > Parameters.

  3. In the Environment tab, scroll to the bottom of the page to find the Token. Copy the key provided. 

This token should be treated as a security key, preventing unauthorized sharing.

With the authentication key in hand, choose a tool to test the API. In Movidesk, we recommend Postman, a widely used software to test and manipulate APIs with ease.

To test, follow the instructions:

  1. Open the Postman and create a new request.

  2. In the URL field, enter the API endpoint you want to consult. For example, to list a single article, the endpoint would be https://api.movidesk.com/public/v1/article/:id

  3. In the Authorization tab, enter the authentication token in the header or as a parameter in the query, as required.

  4. Paste the key you copied earlier into the Token field.

  5. Choose the appropriate HTTP method (e.g. GET to query data).

  6. Click on Send to send the request à API. 

Limits and safety

The API has a limit of 10 requests per minute to ensure stable performance. If your scenario requires a higher volume of requests, please contact our support team for a feasibility analysis.
Integration with API: List a single article

The consultation of a specific article can be done through your ID. 

The endpoint for this operation is:

URL: /public/v1/article/:id
Método: GET 

Property
Type
Description
id
int
Article identifier

Example of request in Postman:

GET: https://api.movidesk.com/public/v1/article/12345/kb
Authorization: YOUR_TOKEN

This request will return the article with the ID provided, including its HTML content and other information such as attachments and categories.

Example Answer

The success response (HTTP Status 200) will have the following format:
{
	"id": 12345,
 "articleStatus": 1,
 "contentHtml":
"Article content</p>",
 "categories": ["Support", "Documentation"],
 "createdDate": "2023-01-01T12:00:00Z",
 "updatedDate":"2023-01-10T15:00:00Z"
}
    .
  • If the token is not entered correctly, the API will return an error HTTP Status 401.
  • If the ID is not found, the return will be HTTP Status 404.
  • If the Id is found, an HTTP Status 200 and a Content-type in JSON format will be returned with the layouts:
article

Property Type Size Description
id int 64 Article identifier.
articleStatus int 1

Status of the Article:

1 - Published;

2 - Suspended.
attachments array   List of attachments.
categories array   List of categories.
contentHtml string max Article content in HTML format.
contentText string max Article content without formatting.
createdDate datetime   Article creation date.
updatedDate datetime  

Article update date.

menu object   Menu the article is in.
relateds array   List of related articles.
revisionId int 64 Id of the published article review.
services array   List of services linked to the article.
slug string 256 List of services linked to the article.
summary string max Summary of the article
tags array   List of article tags
title string 512 Article title.
readingTime time   Approximate time to read the article.
article.attachments[n] 

Property Type Size Description
id int 64 File identifier.
name string 255

File name.
hash string 32  File identification hash.

article.categories[n]

Property Type Size Description
id int 64 Category identifier.
name string 128

Category name.

article.menu 

Property Type Size Description
id int 64 Menu identifier.
name string 128

Name of the menu.

article.relateds[n]

Property Type Size Description
id int 64 Identifier of the related article.
title string 512

Title of the related article.
path string max URL of the related article.

article.services[n]

Property Type Size Description
id int 64 Service identifier.
name string 128

Name of the service.

Example
 
https://api.movidesk.com/public/v1/article/1040
{
    "id": 19040,
    "articleStatus": 1,
    "attachments": [
        {
            "id": 48,
            "name": "pinboard.png",
            "hash": "358F297CE2F84F08C7B85C9EF36AFCB7"
        }
    ],
    "categories": [
        {
            "id": 6622,
            "name": "Configurações 2"
        }
    ],
    "contentHtml": "<strong>Um novo artigo<br /><br /><br /></strong>Conteudo do artigo",
    "contentText": "Um novo artigo\n\nConteudo do artigo\n",
    "createdDate": "2023-04-19T19:33:06.7051183",
    "menu": {
        "id": 6,
        "name": "Menu principal"
    },
    "updatedDate": "2023-04-19T19:33:06.7416947",
    "relateds": [
        {
            "id": 8768,
            "title": "A chave fornecida não estava presente no dicionario",
            "path": "/kb/article/8768/a-chave-fornecida-nao-estava-presente-no-dicionario-2"
        }
    ],
    "revisionId": 19126,
    "services": [
      {
          "id": 5711,
          "name":"SAC"
      }
    ],
    "slug":"a-new-article",
    "summary": "new article",
    "tags": [
      "file"
    ],
   "title":"Article",
    "readingTime":"00:00:04"
}

Integration with the API: Article search

Searches for published and/or suspended articles in the database from paraParameters passed in the URL.Returns a simplified version of the listing for a single article.

The endpoint for this operation is:

URL:/public/v1/article/

Méall: GET 

Property Type Description
q string Value to be searched in title, summary or description.
title string

Value to be searched only in the title.
updatedDateFrom datetime Initial interval of the last update.
updatedDateTo datetime Last update interval.
createdDateFrom datetime Starting range of creation date.
createdDateTo datetime End of creation date.
status int

Article status:

1 (Published);

4 (Suspended).

By default it shows all published and suspended articles.
tags string Name of the tag to be searched.
category string Name of the category to be searched.
menu string Name of the menu to be searched.
page int Current page of search results. Default value: 0.
pageSize int Quantity of records per page. Default value: 30.

Example of request in the Postman

GET: https://api.movidesk.com/public/v1/article/12345/kb
Authorization: YOUR_TOKEN

Response

  • If the token is not entered in the header, an HTTP Status 401 will be returned.
  • If the request is successful, it returns HTTP Status 200.
  • It always returns a JSON, with the layout pattern below:
Property Type Description
pageSize int Quantity of records per page.
totalSize int

Total records found.
items array

If it finds results, it returns a list with a simplified version of the article layout

.

Otherwise, it returns an empty list

.
updatedDateTo datetime Last update interval.
createdDateFrom datetime Initial range of creation date.
createdDateTo datetime End of creation date interval.

Example

https://api.movidesk.com/public/v1/kb/article?q=artigo&updatedDateFrom=202 3-01-01&updatedDateTo=2023-06-01&createdDateFrom=2023-01-01&createdD ateTo=2023-06-01&status=1&pageSize=10&page=0
{
    "pageSize": 10,
    "totalSize": 2,
    "items": [
        {
            "id": 6341,
            "title": "Um novo artigo",
            "summary": "Resumo do artigo",
            "updatedAt": "2023-03-13T20:00:10.5265472Z",
            "createdAt": "2023-03-13T19:59:23.2773286Z",
            "status": 1,
            "tags": [
                "migração 01"
            ],
         

         
"menu": {
              "id": null,
              "name": null
          }
      },
        {
          "id":
6342,
          "title":"Another article",
          "summary": null,
          "updatedAt":"2023-03-13T20:01:33.4411925Z",
       
  "createdAt":"2023-03-13T20:00:58.8507303Z",
          "status": 1,
          "tags": [],
       

         
  {
                  "id": 2713,
                  "name": "Category"
            }
          ],
       
}, "menu": {
            id: 274,
              "name": "MenuKB"
          }
     
}
    ]
}

API Management

After configuring and testing the API, it's important to follow good management practices:

  1. Monitoring: Track the number of requests made and adjust the volume as necessary.

  2. Security: The Authentication Token must be stored in a secure place to prevent unauthorized access.

  3. Logs and Auditing: Use monitoring tools to check faults and latencies in real time.

Was this article useful?
Recently viewed