# Site articles

This endpoint lets you manage your knowledge base articles. Public articles can be retrieved without authentication.

# The article object

  • id integer

    The system-generated ID of the article.

  • site_id integer

    The system-generated ID of the site.

  • title string

    The title of the article in the requested locale.

  • summary string

    A short summary of the article in the requested locale.

  • content string

    The content of the article in the requested locale.

  • source_locale string

    The source locale of the article, which determines the main translation other translations should be based on.

  • locale string

    The locale of the current translation being served.

  • sort_order decimal

    The position of the article in a sorted list. This value can be either incremental (automatically assigned), or custom.

  • url string

    The URL of the article.

  • views integer

    The article's view count.

  • collection_id integer

    The system-generated ID of the collection.

  • collection object expandable

    The collection object attached to the article.

  • categories array

    The list of categories attached to the article.

    Show child attributes
    • categories.* object expandable

      The category object attached to the article.

  • translations array

    The list of translations of the article.

    Show child attributes
    • translations.[en, es, ...] object

      The translation object.

      Show child attributes
      • [en, es, ...].id integer

        The system-generated ID of the translation.

      • [en, es, ...].locale string

        The locale of the translation.

      • [en, es, ...].title string

        The title of the article.

      • [en, es, ...].summary string

        A short summary of the article.

      • [en, es, ...].content string

        The content of the article.

  • reactions object

    The reactions count.

    Show child attributes
    • reactions.total integer

      The total count of reactions.

    • reactions.positive integer

      The total count of positive reactions.

    • reactions.negative integer

      The total count of negative reactions.

  • feedback object

    The feedback count.

    Show child attributes
    • feedback.total integer

      The total count of feedback.

  • created_at string

    The timestamp when the article was created.

  • updated_at string

    The timestamp when the article was last updated.

# The article object

{
  "id": 3,
  "site_id": 1,
  "title": "Sample article",
  "summary": "This is a summary of the article.",
  "content": "<p>Content...</p>",
  "source_locale": "en",
  "locale": "en",
  "sort_order": 1.5,
  "url": "https://docs.example.com/en/article/123/sample-article",
  "views": 0,
  "collection_id": 1,
  "collection": {...},
  "categories": [],
  "translations": {
    "en": {
      "id": 5,
      "locale": "en",
      "title": "Sample article",
      "summary": "This is a summary of the article.",
      "content": "<p>Content...</p>"
    },
    "es-PR": {
      "id": 6,
      "locale": "es-PR",
      "title": "Requisitos del Servidor",
      "summary": "Resumen del artículo.",
      "content": "<p>Contenido...</p>"
    }
  },
  "reactions": {
    "total": 0,
    "positive": 0,
    "negative": 0
  },
  "feedback": {
    "total": 0,
  },
  "created_at": "2019-04-24T01:27:22+00:00",
  "updated_at": "2019-04-24T01:27:22+00:00"
}

# Create an article

  • source_locale string required

    The source locale of the article, which determines the main translation other translations should be based on.

  • collection_id integer required

    The system-generated ID of the collection.

  • sort_order decimal optional

    The position of the article in a sorted list. New articles will be placed in the end of the list when this attribute is empty.

  • categories array optional

    The list of categories attached to the article.

    Show child attributes
    • categories.* integer

      The ID of the article.

  • translations array

    The list of translations of the article.

    Show child attributes
    • translations.[en, es, ...] object

      The translation object.

      Show child attributes
      • [en, es, ...].title string required for source locale

        The title of the article.

      • [en, es, ...].summary string optional

        A short summary of the article.

      • [en, es, ...].content string required for source locale

        The content of the article.

# Sample request

curl https://www.yourdomain.com/api/v1/site/1/articles \
  --request POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d source_locale="en" \
  -d collection_id=1 \
  -d sort_order=3 \
  -d categories[0]=1 \
  -d categories[1]=2 \
  -d translations[en][title]="Sample article" \
  -d translations[en][summary]="This is a summary of the article" \
  -d translations[en][content]="<p>Content...</p>" \
  -d translations[es-PR][title]="Ejemplo de artículo" \
  -d translations[es-PR][summary]="Resumen del artículo." \
  -d translations[es-PR][content]="<p>Contenido...</p>"

# Sample successful response

{
  "data": {
    "id": 3,
    "site_id": 1,
    "title": "Sample article",
    "summary": "This is a summary of the article",
    "content": "<p>Content...</p>",
    "source_locale": "en",
    "locale": "en",
    "sort_order": 1.5,
    "url": "https://docs.example.com/en/article/123/sample-article",
    "views": 0,
    "collection_id": 1,
    "collection": {...},
    "categories": [...],
    "translations": {
      "en": {
        "id": 5,
        "locale": "en",
        "title": "Sample article",
        "summary": "This is a summary of the article",
        "content": "<p>Content...</p>"
      },
      "es-PR": {
        "id": 6,
        "locale": "es-PR",
        "title": "Ejemplo de artículo",
        "summary": "Resumen del artículo",
        "content": "<p>Contenido...</p>"
      }
    },
    "reactions": {
      "total": 0,
      "positive": 0,
      "negative": 0
    },
    "feedback": {
      "total": 0,
    },
    "created_at": "2019-04-24T01:27:22+00:00",
    "updated_at": "2019-04-24T01:27:22+00:00"
  }
}

# Retrieve an article

# Sample request

curl https://www.yourdomain.com/api/v1/sites/1/articles/1 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \ 
  -G

