Articles on: Developer

MEC Restful API

The RESTful API in Modern Events Calendar allows developers to programmatically access, retrieve, and manage event data from external applications, websites, or services. It provides a structured and standardized way to interact with MEC data (such as events, locations, organizers, and schedules) without relying on the WordPress interface. This makes it suitable for integrations with mobile apps, third-party platforms, or custom front-end implementations.


Base URL


The base URL is different per website but the general pattern is like the following.


http://example.com/wp-json/mec/v1.0


API Key


The API key is required for all the following commands. You should send the API key in headers with the name of mec-token If you don’t send mec-token in headers then you will receive an invalid_api_token error.


All Events


GET    /events/


This is a public command, it means all users with an API key can run it.


Request


Send the following parameters as JSON.


Name

Type

Accepted Values

Example

limit

integer

12

order

string

ASC / DESC

ASC

offset

integer

0

start

string

today / date / tomorrow / yesterday/ start_last_month / start_current_month / start_next_month

date

start_date

string

(yyyy-mm-dd)

2024-12-15

show_only_past_events

integer

0,1

0

include_past_events

integer

0,1

0

show_only_ongoing_events

integer

0,1

0

include_ongoing_events

integer

0,1

0


Response


You will receive all events in the events key of the response. Events are categorized based on their start date so you can utilize that to display the events in any format you need like list view, monthly calendar view, weekly timetable view or anything else.


You can also use the pagination key of the response to read all events page by page. Just send the next_date value as start_date of your next request and send next_offset as the value of the offset parameter.


{
   "events": {
      "2025-01-15": [{ ... }],
	...
   },
   "pagination": {
       "next_date": "2025-12-15",
       "next_offset": 1,
       "has_more_events": true,
       "found": 12
   }
}


Single Event


GET    /events/{id}


This is a public command, it means all users with an API key can run it.


Request


Send the following parameters as a query string.


Name

Type

Example

id *

integer

1

occurrence

integer

1747335600


Response


You will receive a bunch of information included but not limited to the following. The data key has many useful information about the event that you can use in your application. The dates key has upcoming dates of the event. You can send the start timestamp value that you can see as an occurrence value in the query string to move forward in the time. Also the date key holds information about the current occurrence.


{
   "ID": 1,
   "data": { ... },
   "dates": [{
     "start": {
         "date": "2025-05-15",
         "hour": 7,
         "minutes": "0",
         "ampm": "PM",
         "timestamp": 1747335600
     },
     "end": {
         "date": "2025-05-15",
         "hour": 11,
         "minutes": "0",
         "ampm": "PM",
         "timestamp": 1747350000
     },
     "allday": "0",
     "hide_time": "0",
     "past": 0
   }],
   "date": {}
}


Login


POST    /login


Request


Send the following parameters as regular-form data.


Name

Type

Example

username *

string

user

password *

string

12345678


Response


Use the token to authorize users in other commands. You should send it as a new header named user-token for those commands that require authentication like my-events or trash events commands.


{
   "success": 1,
   "id": 1,
   "token": "W2X53XpClol8TquAIKWaZo0j68L0tuho3o4wmwD0"
}


Upload Image


POST    /images


Users must be authenticated for this command. Both mec-token and user-token should be included in the headers.


Request


Send following parameters as JSON.


Name

Type

Example

image *

file


Response


Use the image_id in other commands like creating events, etc.


{
    "success": 1,
    "image_id": 10
}


Upload File


POST    /files


Users must be authenticated for this command. Both mec-token and user-token should be included in the headers.


Request


Send the following parameters as JSON.


Name

Type

Example

file *

file


Response


Use the file_id in other commands like creating events, etc.


{
    "success": 1,
    "file_id": 10
}


Create Event


POST    /events


Users must be authenticated for this command. Both mec-token and user-token should be included in the headers.


Request


Send the following parameters as JSON.


Name

Type

Example

title *

string

Event Title

content

string

Event Content

location\[name\]

string

Art Gallery

location\[address\]

text

Art Gallery, City

location\[latitude\]

float

location\[longitude\]

float

location\[thumbnail\]

int

10

organizer\[name\]

string

John Due

organizer\[email\]

email

[\email protected\]

organizer\[tel\]

tel

+13007772299

organizer\[url\]

url

https://google.com

organizer\[thumbnail\]

