Documentation Powered by Redocly

# HumHub - Polls API (1.0.0)

Download OpenAPI specification:Download

E-mail: info@humhub.com License: AGPLv2

Welcome to the HumHub polls module API reference.

# Authentication

## Bearer

Security Scheme Type | JWT

## BasicAuth

Security Scheme Type | HTTP
HTTP Authorization Scheme | basic

# Polls

## Find all polls

##### query Parameters

page | string >= 0 The number of page of the result set.
limit | string [ 1 .. 50 ] Default: 20 The numbers of items to return per page.

### Responses

/api/v1/polls

### Response samples

- 200

Content type
application/json
application/json
application/xml
`
{

- "total": 76,
- "page": 1,
- "pages": 8,
- "links":
  {
  - "self": "{endpoint_path}?page=1&per-page=10",
  - "next": "{endpoint_path}?page=2&per-page=10",
  - "last": "{endpoint_path}?page=8&per-page=10"
  },
- "results":
  [
  - {
    - "id": 4,
    - "contentcontainer_id": 2,
    - "question": "Poll question from API?",
    - "description": "Poll description from API",
    - "allow_multiple": 1,
    - "created_at": "2021-07-20 09:43:12",
    - "created_by":
      {
      - "id": 14,
      - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
      - "display_name": "John Doe",
      - "url": "http://localhost/p/humhub/master/u/j.doe/"
      },
    - "updated_at": "2021-07-20 09:43:12",
    - "updated_by":
      {
      - "id": 14,
      - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
      - "display_name": "John Doe",
      - "url": "http://localhost/p/humhub/master/u/j.doe/"
      },
    - "is_random": 1,
    - "closed": 1,
    - "anonymous": 0,
    - "show_result_after_close": 0,
    - "answers":
      [
      - {
        - "id": 1,
        - "poll_id": 4,
        - "answer": "First answer text",
        - "created_at": "2021-07-20 10:43:12",
        - "created_by":
          {
          - "id": 14,
          - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
          - "display_name": "John Doe",
          - "url": "http://localhost/p/humhub/master/u/j.doe/"
          },
        - "updated_at": "2021-07-20 10:43:12",
        - "updated_by":
          {
          - "id": 14,
          - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
          - "display_name": "John Doe",
          - "url": "http://localhost/p/humhub/master/u/j.doe/"
          }
        }
      ],
    - "content":
      {
      - "metadata":
        {
        - "id": 14,
        - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
        - "object_model": "humhub\\modules\\post\\models\\Post",
        - "object_id": 12,
        - "visibility": 1,
        - "archived": true,
        - "pinned": false,
        - "locked_comments": false,
        - "created_by":
          {
          - "id": 14,
          - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
          - "display_name": "John Doe",
          - "url": "http://localhost/p/humhub/master/u/j.doe/"
          },
        - "created_at": "2022-04-13 05:15:43",
        - "url": "http://localhost/p/humhub/master/content/perma?id=109",
        - "contentcontainer_id": 5,
        - "stream_channel": "default"
        },
      - "comments":
        {
        - "total": 55,
        - "latestComments":
          [
          - {
            - "id": 14,
            - "message": "Calvin Klein – Between love and madness lies obsession.",
            - "createdBy":
              {
              - "id": 14,
              - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
              - "display_name": "John Doe",
              - "url": "http://localhost/p/humhub/master/u/j.doe/"
              },
            - "createdAt": "2018-08-09 14:22:03"
            }
          ]
        },
      - "likes":
        {
        - "total": 35
        },
      - "files":
        {
        - "id": 14,
        - "guid": "bded6dc7-e6f4-417e-a638-b653525529ca",
        - "mime_type": "text/plain",
        - "size": 14353,
        - "file_name": "image.jpg",
        - "url": "http://localhost/p/humhub/master/file/file/download?guid=bded6dc7-e6f4-417e-a638-b653525529ca"
        },
      - "topics":
        [
        - {
          - "id": 135,
          - "name": "News"
          }
        ]
      }
    }
  ]

}`

## Find all polls by container

##### path Parameters

id required | integer ID of content container

##### query Parameters

page | string >= 0 The number of page of the result set.
limit | string [ 1 .. 50 ] Default: 20 The numbers of items to return per page.

### Responses

