# Site collections

This endpoint lets you manage your knowledge base collections. Collections can be retrieved without authentication.

# The collection object

  • id integer

    The system-generated ID of the collection.

  • site_id integer

    The system-generated ID of the site.

  • name string

    The name of the collection in the requested locale.

  • summary string

    A short summary of the collection in the requested locale.

  • source_locale string

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

  • categories_count integer

    The number of categories under this collection.

  • articles_count integer

    The number of articles under this collection.

  • translations array

    The list of translations of the collection.

    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 collection.

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

        A short summary of the collection.

  • created_at string

    The timestamp when the collection was created.

  • updated_at string

    The timestamp when the collection was last updated.

# The collection object

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

# Create an collection

  • source_locale string required

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

  • sort_order decimal optional

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

  • translations array

    The list of translations of the collection.

    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 collection.

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

        A short summary of the collection.

# Sample request

curl https://www.yourdomain.com/api/v1/site/1/collections \
  --request POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d source_locale="en" \
  -d sort_order=3 \
  -d translations[en][name]="Sample collection" \
  -d translations[en][summary]="This is a summary of the collection" \
  -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 collection",
    "summary": "This is a summary of the collection",
    "source_locale": "en",
    "locale": "en",
    "sort_order": 1.5,
    "categories_count": 0,
    "articles_count": 0,
    "translations": {
      "en": {
        "id": 5,
        "locale": "en",
        "name": "Sample collection",
        "summary": "This is a summary of the collection",
      },
      "es-PR": {
        "id": 6,
        "locale": "es-PR",
        "name": "Ejemplo de artículo",
        "summary": "Resumen del artículo",
      }
    }
  }
}

# Retrieve an collection

# Sample request

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

# Sample successful response

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

# Update an collection

  • source_locale string required

    The source locale of the collection, 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 collection in a sorted list. New collections will be placed in the end of the list when this attribute is empty.

  • translations array

    The list of translations of the collection.

    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 collection.

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

        A short summary of the collection.

# Sample request

curl https://www.yourdomain.com/api/v1/sites/1/collections/1 \
  --request PUT \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d source_locale="en" \
  -d sort_order=3 \
  -d translations[en][name]="Sample collection" \
  -d translations[en][summary]="This is a summary of the collection" \
  -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 collection",
    "summary": "This is a summary of the collection",
    "source_locale": "en",
    "locale": "en",
    "sort_order": 1.5,
    "categories_count": 0,
    "articles_count": 0,
    "translations": {
      "en": {
        "id": 5,
        "locale": "en",
        "name": "Sample collection",
        "summary": "This is a summary of the collection",
      },
      "es-PR": {
        "id": 6,
        "locale": "es-PR",
        "name": "Ejemplo de artículo",
        "summary": "Resumen del artículo",
      }
    }
  }
}

# Delete an collection

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

# Parameters

  • sort_by enum: sort_order optional

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

# Sample successful response

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