number

10

start_date

date (yyyy-mm-dd)

2025-06-01

start_hour

int

10

start_minutes

int

15

start_ampm

string

AM

end_date

date (yyyy-mm-dd)

2025-06-01

end_hour

int

2

end_minutes

int

45

end_ampm

string

PM


Response


Use the event_id in other commands like get single event, etc.


{
    "success": 1,
    "message": "The event is published.",
    "event_id": 12
}


Edit Event


PUT    /events/{id}


Users must be authenticated for this command. Both mec-token and user-token should be included in the headers.


Request


The request is exactly like the create event command.


Response


The response is also exactly like the create event command.


My Events


GET    /my-events


Users must be authenticated for this command. Both mec-token and user-token should be included in the headers.


Request


Send the following parameters as JSON.


Name

Type

Example

limit *

integer

12

pages *

integer

1


Response


You can loop through the events to display all events. Use the pagination data to navigate through the pages of events.


{
   "events": [
       {
           "id": 2645,
           "title": "Monthly",
           "url": "http://example.com/events/monthly/",
           "status": "publish"
       }
   ],
   "pagination": {
       "current_page": 2,
       "total_pages": 5
   }
}


Trash Event


DELETE    /events/{id}/trash


Users must be authenticated for this command. Both mec-token and user-token should be included in the headers.


Request


None.


Response


If the command was successful you will receive the following response otherwise an error object with proper http code will be returned.


{
   "success": 1
}


Delete Event


DELETE    /events/{id}


Users must be authenticated for this command. Both mec-token and user-token should be included in the headers.


This command will force delete an event. It doesn’t matter if the event is already trashed or not.


Request


None.


Response


If the command was successful you will receive the following response otherwise an error object with proper http code will be returned.


{
   "success": 1
}


Custom Fields


GET    /config/custom-fields


This is a public command, it means all users with an API key can run it.


Request


None.


Response


If the command was successful you will receive the following response otherwise an error object with proper http code will be returned.


{
    "success": 1,
    "fields": {
        "1": {
            "mandatory": "1",
            "type": "text",
            "label": "Your Comment"
        },
        "2": {
            "mandatory": "0",
            "type": "date",
            "label": "Preferred Date"
        },
        "3": {
            "mandatory": "0",
            "ignore": "0",
            "type": "select",
            "label": "Gender",
            "options": {
                "1": {
                    "label": "Male"
                },
                "2": {
                    "label": "Female"
                }
            }
        }
    }
}


Icons


GET    /config/icons


This is a public command, it means all users with an API key can run it.


Request


None.


Response


If the command was successful you will receive the following response otherwise an error object with proper http code will be returned.


{
    "success": 1,
    "icons": [
        {
            "name": "Location Marker Icon",
            "default": "<i class=\"mec-sl-location-pin\"></i>",
            "modules": [
                "single",
                "shortcode"
            ],
            "value": "<img class=\"mec-custom-image-icon\" src=\"http://site.com/wp-content/uploads/2025/03/location.jpg\" alt=\"location-pin\">"
        }
    ]
}


Weather


GET    /events/{id}/weather


This is a public command, it means all users with an API key can run it.


Request


Send following parameters as query string.


Name

Type

Example

date

string

yyyy-mm-dd


Response


If the command was successful you will receive the following response otherwise an error object with proper http code will be returned.


{
    "success": 1,
    "weather": {
        "icon": "//cdn.weatherapi.com/weather/64x64/day/113.png",
        "condition": "Sunny",
        "temp_c": 13.699999999999999,
        "temp_f": 56.700000000000003,
        "wind_kph": 9,
        "wind_mph": 5.5999999999999996,
        "humidity": 58,
        "feelslike_c": 13.199999999999999,
        "feelslike_f": 55.799999999999997
    }
}



GET    /events/{id}/related-events


This is a public command, it means all users with an API key can run it.


Request


None.


Response


If the command was successful you will receive the following response otherwise an error object with proper http code will be returned.


{
    "success": 1,
    "related_events": [
        {
            "id": 21,
            "title": "Daily Event",
            "url": "http://site.com/events/daily-event/",
            "timestamp": 1746432000,
            "date": "May 5, 2025"
        }
    ]
}


Next / Previous Events


GET    /events/{id}/next-previous-events


This is a public command, it means all users with an API key can run it.