/api/v1/polls/container/{id}

### Response samples

- 200
- 404

Content type
application/json
application/json
application/xml
`
{

- "total": 76,
- "page": 1,
- "pages": 8,
- "links":
  {
  - "self": "{endpoint_path}?page=1&per-page=10",
  - "next": "{endpoint_path}?page=2&per-page=10",
  - "last": "{endpoint_path}?page=8&per-page=10"
  },
- "results":
  [
  - {
    - "id": 4,
    - "contentcontainer_id": 2,
    - "question": "Poll question from API?",
    - "description": "Poll description from API",
    - "allow_multiple": 1,
    - "created_at": "2021-07-20 09:43:12",
    - "created_by":
      {
      - "id": 14,
      - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
      - "display_name": "John Doe",
      - "url": "http://localhost/p/humhub/master/u/j.doe/"
      },
    - "updated_at": "2021-07-20 09:43:12",
    - "updated_by":
      {
      - "id": 14,
      - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
      - "display_name": "John Doe",
      - "url": "http://localhost/p/humhub/master/u/j.doe/"
      },
    - "is_random": 1,
    - "closed": 1,
    - "anonymous": 0,
    - "show_result_after_close": 0,
    - "answers":
      [
      - {
        - "id": 1,
        - "poll_id": 4,
        - "answer": "First answer text",
        - "created_at": "2021-07-20 10:43:12",
        - "created_by":
          {
          - "id": 14,
          - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
          - "display_name": "John Doe",
          - "url": "http://localhost/p/humhub/master/u/j.doe/"
          },
        - "updated_at": "2021-07-20 10:43:12",
        - "updated_by":
          {
          - "id": 14,
          - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
          - "display_name": "John Doe",
          - "url": "http://localhost/p/humhub/master/u/j.doe/"
          }
        }
      ],
    - "content":
      {
      - "metadata":
        {
        - "id": 14,
        - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
        - "object_model": "humhub\\modules\\post\\models\\Post",
        - "object_id": 12,
        - "visibility": 1,
        - "archived": true,
        - "pinned": false,
        - "locked_comments": false,
        - "created_by":
          {
          - "id": 14,
          - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
          - "display_name": "John Doe",
          - "url": "http://localhost/p/humhub/master/u/j.doe/"
          },
        - "created_at": "2022-04-13 05:15:43",
        - "url": "http://localhost/p/humhub/master/content/perma?id=109",
        - "contentcontainer_id": 5,
        - "stream_channel": "default"
        },
      - "comments":
        {
        - "total": 55,
        - "latestComments":
          [
          - {
            - "id": 14,
            - "message": "Calvin Klein – Between love and madness lies obsession.",
            - "createdBy":
              {
              - "id": 14,
              - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
              - "display_name": "John Doe",
              - "url": "http://localhost/p/humhub/master/u/j.doe/"
              },
            - "createdAt": "2018-08-09 14:22:03"
            }
          ]
        },
      - "likes":
        {
        - "total": 35
        },
      - "files":
        {
        - "id": 14,
        - "guid": "bded6dc7-e6f4-417e-a638-b653525529ca",
        - "mime_type": "text/plain",
        - "size": 14353,
        - "file_name": "image.jpg",
        - "url": "http://localhost/p/humhub/master/file/file/download?guid=bded6dc7-e6f4-417e-a638-b653525529ca"
        },
      - "topics":
        [
        - {
          - "id": 135,
          - "name": "News"
          }
        ]
      }
    }
  ]

}`

## Delete polls by container

##### path Parameters

id required | integer The id of content container

### Responses

/api/v1/polls/container/{id}

### Response samples

- 200
- 404

Content type
application/json
`
{

- "code": 200,
- "message": "Records successfully deleted!"

}`

# Poll

## Create new poll

##### path Parameters

id required | integer The id of content container

##### Request Body schema: application/json

Poll information

required | object
newAnswers required | Array of strings New answers
| object (Content)

### Responses

/api/v1/polls/container/{id}

### Request samples

- Payload