# Sample successful response

{
  "data": {
    "id": 3,
    "site_id": 1,
    "title": "Sample article",
    "summary": "This is a summary of the article",
    "content": "<p>Content...</p>",
    "source_locale": "en",
    "locale": "en",
    "sort_order": 1.5,
    "url": "https://docs.example.com/en/article/123/sample-article",
    "views": 0,
    "collection_id": 1,
    "collection": {...},
    "categories": [...],
    "translations": {
      "en": {
        "id": 5,
        "locale": "en",
        "title": "Sample article",
        "summary": "This is a summary of the article",
        "content": "<p>Content...</p>"
      },
      "es-PR": {
        "id": 6,
        "locale": "es-PR",
        "title": "Ejemplo de artículo",
        "summary": "Resumen del artículo",
        "content": "<p>Contenido...</p>"
      }
    },
    "reactions": {
      "total": 0,
      "positive": 0,
      "negative": 0
    },
    "feedback": {
      "total": 0,
    },
    "created_at": "2019-04-24T01:27:22+00:00",
    "updated_at": "2019-04-24T01:27:22+00:00"
  }
}

# Update an article

  • source_locale string required

    The source locale of the article, which determines the main translation other translations should be based on.

  • collection_id integer required

    The system-generated ID of the collection.

  • sort_order decimal optional

    The position of the article in a sorted list. New articles will be placed in the end of the list when this attribute is empty.

  • categories array optional

    The list of categories attached to the article.

    Show child attributes
    • categories.* integer

      The ID of the article.

  • translations array

    The list of translations of the article.

    Show child attributes
    • translations.[en, es, ...] object

      The translation object.

      Show child attributes
      • [en, es, ...].title string required for source locale

        The title of the article.

      • [en, es, ...].summary string optional

        A short summary of the article.

      • [en, es, ...].content string required for source locale

        The content of the article.

# Sample request

curl https://www.yourdomain.com/api/v1/sites/1/articles/1 \
  --request PUT \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d source_locale="en" \
  -d collection_id=1 \
  -d sort_order=3 \
  -d categories[0]=1 \
  -d categories[1]=2 \
  -d translations[en][title]="Sample article" \
  -d translations[en][summary]="This is a summary of the article" \
  -d translations[en][content]="<p>Content...</p>" \
  -d translations[es-PR][title]="Ejemplo de artículo" \
  -d translations[es-PR][summary]="Resumen del artículo." \
  -d translations[es-PR][content]="<p>Contenido...</p>"

# Sample successful response

{
  "data": {
    "id": 3,
    "site_id": 1,
    "title": "Sample article",
    "summary": "This is a summary of the article",
    "content": "<p>Content...</p>",
    "source_locale": "en",
    "locale": "en",
    "sort_order": 1.5,
    "url": "https://docs.example.com/en/article/123/sample-article",
    "views": 0,
    "collection_id": 1,
    "collection": {...},
    "categories": [...],
    "translations": {
      "en": {
        "id": 5,
        "locale": "en",
        "title": "Sample article",
        "summary": "This is a summary of the article",
        "content": "<p>Content...</p>"
      },
      "es-PR": {
        "id": 6,
        "locale": "es-PR",
        "title": "Ejemplo de artículo",
        "summary": "Resumen del artículo",
        "content": "<p>Contenido...</p>"
      }
    },
    "reactions": {
      "total": 0,
      "positive": 0,
      "negative": 0
    },
    "feedback": {
      "total": 0,
    },
    "created_at": "2019-04-24T01:27:22+00:00",
    "updated_at": "2019-04-24T01:27:22+00:00"
  }
}

# Delete an article

curl https://www.yourdomain.com/api/v1/sites/1/articles/1 \
  --request DELETE
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>"

If successful, the above request will return an empty response with 204 HTTP status code.

# List all articles

# Parameters

  • query string optional

    A filter on the list based on keywords.

  • collection_id integer optional

    A filter on the list based on the article's collection_id field.

  • ids array of integers optional

    A filter on the list based on the article's id field.

  • sort_by enum: sort_order optional

    A sort on the list based on the provided article's field.

  • sort_type enum: desc, asc optional

    The type of the sort to perform.

# Sample request

curl https://www.yourdomain.com/api/v1/sites/1/articles \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -G

# Sample successful response

{
  "data": [
    {
      "id": 3,
      "site_id": 1,
      "title": "Sample article",
      "summary": "This is a summary of the article",
      "content": "<p>Content...</p>",
      "source_locale": "en",
      "locale": "en",
      "sort_order": 1.5,
      "url": "https://docs.example.com/en/article/123/sample-article",
      "views": 0,
      "collection_id": 1,
      "collection": {...},
      "categories": [...],
      "translations": {
        "en": {
          "id": 5,
          "locale": "en",
          "title": "Sample article",
          "summary": "This is a summary of the article",
          "content": "<p>Content...</p>"
        },
        "es-PR": {
          "id": 6,
          "locale": "es-PR",
          "title": "Ejemplo de artículo",
          "summary": "Resumen del artículo",
          "content": "<p>Contenido...</p>"
        }
      },
      "reactions": {
        "total": 0,
        "positive": 0,
        "negative": 0
      },
      "feedback": {
        "total": 0,
      },
      "created_at": "2019-04-24T01:27:22+00:00",
      "updated_at": "2019-04-24T01:27:22+00:00"
    },
    {...}
  ]
}