Related articles
API Endpoints & Parameters
Here you will find a list of all of the available endpoints for MagicChecklists. Make sure to replace the {{SITE_URL}} with your actual domain URL (for example https://example.com) and also insert your checklist id for {{checklist_id} (for example 123).
You can find the checklist ID in the URL when editing the desired checklist or in your database.
/wp-admin/admin.php?page=mcl_add_new&checklist_id=123Base URL:
{{SITE_URL}}/wp-json/magicchecklists/v1/Available Endpoints
| Endpoint | Method | Description |
|---|---|---|
/checklists | GET | Retrieve all checklists |
/checklists | POST | Create a new checklist |
/checklists/{checklist_id} | GET | Retrieve a specific checklist |
/checklists/{checklist_id} | PUT | Update an existing checklist |
/checklists/{checklist_id}/items | PUT | Update/create list items |
/checklists/{checklist_id}/checked-state | PUT | Update items’ checked state |
/checklists/{checklist_id} | DELETE | Delete a checklist |
Request Examples
| Method + Endpoint URL | What it does |
|---|---|
GET https://your-domain.com/wp-json/magicchecklists/v1/checklists | Retrieves all checklists |
POST https://your-domain.com/wp-json/magicchecklists/v1/checklists | Creates a new checklist |
GET https://your-domain.com/wp-json/magicchecklists/v1/checklists/123 | Retrieves a specific checklist |
PUT https://you-domain.com/wp-json/magicchecklists/v1/checklists/123 | Updates a specific checklist |
PUT https://your-domain.com/wp-json/magicchecklists/v1/checklists/123/items | Updates and/or created list items for a specific checklist |
PUT https://your-domain.com/wp-json/magicchecklists/v1/checklists/123/checked-state | Updates the checked state of one or multiple list items |
DELETE https://your-domain.com/wp-json/magicchecklists/v1/checklists/123 | Deletes a specific checklist. |
PUT https://your-domain.com/wp-json/magicchecklists/v1/checklists/123/notification-settings | Retrieve or change the notification settings of a checklist. |
Response Body examples
| Code | Description |
|---|---|
| 200 No JSON body needed for just retrieving all checklists. | Successfully retrieved all checklists. |
| 201 { “id”: 123, “title”: “New Test Checklist”, “description”: “This is a test checklist created via API”, “date_created”: “2024-12-12T13:38:50”, “date_modified”: “2024-12-12T13:38:50”, “items”: [ { “id”: “item1”, “content”: “First task”, “priority”: “high” }, { “id”: “item2”, “content”: “Second task”, “priority”: “medium” } ], “checked_state”: [], “_links”: { “self”: [ { “href”: “https://plugin-dev.local/wp-json/magicchecklists/v1/checklists/193” } ], “items”: [ { “href”: “https://plugin-dev.local/wp-json/magicchecklists/v1/checklists/193/items” } ], “checked-state”: [ { “href”: “https://plugin-dev.local/wp-json/magicchecklists/v1/checklists/193/checked-state” } ] } } | Created a new checklist successfully |
| 200 { “id”: 123, “title”: “New checklist title”, “description”: “Yup, it really works!”, “date_created”: “2024-12-06T21:18:24”, “date_modified”: “2024-12-12T13:38:27”, “time_date”: “1733875980”, “items”: [ { “id”: “item11”, “content”: “It’s working just like it should.”, “priority”: “low” }, { “id”: “item12”, “content”: “fantastic mate!”, “priority”: “low” }, { “id”: “item13”, “content”: “maus ist toll”, “priority”: “high” }, { “id”: “item_1733836180047”, “content”: “new item yauers<br>”, “priority”: “none” } ], “keyboard_shortcut”: “Ctrl+A”, “active”: “1”, “checked_state_handling”: “per_user”, “theme”: “light”, “priority”: “none”, “enable_item_priority”: “0”, “trigger_shortcut”: “1”, “trigger_button”: “1”, “short_title”: “test”, “public_access”: “0”, “public_permission”: “interact”, “public_checked_state_handling”: “global”, “priority_display_type”: “color”, “enable_rate_limit”: “1”, “checked_state”: [], “_links”: { “self”: [ { “href”: “https://plugin-dev.local/wp-json/magicchecklists/v1/checklists/184” } ], “items”: [ { “href”: “https://plugin-dev.local/wp-json/magicchecklists/v1/checklists/184/items” } ], “checked-state”: [ { “href”: “https://plugin-dev.local/wp-json/magicchecklists/v1/checklists/184/checked-state” } ] } } | Successfully retrieved the desired checklist |
| 200 { “id”: 123, “title”: “New checklist title”, “description”: “Yup, it really works!”, “date_created”: “2024-12-06T21:18:24”, “date_modified”: “2024-12-12T13:38:27”, “time_date”: “1733875980”, “items”: [ { “id”: “item_1733836180047”, “content”: “new item yauers<br>”, “priority”: “none” }, { “id”: “item11”, “content”: “It’s working just like it should.”, “priority”: “none” } ], “keyboard_shortcut”: “Ctrl+A”, “active”: “1”, “checked_state_handling”: “per_user”, “theme”: “light”, “priority”: “none”, “enable_item_priority”: “0”, “trigger_shortcut”: “1”, “trigger_button”: “1”, “short_title”: “test”, “public_access”: “0”, “public_permission”: “interact”, “public_checked_state_handling”: “global”, “priority_display_type”: “color”, “enable_rate_limit”: “1”, “checked_state”: [], “_links”: { “self”: [ { “href”: “https://plugin-dev.local/wp-json/magicchecklists/v1/checklists/184” } ], “items”: [ { “href”: “https://plugin-dev.local/wp-json/magicchecklists/v1/checklists/184/items” } ], “checked-state”: [ { “href”: “https://plugin-dev.local/wp-json/magicchecklists/v1/checklists/184/checked-state” } ] } } | Successfully updated the specified checklist. Also returns all other settings. |
| { “success”: true, “items”: [ { “id”: “item11”, “content”: “It’s working just like it should.”, “priority”: “low” }, { “id”: “item12”, “content”: “fantastic mate!”, “priority”: “low” }, { “id”: “item13”, “content”: “maus ist toll”, “priority”: “high” }, { “id”: “item_1733836180047”, “content”: “new item yauers<br>”, “priority”: “none” } ] } | Successfully updated the list items. When the item number did not exist before, it now also created this item as a new item. |
| { “id”: 123, “checked_items”: [], “updated”: true } | Successfully updated the checked state of your list items. |
Request Body Parameters
You have access to all settings of a checklist. Just include the parameters in the body when creating checklists. Make sure to only use the expected parameters for each endpoint, or else the request will fail.
Good to know: You can also make a simple get request to retrieve a checklist, and just use the same parameters that the response is showing you.
| Parameter | What it means | Possible values |
|---|---|---|
| title | The title of the checklist. | String, any text or numbers |
| description | The description of the checklist. | String, any text or numbers |
| time_date | The deadline for the checklist. | Unix timestamp (example 1735686000) |
| items | The list items of the checklist. Is an array. Expects more parameters inside: id content priority (optional) | Array id: string (like item_1733836180047) content: string priority: none / low / medium / high / critical |
| theme | The theme (appearance) of the checklist. | light / dark |
| active | Whether or not the checklist should be activated. | 0 / 1 |
| tags | Array of tags for organisational purposes. Every tag also has a color associated. | Array name: string color: hexcode with # |
| checked_state_handling | How the checked states of list items should be handled. | per_user / global |
| priority | The priority level of the checklist | none / low / medium / high / critical |
| priority_display_type | Colored or numbered priorities. Only applies to list item priorities. | color / number |
| enable_item_priority | Whether or not to use priorities also on list items | 0 / 1 |
| trigger_shortcut | Whether or not a keyboard shortcut should be used to toggle the drawer. | 0 / 1 |
| trigger_button | Whether or not a floating button should be used to toggle the drawer. | 0 / 1 |
| keyboard_shortcut | The desired keyboard shortcut to toggle the checklist drawer | String, your shortcut in text. Example: Alt+A |
| short_title | A short title that is used inside the floating button (instead of the checklist title). If empty, the checklist title will be used. | String, any text or numbers |
| auto_reset | Whether or not auto reset should be enabled. | 0 / 1 |
| reset_interval | Set the interval in which the reset should happen. Use custom for a granular control over that. | daily / weekly / monthly / custom |
| reset_time | The exact time on which the reset should happen. | Expects a time in 24h format. Example: 14:00 |
| custom_days | Set the number of days for the reset to happen. | String, but only numbers. |
| custom_weeks | Set the number of weeks for the reset to happen. | String, but only numbers. |
| custom_months | Set the number of months for the reset to happen. | String, but only numbers. |
| public_access | Whether or not a checklist should be accessible by any website visitor, without restrictions. | 0 / 1 |
| public_permission | The level of permission for a public checklist. Choose carefully. | view / interact / edit |
| public_checked_state_handling | How the checked states of list items of public checklists should be handled. | per_user / global |
| enable_rate_limit | Whether or not you want to enable the rate limit for checklist actions, such as open / close drawer, check items, add new items etc. Can be helpful for public checklists. | 0 / 1 |
| access_roles | Set the user roles that should have access to the checklist. | Array WordPress user roles as string. Example: administrator, editor etc. |
| access_roles_permission | The level of permission for the user roles you’ve set earlier. | view / interact / edit |
| access_users | Set the individual users that should have access to checklist | Array ID of the user. Example: 1, 123 |
| access_users_permission | The level of permission for the individual users you’ve set earlier. | view / interact / edit |
| load_everywhere | Whether or not to enable the load everywhere condition. When enabled, the checklist will load anyhwere on the site. To have granular control over where the checklist should load, this needs to be turned off (0). | 0 / 1 |
| allowed_pages | An array of all the pages the checklist should load on. | Array String, URL slug. Example: dashboard, bricks-settings etc. |
| allowed_urls | An array of all the custom URLs the checklist should load on. Also allows URL patterns. | Array String, custom URL. Example: /category/*, https://magicplugins.io etc. |
| notification_settings | This parameter itself consists of a bigger array. We will present every inner parameter individually. But keep in mind, that all notification parameters have to be inside the array of notification_settings. | Array See below for what needs to be inside here. |
| notifications_enabled | Whether or not notifications should be enabled. | true / false |
| email_enabled | Whether or not email notifications should be sent. | true / false |
| integration_enabled | Whether or not notifications should be sent via an integration, like Slack or Discord for example. | true / false |
| email_recipients | Enter the email addresses you want the notifications to be sent to. | String, comma separated list. Example: hi@domain.com, service@domain.com |
| slack_webhook_url | Enter the slack webhook URL from your custom app channel. | URL |
| discord_webhook_url | Enter the discord webhook URL from your custom bot. | URL |
| notify_on_new_item | Whether or not the notification should be sent when a new item is created. | true / false |
| notify_on_delete_item | Whether or not the notification should be sent when an item is deleted. | true / false |
| notify_on_check_item | Whether or not the notification should be sent when an item is checked. | true / false |
| notify_on_uncheck_item | Whether or not the notification should be sent when an item is unchecked. | true / false |
| notify_on_deadline | Whether or not the notification should be sent when the deadline approaches. | true / false |
| deadline_threshold_hours | notify_on_deadline has to be enabled for this option to work. The amount of hours before the deadline end, which triggers the notification. | true / false |
| batch_interval | The schedule on which the notifications should be sent. | immediate / fifteen_minutes / hourly / daily |
Response Codes
| Response Body & Code | What it means |
|---|---|
| 200 | Success |
| 201 | Created successfully |
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Resource not found |
| 500 | Server error |
Rate Limiting
We have implemented a rate limting to the API of 120 actions (not requests) per minute. Keep in mind that one request can trigger multiple actions. For example checking or unchecking items will actually trigger 4 actions. This is due to the real-time nature of the plugin, triggering multiple methods at once to always show and save up-to-date data.
That’s it, you’re done! If you encounter any problems, hit us up at hello@magicplugins.io.