Content type
application/json
`
{

- "Poll":
  {
  - "question": "New question from API?",
  - "description": "New description from API?",
  - "allow_multiple": 0,
  - "is_random": 1,
  - "anonymous": 0,
  - "show_result_after_close": 0
  },
- "newAnswers":
  [
  - "First answer",
  - "Second answer",
  - "Third answer"
  ],
- "content":
  {
  - "metadata":
    {
    - "visibility": 1,
    - "archived": true,
    - "pinned": false,
    - "locked_comments": false
    },
  - "topics":
    [
    - {
      - "name": "News"
      }
    ]
  }

}`

### Response samples

- 200
- 403
- 404
- 500

Content type
application/json
`
{

- "id": 4,
- "contentcontainer_id": 2,
- "question": "Poll question from API?",
- "description": "Poll description from API",
- "allow_multiple": 1,
- "created_at": "2021-07-20 09:43:12",
- "created_by":
  {
  - "id": 14,
  - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
  - "display_name": "John Doe",
  - "url": "http://localhost/p/humhub/master/u/j.doe/"
  },
- "updated_at": "2021-07-20 09:43:12",
- "updated_by":
  {
  - "id": 14,
  - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
  - "display_name": "John Doe",
  - "url": "http://localhost/p/humhub/master/u/j.doe/"
  },
- "is_random": 1,
- "closed": 1,
- "anonymous": 0,
- "show_result_after_close": 0,
- "answers":
  [
  - {
    - "id": 1,
    - "poll_id": 4,
    - "answer": "First answer text",
    - "created_at": "2021-07-20 10:43:12",
    - "created_by":
      {
      - "id": 14,
      - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
      - "display_name": "John Doe",
      - "url": "http://localhost/p/humhub/master/u/j.doe/"
      },
    - "updated_at": "2021-07-20 10:43:12",
    - "updated_by":
      {
      - "id": 14,
      - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
      - "display_name": "John Doe",
      - "url": "http://localhost/p/humhub/master/u/j.doe/"
      }
    }
  ],
- "content":
  {
  - "metadata":
    {
    - "id": 14,
    - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
    - "object_model": "humhub\\modules\\post\\models\\Post",
    - "object_id": 12,
    - "visibility": 1,
    - "archived": true,
    - "pinned": false,
    - "locked_comments": false,
    - "created_by":
      {
      - "id": 14,
      - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
      - "display_name": "John Doe",
      - "url": "http://localhost/p/humhub/master/u/j.doe/"
      },
    - "created_at": "2022-04-13 05:15:43",
    - "url": "http://localhost/p/humhub/master/content/perma?id=109",
    - "contentcontainer_id": 5,
    - "stream_channel": "default"
    },
  - "comments":
    {
    - "total": 55,
    - "latestComments":
      [
      - {
        - "id": 14,
        - "message": "Calvin Klein – Between love and madness lies obsession.",
        - "createdBy":
          {
          - "id": 14,
          - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
          - "display_name": "John Doe",
          - "url": "http://localhost/p/humhub/master/u/j.doe/"
          },
        - "createdAt": "2018-08-09 14:22:03"
        }
      ]
    },
  - "likes":
    {
    - "total": 35
    },
  - "files":
    {
    - "id": 14,
    - "guid": "bded6dc7-e6f4-417e-a638-b653525529ca",
    - "mime_type": "text/plain",
    - "size": 14353,
    - "file_name": "image.jpg",
    - "url": "http://localhost/p/humhub/master/file/file/download?guid=bded6dc7-e6f4-417e-a638-b653525529ca"
    },
  - "topics":
    [
    - {
      - "id": 135,
      - "name": "News"
      }
    ]
  }

}`

## Get a poll by id

##### path Parameters

id required | integer The id of the poll

### Responses

/api/v1/polls/poll/{id}

### Response samples

- 200
- 404

