Manuals

Manuals are guides and policies orchestrated by the chain management.

Manuals can be restricted by user types and contains chapters (and sub-chapters) that can be restricted further by user types.

Get Manuals

curl "https://example.ziik.io/api/manuals"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
{
  "hits": [
    {
        "id":"927",
        "type":"manuals",
        "title":"EMPLOYEE HANDBOOK",
        "description":"This guide serves as an on-boarding manual.",
        "url":"api/manuals/927"
    }
  ],
  "meta": {
      "pagination": {
          "total": 315,
          "count": 50,
          "per_page": 50,
          "current_page": 2,
          "total_pages": 7,
          "links": []
      }
  }
}

This endpoint retrieves a list of manuals.

HTTP Request

GET https://example.ziik.io/api/manuals

Query Parameters

None

Get Single Manual

curl "https://example.ziik.io/api/manuals/927"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

  {
      "id": 927,
      "content_type": "manuals",
      "permissions": {
          "edit": true,
          "delete": true
      },
      "title": "EMPLOYEE HANDBOOK",
      "description": "This guide serves as an on-boarding manual.",
      "chapters": [{
          "id": 928,
          "content_type": "manuals",
          "permissions": {
              "edit": true,
              "delete": true
          },
          "title": "Welcome!",
          "description": null,
          "chapters": [],
          "paragraphs": [],
          "url": "api/manuals/928"
      }, {
          "id": 929,
          "content_type": "manuals",
          "permissions": {
              "edit": true,
              "delete": true
          },
          "title": "Introduction",
          "description": null,
          "chapters": [],
          "paragraphs": [],
          "url": "api/manuals/929"
      }, {
          "id": 930,
          "content_type": "manuals",
          "permissions": {
              "edit": true,
              "delete": true
          },
          "title": "General Employment Policies and Practicies",
          "description": null,
          "chapters": [{
              "id": 935,
              "content_type": "manuals",
              "permissions": {
                  "edit": true,
                  "delete": true
              },
              "title": "Your Employment Relationship with the Company",
              "description": null,
              "chapters": [],
              "paragraphs": [],
              "url": "api/manuals/935"
          }, {
              "id": 936,
              "content_type": "manuals",
              "permissions": {
                  "edit": true,
                  "delete": true
              },
              "title": "Hours of work",
              "description": null,
              "chapters": [],
              "paragraphs": [],
              "url": "api/manuals/936"
          }, {
              "id": 937,
              "content_type": "manuals",
              "permissions": {
                  "edit": true,
                  "delete": true
              },
              "title": "Dress Code and Public Image",
              "description": null,
              "chapters": [],
              "paragraphs": [],
              "url": "api/manuals/937"
          }, {
              "id": 938,
              "content_type": "manuals",
              "permissions": {
                  "edit": true,
                  "delete": true
              },
              "title": "Communication",
              "description": null,
              "chapters": [],
              "paragraphs": [],
              "url": "api/manuals/938"
          }, {
              "id": 1256,
              "content_type": "manuals",
              "permissions": {
                  "edit": true,
                  "delete": true
              },
              "title": "Something",
              "description": null,
              "chapters": [],
              "paragraphs": [],
              "url": "api/manuals/1256"
          }],
          "paragraphs": [],
          "url": "api/manuals/930"
      }],
      "paragraphs": [],
      "url": "api/manuals/927"
  }

This endpoint returns an entire manual with chapters and subchapters, but without paragraph content

HTTP Request

GET https://example.ziik.io/api/manuals/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the manual

Permissions Required

  • User's user type in manual's user types
  • User's unit in manual's units

Create New Manual

curl -i -X POST "https://example.ziik.io/api/manuals"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 201 Created with a location header for where to find the newly created manual

HTTP/1.0 201 Created
Location: https://example.ziik.io/api/manuals/1234
{
    "message": "Manual created"
}

This endpoint creates a news story.

HTTP Request

POST https://example.ziik.io/api/manuals

Request Parameters

ParameterTypeRequiredDescription
titleStringYesManual title
descriptionStringNoShort description of the manual
statusBooleanNoIf true, manual is published, otherwise it is a draft, only available to users with write permission
userTypesArrayNoUser type IDs of the user types, who can access the manual
unitsArrayNoUnits this manual should be available in

Permissions Required

  • Write permission to manuals

Update Manual

curl -i -X PATCH "https://example.ziik.io/api/manuals/123"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on successful update.

HTTP/1.0 204 No Content

This endpoint updates an existing manual.

HTTP Request

PATCH https://example.ziik.io/api/manuals/ID

Request Parameters

