# Site collection categories

This endpoint lets you manage your knowledge base categories. Categories can be retrieved without authentication.

# The category object

  • id integer

    The system-generated ID of the category.

  • collection_id integer

    The system-generated ID of the collection.

  • name string

    The name of the category in the requested locale.

  • summary string

    A short summary of the category in the requested locale.

  • source_locale string

    The source locale of the category, 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 category in a sorted list. This value can be either incremental (automatically assigned), or custom.

  • articles_count integer

    The number of articles under this category.

  • collection_id integer

    The system-generated ID of the collection.

  • collection object expandable

    The collection object attached to the article.

  • views_count integer

    The total views of this category.

  • translations array

    The list of translations of the category.

    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, ...].name string

        The name of the category.

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

        A short summary of the category.

  • created_at string

    The timestamp when the category was created.

  • updated_at string

    The timestamp when the category was last updated.

# The category object

{
  "id": 3,
  "name": "Sample category",
  "summary": "This is a summary of the category.",
  "source_locale": "en",
  "locale": "en",
  "sort_order": 1.5,
  "articles_count": 0,
  "collection_id": 1,
  "collection": {...},
  "views_count": 0,
  "translations": {
    "en": {
      "id": 5,
      "locale": "en",
      "name": "Sample category",
      "summary": "This is a summary of the category.",
    },
    "es-PR": {
      "id": 6,
      "locale": "es-PR",
      "name": "Ejemplo de categoría",
      "summary": "Resumen del categoría",
    }
  }
}

# Create an category

  • collection_id integer required

    The system-generated ID of the collection.

  • source_locale string required

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

  • sort_order decimal optional

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

  • translations array

    The list of translations of the category.

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

      The translation object.

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

        The name of the category.

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

        A short summary of the category.

# Sample request

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

# Sample successful response

{
  "data": {
    "id": 3,
    "name": "Sample category",
    "summary": "This is a summary of the category",
    "source_locale": "en",
    "locale": "en",
    "sort_order": 1.5,
    "articles_count": 0,
    "collection_id": 1,
    "collection": {...},
    "views_count": 0,
    "translations": {
      "en": {
        "id": 5,
        "locale": "en",
        "name": "Sample category",
        "summary": "This is a summary of the category",
      },
      "es-PR": {
        "id": 6,
        "locale": "es-PR",
        "name": "Ejemplo de artículo",
        "summary": "Resumen del artículo",
      }
    }
  }
}

# Retrieve an category

# Sample request

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

# Sample successful response

{
  "data": {
    "id": 3,
    "name": "Sample category",
    "summary": "This is a summary of the category",
    "source_locale": "en",
    "locale": "en",
    "sort_order": 1.5,
    "collection_id": 1,
    "collection": {...},
    "views_count": 0,
    "translations": {
      "en": {
        "id": 5,
        "locale": "en",
        "name": "Sample category",
        "summary": "This is a summary of the category",
      },
      "es-PR": {
        "id": 6,
        "locale": "es-PR",
        "name": "Ejemplo de artículo",
        "summary": "Resumen del artículo",
      }
    }
  }
}

# Update an category

  • collection_id integer required

    The system-generated ID of the collection.

  • source_locale string required

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

  • category_id integer required

    The system-generated ID of the category.

  • sort_order decimal optional

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

  • translations array

    The list of translations of the category.

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

      The translation object.

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

        The name of the category.

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

        A short summary of the category.

# Sample request

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

# Sample successful response

{
  "data": {
    "id": 3,
    "site_id": 1,
    "name": "Sample category",
    "summary": "This is a summary of the category",
    "source_locale": "en",
    "locale": "en",
    "sort_order": 1.5,
    "articles_count": 0,
    "collection_id": 1,
    "collection": {...},
    "views_count": 0,
    "translations": {
      "en": {
        "id": 5,
        "locale": "en",
        "name": "Sample category",
        "summary": "This is a summary of the category",
      },
      "es-PR": {
        "id": 6,
        "locale": "es-PR",
        "name": "Ejemplo de artículo",
        "summary": "Resumen del artículo",
      }
    }
  }
}

# Delete an category

curl https://www.yourdomain.com/api/v1/sites/1/categories/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 categories

# Parameters

  • collection_id integer optional

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

  • sort_by enum: sort_order optional

    A sort on the list based on the provided category'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/categories \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -G

# Sample successful response

{
  "data": [
    {
      "id": 3,
      "name": "Sample category",
      "summary": "This is a summary of the category",
      "source_locale": "en",
      "locale": "en",
      "sort_order": 1.5,
      "articles_count": 0,
      "collection_id": 1,
      "collection": {...},
      "views_count": 0,
      "translations": {
        "en": {
          "id": 5,
          "locale": "en",
          "name": "Sample category",
          "summary": "This is a summary of the category",
        },
        "es-PR": {
          "id": 6,
          "locale": "es-PR",
          "name": "Ejemplo de artículo",
          "summary": "Resumen del artículo",
        }
      }
    },
    {...}
  ]
}