Content type
application/json
`
{

- "id": 4,
- "contentcontainer_id": 2,
- "question": "Poll question from API?",
- "description": "Poll description from API",
- "allow_multiple": 1,
- "created_at": "2021-07-20 09:43:12",
- "created_by":
  {
  - "id": 14,
  - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
  - "display_name": "John Doe",
  - "url": "http://localhost/p/humhub/master/u/j.doe/"
  },
- "updated_at": "2021-07-20 09:43:12",
- "updated_by":
  {
  - "id": 14,
  - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
  - "display_name": "John Doe",
  - "url": "http://localhost/p/humhub/master/u/j.doe/"
  },
- "is_random": 1,
- "closed": 1,
- "anonymous": 0,
- "show_result_after_close": 0,
- "answers":
  [
  - {
    - "id": 1,
    - "poll_id": 4,
    - "answer": "First answer text",
    - "created_at": "2021-07-20 10:43:12",
    - "created_by":
      {
      - "id": 14,
      - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
      - "display_name": "John Doe",
      - "url": "http://localhost/p/humhub/master/u/j.doe/"
      },
    - "updated_at": "2021-07-20 10:43:12",
    - "updated_by":
      {
      - "id": 14,
      - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
      - "display_name": "John Doe",
      - "url": "http://localhost/p/humhub/master/u/j.doe/"
      }
    }
  ],
- "content":
  {
  - "metadata":
    {
    - "id": 14,
    - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
    - "object_model": "humhub\\modules\\post\\models\\Post",
    - "object_id": 12,
    - "visibility": 1,
    - "archived": true,
    - "pinned": false,
    - "locked_comments": false,
    - "created_by":
      {
      - "id": 14,
      - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
      - "display_name": "John Doe",
      - "url": "http://localhost/p/humhub/master/u/j.doe/"
      },
    - "created_at": "2022-04-13 05:15:43",
    - "url": "http://localhost/p/humhub/master/content/perma?id=109",
    - "contentcontainer_id": 5,
    - "stream_channel": "default"
    },
  - "comments":
    {
    - "total": 55,
    - "latestComments":
      [
      - {
        - "id": 14,
        - "message": "Calvin Klein – Between love and madness lies obsession.",
        - "createdBy":
          {
          - "id": 14,
          - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
          - "display_name": "John Doe",
          - "url": "http://localhost/p/humhub/master/u/j.doe/"
          },
        - "createdAt": "2018-08-09 14:22:03"
        }
      ]
    },
  - "likes":
    {
    - "total": 35
    },
  - "files":
    {
    - "id": 14,
    - "guid": "bded6dc7-e6f4-417e-a638-b653525529ca",
    - "mime_type": "text/plain",
    - "size": 14353,
    - "file_name": "image.jpg",
    - "url": "http://localhost/p/humhub/master/file/file/download?guid=bded6dc7-e6f4-417e-a638-b653525529ca"
    },
  - "topics":
    [
    - {
      - "id": 135,
      - "name": "News"
      }
    ]
  }

}`

## Update a poll by id

##### path Parameters

id required | integer The id of the poll

##### Request Body schema: application/json

Poll information

required | object
answers | Array of strings Updating answers
newAnswers required | Array of strings New answers
| object (Content)

### Responses

/api/v1/polls/poll/{id}

### Request samples

- Payload

Content type
application/json
`
{

- "Poll":
  {
  - "question": "New question from API?",
  - "description": "New description from API?",
  - "allow_multiple": 0,
  - "is_random": 1,
  - "anonymous": 0,
  - "show_result_after_close": 0
  },
- "answers":
  [
  - {
    - "1": "Updated first answer"
    },
  - {
    - "2": "Updated second answer"
    },
  - {
    - "3": "Updated third answer"
    }
  ],
- "newAnswers":
  [
  - "Fourth answer",
  - "Fifth answer"
  ],
- "content":
  {
  - "metadata":
    {
    - "visibility": 1,
    - "archived": true,
    - "pinned": false,
    - "locked_comments": false
    },
  - "topics":
    [
    - {
      - "name": "News"
      }
    ]
  }

}`

### Response samples

- 200
- 403
- 404
- 500

