API Documentation

API Documentation

OpenPoll features a simple RESTful API that allows clients to interact with the platform programmatically. You are able to create and get polls using the API. To use the api you need to have an API key. The api can be generated in the settings page.

Endpoint: Create Poll

This endpoint allows clients to create a new poll. Clients must be authorized to use this endpoint.

HTTP Method

POST

Endpoint

/api/poll/create

Headers

  • Authorization: A valid API key to authenticate the request.

Request Body

The request body must be a JSON object that contains the following properties:

  • question: A string representing the poll question.
  • options: An array of strings representing the poll options.
{
  "name": "My Poll Event",
  "question": "What is your favorite programming language?",
  "options": [
    "Python",
    "JavaScript",
    "Java",
    "C#",
    "C++",
    "Go",
    "Ruby",
    "Swift",
    "Kotlin",
    "Rust"
  ]
}

Successful Response

A successful response returns HTTP status 200 along with the poll details in JSON format, including a unique URL for accessing the poll and an API URL for further interactions.

{
  "id": 31,
  "name": "My Poll Event",
  "question": "What is your favorite programming language?",
  "timestamp": "2024-04-13T15:10:01",
  "views": 0,
  "shortId": "PK_IOGjY5i",
  "creatorId": "891272f3-4a4c-4bba-b28a-ea3bd3eb5de0",
  "isLocked": false,
  "selectedPollOptionId": null,
  "options": [
    {
      "id": 69,
      "pollId": 31,
      "option": "Python",
      "votes": 0
    },
    {
      "id": 70,
      "pollId": 31,
      "option": "JavaScript",
      "votes": 0
    },
    // Additional options omitted 
  ],
  "url": "https://openpoll.app/PK_IOGjY5i", // Used to access the poll on the web
  "api_url": "https://openpoll.app/api/poll/PK_IOGjY5i" // Used to interact with the poll via the API
}

Error Responses

  • 401 Unauthorized: Returned if the Authorization header is missing or the API key is invalid.
  • 429 Too Many Requests: Returned if the request rate limit is exceeded. The rate limit is 10 requests per hour per API key.

Rate Limiting

Rate limiting is enforced using a Redis key based on the Authorization header. If the number of requests exceeds the limit within an hour, subsequent requests will receive a 429 status code. The limit resets after one hour.

Example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Poll Event",
    "question": "What is your favorite programming language?",
    "options": [
      "Python",
      "JavaScript",
      "Java",
      "C#",
      "C++",
      "Go",
      "Ruby",
      "Swift",
      "Kotlin",
      "Rust"
    ]
  }' \
  https://openpoll.app/api/poll/create

Endpoint: Get Poll Details

This endpoint allows clients to retrieve details about a specific poll. Clients must be authorized and have the appropriate privileges to access the poll data.

HTTP Method

GET

Endpoint

/api/poll/{pollId}

URL Parameters

  • pollId: The unique identifier for the poll. Also called the shortId.

Headers

  • Authorization: A valid API key to authenticate the request.

Successful Response

A successful response returns HTTP status 200 along with the poll details in JSON format.

{
  "id": 31,
  "question": "What is your favorite programming language?",
  "timestamp": "2024-04-13T15:10:01",
  "views": 0,
  "shortId": "PK_IOGjY5i",
  "creatorId": "891272f3-4a4c-4bba-b28a-ea3bd3eb5de0",
  "isLocked": false,
  "selectedPollOptionId": null,
  "options": [
    {
      "id": 69,
      "pollId": 31,
      "option": "Python",
      "votes": 0
    },
    {
      "id": 70,
      "pollId": 31,
      "option": "JavaScript",
      "votes": 0
    },
    // Additional options omitted for brevity
  ],
  "url": "https://openpoll.app/PK_IOGjY5i",
  "api_url": "https://openpoll.app/api/poll/PK_IOGjY5i"
}

Error Responses

  • 401 Unauthorized: Returned if the Authorization header is missing or the API key is invalid.
  • 404 Not Found: Returned if no poll matches the given pollId.
  • 403 Forbidden: Returned if the authenticated user does not have permission to access the specified poll details.

Example

curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  https://openpoll.app/api/poll/{pollId}