Skip to content

API

Jump to bottom
René Gieling edited this page Jun 28, 2025 · 3 revisions

DRAFT

This documentation and the API are not final, out of date and may contain issues and bugs! Details may change!

Find the actual endpoints by looking into the ApiControllers.

  • To act like a authenticated user, use username:password@ prefix in the URL.
  • Parameters in the body override the URL-parameter

Base URL for all calls: /ocs/v2.php/apps/polls/api/v1.0

Example calls:

  • Gets all comments of poll no. 1 https://username:[email protected]/ocs/v2.php/apps/polls/api/v1.0/poll/1/comments 
`curl -u username:password -X GET https://nextcloud.local/ocs/v2.php/apps/polls/api/v1.0/poll/1/comments`

Poll

Default functions

Method Endpoint Payload Description Return codes Return value
GET /polls no Get array of polls 200, 403, 404 array
GET /poll/{pollId} no Get poll with {pollId} 200, 403, 404 requested poll
POST /poll yes Add new poll 201, 403, 404 added poll
PUT /poll/{pollId} yes Update poll 200, 403, 404, 409 updated poll
DELETE /poll/{pollId} no Delete poll 200, 403, 404 deleted poll

Special functions

Method Endpoint Payload Description Return codes Return value
POST /poll/{pollId}/clone no Clone poll from {pollId} 201, 403, 404 cloned poll
POST /poll/{pollId}/trash no Move to/remome from trash 200, 403, 404 updated poll
GET /enum/poll no Get valid enums 200, 403, 404 array

Valid payloads

Add new poll

{
    "type": "datePoll",
    "title": "Poll Title"
}

Update poll

send the full or a partial structure

{
    "poll": {
        "title": "Changed Title",
        "description": "Updated description",
        "expire": 0,
        "deleted": 0,
        "access": "hidden",
        "anonymous": 1,
        "allowMaybe": 1,
        "showResults": "never",
        "adminAccess": 1
    }
}

Keys and values

Key Type description
expire integer unix timestamp
deleted integer unix timestamp

Options

Default functions

Method Endpoint Payload Description Return codes Return value
GET /poll/{pollId}/options no Get poll options 200, 403, 404 array
POST /poll/{pollId}/option yes Add new option 201, 403, 404, 409 added option
PUT /option/{optionId} yes Update option 200, 403, 404 updated option
DELETE /option/{optionId} no Delete option 200, 403, 404 deleted option

Special functions (no payloads)

Method Endpoint Description Return codes Return value
PUT /option/{optionId}/confirm Confirm/unconfirm option 200, 403, 404 confirmed option
PUT /option/{optionId}/setorder/{order} Set order (text poll) 200, 403, 404 array

Valid payloads

Add/update option (text poll)

{
    "pollOptionText": "Text of new option"
}

Add/update option (date poll)

{
	"timestamp": 1589195823,
    "duration": 1800
}

Keys and values

Key Type description
pollOptionText String poll text
timestamp Integer 10 digit unix timestamp
duration Integer duration in seconds

Votes

Method Endpoint Description Return codes
GET /poll/{pollId}/votes Get votes 200, 403, 404
POST /vote Set vote with Payload 200, 403, 404

set vote

{
    "optionId": 1,
    "setTo" :"yes"
}

Comments

Method Endpoint Description Return codes
GET /poll/{pollId}/comments Get comments 200, 403, 404
POST /comment Add new comment with Payload 201, 403, 404
DELETE /comment/{commentId} Delete comment 200, 403, 404

Add comment

{
    "pollId": 1,
    "message": "Comment text"
}

Shares

Method Endpoint Description Return codes
GET /poll/{pollId}/shares Get shares 200, 403, 404
GET /share/{token} Get share by token 200, 403, 404
POST /share Add new share with Payload 201, 403, 404
DELETE /share/{token} Delete share 200, 404, 409

Add share

public share

{
    "type": "public",
    "pollId": 1
}

user share

tbd

email share

tbd

contact share

tbd

Subscription

Method Endpoint Description Return codes
GET /poll/{pollId}/subscription Get subscription status 200, 403, 404
PUT /poll/{pollId}/subscription Subcribe 201, 403
DELETE /poll/{pollId}/subscription unsubscribe 200, 403
Clone this wiki locally