Content type
application/json
`
{

- "id": 4,
- "contentcontainer_id": 2,
- "question": "Poll question from API?",
- "description": "Poll description from API",
- "allow_multiple": 1,
- "created_at": "2021-07-20 09:43:12",
- "created_by":
  {
  - "id": 14,
  - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
  - "display_name": "John Doe",
  - "url": "http://localhost/p/humhub/master/u/j.doe/"
  },
- "updated_at": "2021-07-20 09:43:12",
- "updated_by":
  {
  - "id": 14,
  - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
  - "display_name": "John Doe",
  - "url": "http://localhost/p/humhub/master/u/j.doe/"
  },
- "is_random": 1,
- "closed": 1,
- "anonymous": 0,
- "show_result_after_close": 0,
- "answers":
  [
  - {
    - "id": 1,
    - "poll_id": 4,
    - "answer": "First answer text",
    - "created_at": "2021-07-20 10:43:12",
    - "created_by":
      {
      - "id": 14,
      - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
      - "display_name": "John Doe",
      - "url": "http://localhost/p/humhub/master/u/j.doe/"
      },
    - "updated_at": "2021-07-20 10:43:12",
    - "updated_by":
      {
      - "id": 14,
      - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
      - "display_name": "John Doe",
      - "url": "http://localhost/p/humhub/master/u/j.doe/"
      }
    }
  ],
- "content":
  {
  - "metadata":
    {
    - "id": 14,
    - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
    - "object_model": "humhub\\modules\\post\\models\\Post",
    - "object_id": 12,
    - "visibility": 1,
    - "archived": true,
    - "pinned": false,
    - "locked_comments": false,
    - "created_by":
      {
      - "id": 14,
      - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
      - "display_name": "John Doe",
      - "url": "http://localhost/p/humhub/master/u/j.doe/"
      },
    - "created_at": "2022-04-13 05:15:43",
    - "url": "http://localhost/p/humhub/master/content/perma?id=109",
    - "contentcontainer_id": 5,
    - "stream_channel": "default"
    },
  - "comments":
    {
    - "total": 55,
    - "latestComments":
      [
      - {
        - "id": 14,
        - "message": "Calvin Klein – Between love and madness lies obsession.",
        - "createdBy":
          {
          - "id": 14,
          - "guid": "cd081891-d2e2-40d5-84a4-b47309e71c80",
          - "display_name": "John Doe",
          - "url": "http://localhost/p/humhub/master/u/j.doe/"
          },
        - "createdAt": "2018-08-09 14:22:03"
        }
      ]
    },
  - "likes":
    {
    - "total": 35
    },
  - "files":
    {
    - "id": 14,
    - "guid": "bded6dc7-e6f4-417e-a638-b653525529ca",
    - "mime_type": "text/plain",
    - "size": 14353,
    - "file_name": "image.jpg",
    - "url": "http://localhost/p/humhub/master/file/file/download?guid=bded6dc7-e6f4-417e-a638-b653525529ca"
    },
  - "topics":
    [
    - {
      - "id": 135,
      - "name": "News"
      }
    ]
  }

}`

## Delete a poll by id

##### path Parameters

id required | integer The id of the poll

### Responses

/api/v1/polls/poll/{id}

### Response samples

- 200
- 403
- 404
- 500

Content type
application/json
`
{

- "code": 200,
- "message": "Successfully deleted!"

}`

# Poll management

## Close a poll by id

##### path Parameters

id required | integer The id of the poll

### Responses

/api/v1/polls/poll/{id}/close

### Response samples

- 200
- 403
- 404
- 500

Content type
application/json
`
{

- "code": 200,
- "message": "Poll has been successfully closed."

}`

## Open a poll by id

##### path Parameters

id required | integer The id of the poll

### Responses

/api/v1/polls/poll/{id}/open

### Response samples

- 200
- 403
- 404
- 500

Content type
application/json
`
{

- "code": 200,
- "message": "Poll has been successfully reopened."

}`

# Poll voting

## Vote on a poll by id

##### path Parameters

id required | integer The id of the poll

##### Request Body schema: application/json

answers | Array of integers[ items ] Selected answers

### Responses

/api/v1/polls/vote/{id}

### Request samples

- Payload

Content type
application/json
`
{

- "answers":
  [
  - 1,
  - 4
  ]

}`

### Response samples

- 200
- 403
- 404

Content type
application/json
`
{

- "code": 200,
- "message": "You have voted."

}`

## Reset vote on a poll by id

##### path Parameters

id required | integer The id of the poll

### Responses

/api/v1/polls/vote/{id}

### Response samples

- 200
- 403
- 404

Content type
application/json
`
{

- "code": 200,
- "message": "You have reset your vote."

}`

## Get votes on a poll for current user

##### path Parameters

id required | integer The id of the poll

### Responses

/api/v1/polls/vote/{id}

### Response samples

- 200
- 404

Content type
application/json
`
[

- [
  - 11,
  - 13,
  - 24
  ]

]`