ParameterTypeRequiredDescription
titleStringYesManual title
descriptionStringNoShort description of the manual
statusBooleanNoIf true, manual is published, otherwise it is a draft, only available to users with write permission
userTypesArrayNoUser type IDs of the user types, who can access the manual
unitsArrayNoUnits this manual should be available in

Permissions Required

  • Write permission to manuals
  • Requesting user in the same unit as the manual's creator

Delete Manual

curl -i -X DELETE "https://example.ziik.io/api/manuals/123"
  -H "Authorization: Bearer aaaaaa.bbbbbbb.ccccccc"

The above command returns a 204 No Content header on success:

HTTP/1.0 204 No Content

This endpoint deletes a manual and all its chapters.

HTTP Request

DELETE https://example.ziik.io/api/manuals/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the manual to delete

Permissions Required

  • Write permission to manuals
  • Requesting user in the same unit as the manual's creator

Create Manual Chapter

curl -i -X POST "https://example.ziik.io/api/manuals/123/chapters"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 201 Created with a location header for where to find the newly created chapter

HTTP/1.0 201 Created
Location: https://example.ziik.io/api/manuals/123/chapters/1234
{
    "message": "Chapter created"
}

This endpoint creates a chapter for a manual.

HTTP Request

POST https://example.ziik.io/api/manuals/ID/chapters

Request Parameters

ParameterTypeRequiredDescription
titleStringYesChapter title
parentIntegerNoParent chapter for the created chapter
userTypesArrayNoUser type IDs of the user types, who can access the chapter

Permissions Required

  • Update permission to the manual

Update Chapter

curl -i -X PATCH "https://example.ziik.io/api/chapters/123"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on successful update.

HTTP/1.0 204 No Content

This endpoint updates an existing chapter.

HTTP Request

PATCH https://example.ziik.io/api/chapters/ID

Request Parameters

ParameterTypeRequiredDescription
titleStringYesChapter title
parentIntegerNoParent chapter for the created chapter
userTypesArrayNoUser type IDs of the user types, who can access the chapter

Permissions Required

  • Update permission to the manual

Delete Chapter

curl -i -X DELETE "https://example.ziik.io/api/chapters/123"
  -H "Authorization: Bearer aaaaaa.bbbbbbb.ccccccc"

The above command returns a 204 No Content header on success:

HTTP/1.0 204 No Content

This endpoint deletes a chapter and all its subchapters.

HTTP Request

DELETE https://example.ziik.io/api/chapters/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the chapter to delete

Permissions Required

  • Update permission to the manual

Create Chapter Paragraph

curl -i -X POST "https://example.ziik.io/api/chapters/123/paragraphs"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 201 Created with a location header for where to find the newly created paragraph

HTTP/1.0 201 Created
Location: https://example.ziik.io/api/chapters/123/paragraphs/1234
{
    "message": "Paragraph created"
}

This endpoint creates a paragraph for a chapter.

HTTP Request

POST https://example.ziik.io/api/chapters/ID/paragraphs

Request Parameters

ParameterTypeRequiredDescription
textStringYesParagraph contents
filesArrayNoFile data for files to accompany the paragraph. Must be an array of arrays with the following values
- typeStringYesType of file - can be either 'upload', 'youtube' or 'vimeo'.
- nameStringYesFile name.
- dataStringYesIf type is 'upload' this must be the base64 encoded content of the file. Else it must be the Youtube/Vimeo embed URL.

Move Chapter In Manual Hierarchy

curl -i -X POST "https://example.ziik.io/api/chapters/123/move"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on success

HTTP/1.0 204 No Content

This endpoint moves a chapter to a new location in the manual hierarchy.

HTTP Request

POST https://example.ziik.io/api/chapters/ID/move

Request Parameters

ParameterTypeRequiredDescription
chapterIntegerYesID of the chapter to relate to
positionStringYesWhere to place the chapter relative to the relation chapter. Possible values are "before" (previous sibling), "after" (next sibling), "inside" (child of relation)

Get Chapter