Request


None.


Response


If the command was successful you will receive the following response otherwise an error object with proper http code will be returned.


{
    "success": 1,
    "next": {
        "id": "21",
        "title": "Daily Event",
        "url": "http://rezamiri.test/events/daily-event/"
    },
    "previous": []
}


Next Occurrences


GET    /events/{id}/next-occurrences


This is a public command, it means all users with an API key can run it.


Request


None.


Response


If the command was successful you will receive the following response otherwise an error object with proper http code will be returned.


{
    "success": 1,
    "occurrences": [
        {
            "start": {
                "date": "2025-05-10",
                "hour": "8",
                "minutes": "0",
                "ampm": "AM",
                "timestamp": 1746864000
            },
            "end": {
                "date": "2025-05-10",
                "hour": 6,
                "minutes": "0",
                "ampm": "PM",
                "timestamp": 1746900000
            },
            "allday": "0",
            "hide_time": "0",
            "past": 0
        }
    ]
}


Attendee Fields


GET    /config/attendee-fields


This is a public command, it means all users with an API key can run it.


Request


None.


Response


If the command was successful you will receive the following response otherwise an error object with proper http code will be returned.


{
    "success": 1,
    "fields": [
        {
            "mandatory": "1",
            "type": "mec_email",
            "label": "Email"
        },
        {
            "mandatory": "1",
            "type": "name",
            "label": "Name"
        },
        {
            "mandatory": "0",
            "type": "textarea",
            "label": "Text",
            "mapping": ""
        }
    ]
}


Fixed Fields


GET    /config/fixed-fields


This is a public command, it means all users with an API key can run it.


Request


None.


Response


If the command was successful you will receive the following response otherwise an error object with proper http code will be returned.


{
    "success": 1,
    "fields": {
        "1": {
            "mandatory": "0",
            "type": "text",
            "label": "Text"
        },
        "2": {
            "mandatory": "1",
            "type": "date",
            "label": "Date"
        }
    }
}


Ticket Variations


GET    /config/ticket-variations


This is a public command, it means all users with an API key can run it.


Request


None.


Response


If the command was successful you will receive the following response otherwise an error object with proper http code will be returned.


{
    "success": 1,
    "ticket_variations": {
        "1": {
            "title": "Pizza",
            "price": "6",
            "max": "2"
        },
        "2": {
            "title": "Juice",
            "price": "4",
            "max": "3"
        }
    }
}


Booking Tax / Fees


GET    /events/{id}/fees


This is a public command, it means all users with an API key can run it.


Request


None.


Response


If the command was successful you will receive the following response otherwise an error object with proper http code will be returned.


{
    "success": 1,
    "fees": {
        "1": {
            "title": "Tax",
            "amount": "12",
            "type": "percent"
        },
        "2": {
            "title": "Deposit",
            "amount": "50",
            "type": "amount_per_booking"
        }
    }
}


Tickets


GET    /events/{id}/tickets


This is a public command, it means all users with an API key can run it.


Request


Name

Type

Example

occurrence

string

yyyy-mm-dd hh:mm:ss


Response


If the command was successful you will receive the following response otherwise an error object with proper http code will be returned.


{
    "success": 1,
    "tickets": {
        "1": {
            "name": "Ticket A",
            "ticket_start_time_hour": "08",
            "ticket_start_time_minute": "0",
            "ticket_end_time_hour": "06",
            "ticket_end_time_minute": "0",
            "description": "",
            "private_description": "",
            "price": "8.97",
            "price_label": "$8.97",
            "limit": "",
            "unlimited": "0",
            "seats": "1",
            "minimum_ticket": "1",
            "maximum_ticket": "",
            "stop_selling_value": "0",
            "stop_selling_type": "day",
            "dates": [],
            "ticket_start_time_ampm": "AM",
            "ticket_end_time_ampm": "PM",
            "category_ids": [],
            "id": 1,
            "variations": {
                "1": {
                    "title": "Pizza",
                    "price": "6",
                    "max": "2"
                },
                "2": {
                    "title": "Juice",
                    "price": "4",
                    "max": "3"
                }
            }
        }
    },
    "availability": {
        "1": 100,
        "seats_1": 1,
        "total": 100
    }
}

Updated on: 01/02/2026

Was this article helpful?

Share your feedback

Cancel

Thank you!