curl "https://example.ziik.io/api/chapters/123"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

  {
            "id": 930,
            "content_type": "manuals",
            "permissions": {
                "edit": true,
                "delete": true
            },
            "title": "General Employment Policies and Practicies",
            "description": null,
            "chapters": [{
                "id": 935,
                "content_type": "manuals",
                "permissions": {
                    "edit": true,
                    "delete": true
                },
                "title": "Your Employment Relationship with the Company",
                "description": null,
                "chapters": [],
                "paragraphs": [
                    {
                      "text": "<HTML TEXT>",
                      "files": [{
                          "id": 643,
                          "name": "filename.jpg",
                          "mime": "image/jpeg",
                          "size": 102380,
                          "type": "image",
                          "source": "https://example.ziik.io/api/file/manuals/filename.jpg",
                          "versions": {
                              "listing": "https://example.ziik.io/api/file/styles/article_listing/private/manuals/filename.jpg",
                              "detail": "https://example.ziik.io/api/file/styles/article_desktop/private/manuals/filename.jpg",
                              "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/manuals/filename.png"
                          }
                      }]
                    }
                ],
                "url": "api/manuals/935"
            }, {
                "id": 936,
                "content_type": "manuals",
                "permissions": {
                    "edit": true,
                    "delete": true
                },
                "title": "Hours of work",
                "description": null,
                "chapters": [],
                "paragraphs": [],
                "url": "api/manuals/936"
            }, {
                "id": 937,
                "content_type": "manuals",
                "permissions": {
                    "edit": true,
                    "delete": true
                },
                "title": "Dress Code and Public Image",
                "description": null,
                "chapters": [],
                "paragraphs": [],
                "url": "api/manuals/937"
            }, {
                "id": 938,
                "content_type": "manuals",
                "permissions": {
                    "edit": true,
                    "delete": true
                },
                "title": "Communication",
                "description": null,
                "chapters": [],
                "paragraphs": [],
                "url": "api/manuals/938"
            }, {
                "id": 1256,
                "content_type": "manuals",
                "permissions": {
                    "edit": true,
                    "delete": true
                },
                "title": "Something",
                "description": null,
                "chapters": [],
                "paragraphs": [],
                "url": "api/manuals/1256"
            }],
            "paragraphs": [
                {
                  "text": "<HTML TEXT>",
                  "files": [{
                      "id": 643,
                      "name": "filename.jpg",
                      "mime": "image/jpeg",
                      "size": 102380,
                      "type": "image",
                      "source": "https://example.ziik.io/api/file/manuals/filename.jpg",
                      "versions": {
                          "listing": "https://example.ziik.io/api/file/styles/article_listing/private/manuals/filename.jpg",
                          "detail": "https://example.ziik.io/api/file/styles/article_desktop/private/manuals/filename.jpg",
                          "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/manuals/filename.png"
                      }
                  }]
                }
            ],
            "url": "api/manuals/930"

This endpoint returns a single chapter with its subchapters and paragraphs

HTTP Request

GET https://example.ziik.io/api/chapters/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the chapter

Permissions Required

  • Read access to the manual
  • User's user type within the chapter's user types

Get Subchapters

curl "https://example.ziik.io/api/chapters/123/subchapters"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

  {
            "id": 930,
            "content_type": "manuals",
            "permissions": {
                "edit": true,
                "delete": true
            },
            "title": "General Employment Policies and Practicies",
            "description": null,
            "chapters": [{
                "id": 935,
                "content_type": "manuals",
                "permissions": {
                    "edit": true,
                    "delete": true
                },
                "title": "Your Employment Relationship with the Company",
                "description": null,
                "chapters": [],
                "paragraphs": [
                    {
                      "text": "<HTML TEXT>",
                      "files": [{
                          "id": 643,
                          "name": "filename.jpg",
                          "mime": "image/jpeg",
                          "size": 102380,
                          "type": "image",
                          "source": "https://example.ziik.io/api/file/manuals/filename.jpg",
                          "versions": {
                              "listing": "https://example.ziik.io/api/file/styles/article_listing/private/manuals/filename.jpg",
                              "detail": "https://example.ziik.io/api/file/styles/article_desktop/private/manuals/filename.jpg",
                              "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/manuals/filename.png"
                          }
                      }]
                    }
                ],
                "url": "api/manuals/935"
            }, {
                "id": 936,
                "content_type": "manuals",
                "permissions": {
                    "edit": true,
                    "delete": true
                },
                "title": "Hours of work",
                "description": null,
                "chapters": [],
                "paragraphs": [],
                "url": "api/manuals/936"
            }, {
                "id": 937,
                "content_type": "manuals",
                "permissions": {
                    "edit": true,
                    "delete": true
                },
                "title": "Dress Code and Public Image",
                "description": null,
                "chapters": [],
                "paragraphs": [],
                "url": "api/manuals/937"
            }, {
                "id": 938,
                "content_type": "manuals",
                "permissions": {
                    "edit": true,
                    "delete": true
                },
                "title": "Communication",
                "description": null,
                "chapters": [],
                "paragraphs": [],
                "url": "api/manuals/938"
            }, {
                "id": 1256,
                "content_type": "manuals",
                "permissions": {
                    "edit": true,
                    "delete": true
                },
                "title": "Something",
                "description": null,
                "chapters": [],
                "paragraphs": [],
                "url": "api/manuals/1256"
            }],
            "paragraphs": [
                {
                  "text": "<HTML TEXT>",
                  "files": [{
                      "id": 643,
                      "name": "filename.jpg",
                      "mime": "image/jpeg",
                      "size": 102380,
                      "type": "image",
                      "source": "https://example.ziik.io/api/file/manuals/filename.jpg",
                      "versions": {
                          "listing": "https://example.ziik.io/api/file/styles/article_listing/private/manuals/filename.jpg",
                          "detail": "https://example.ziik.io/api/file/styles/article_desktop/private/manuals/filename.jpg",
                          "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/manuals/filename.png"
                      }
                  }]
                }
            ],
            "url": "api/manuals/930"

This endpoint returns a subchapters and their paragraphs to a given chapter

HTTP Request

GET https://example.ziik.io/api/chapters/ID/subchapters

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the chapter

Permissions Required

  • Read access to the manual
  • User's user type within the chapter's user types

Get Single Paragraph

curl "https://example.ziik.io/api/paragraphs/123"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

    {
      "text": "<HTML TEXT>",
      "files": [{
          "id": 643,
          "name": "filename.jpg",
          "mime": "image/jpeg",
          "size": 102380,
          "type": "image",
          "source": "https://example.ziik.io/api/file/manuals/filename.jpg",
          "versions": {
              "listing": "https://example.ziik.io/api/file/styles/article_listing/private/manuals/filename.jpg",
              "detail": "https://example.ziik.io/api/file/styles/article_desktop/private/manuals/filename.jpg",
              "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/manuals/filename.png"
          }
      }]
    }

This endpoint returns a paragraph

HTTP Request

GET https://example.ziik.io/api/chapters/ID/subchapters

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the paragraph

Permissions Required

  • Read access to the paragraph's chapter

Update Paragraph

curl -i -X PATCH "https://example.ziik.io/api/paragraphs/123"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on successful update.

HTTP/1.0 204 No Content

This endpoint updates an existing paragraph.

HTTP Request

PATCH https://example.ziik.io/api/paragraphs/ID

ParameterTypeRequiredDescription
textStringYesParagraph contents
filesArrayNoFile data for files to accompany the paragraph. Must be an array of arrays with the following values
- typeStringYesType of file - can be either 'upload', 'youtube' or 'vimeo'.
- nameStringYesFile name.
- dataStringYesIf type is 'upload' this must be the base64 encoded content of the file. Else it must be the Youtube/Vimeo embed URL.

Permissions Required

  • Update permission to the manual

Delete Paragraph

curl -i -X DELETE "https://example.ziik.io/api/paragraphs/123"
  -H "Authorization: Bearer aaaaaa.bbbbbbb.ccccccc"

The above command returns a 204 No Content header on success:

HTTP/1.0 204 No Content

This endpoint deletes a paragraph.

HTTP Request

DELETE https://example.ziik.io/api/paragraphs/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the paragraph to delete

Permissions Required

  • Update permission to the manual

Move Paragraph In Chapter

curl -i -X POST "https://example.ziik.io/api/paragraphs/123/move"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on success

HTTP/1.0 204 No Content

This endpoint moves a paragraph to a new order in the chapter.

HTTP Request

POST https://example.ziik.io/api/paragraphs/ID/move

Request Parameters

ParameterTypeRequiredDescription
newIntegerYesPosition in the paragraph ordering (1 = first, 2 = second etc.)

Add Files To Paragraph

curl -i -X POST "https://example.ziik.io/api/paragraphs/files"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on success

HTTP/1.0 204 No Content

This endpoint adds files to an existing paragraph.

HTTP Request

POST https://example.ziik.io/api/paragraphs/files

Request Parameters

ParameterTypeDescription
idIntegerThe ID of the paragraph to add files to
filesArrayNo
- typeStringYes
- nameStringYes
- dataStringYes

Permissions Required

  • Manual edit access

Delete File From Paragraph

curl -i -X DELETE "https://example.ziik.io/api/paragraphs/124/files/12345"
  -H "Authorization: Bearer aaaaaa.bbbbbbb.ccccccc"

The above command returns a 204 No Content header on success:

HTTP/1.0 204 No Content

This endpoint deletes a file from a paragraph.

HTTP Request

DELETE https://example.ziik.io/api/paragraphs/<ParagraphID>/files/<FileID>

URL Parameters

ParameterTypeDescription
ParagraphIDIntegerThe ID of the paragraph
FileIDIntegerThe ID of the file to delete

Permissions Required

  • Manual edit access