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.0API 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 /loginRequest
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 /imagesUsers 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 /filesUsers 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 /eventsUsers 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 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-eventsUsers 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}/trashUsers 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
}Taxonomy Entities
These endpoints allow you to manage MEC taxonomy entities including categories, tags, labels, speakers, and sponsors.
Users must be authenticated for these commands. Both mec-token and user-token should be included in the headers.
List Taxonomy Entities
GET /taxonomies/{entity}Path Parameters:
| Parameter | Type | Description |
| entity | string | The entity type. One of: categories, tags, labels, speakers, sponsors |
Query Parameters:
| Parameter | Type | Default | Description |
| limit | int | 20 | Number of items per page |
| paged | int | 1 | Page number |
| orderby | string | name | Sort field. Options: name, slug, count, term_id |
| order | string | ASC | Sort order. Options: ASC, DESC |
| search | string | Search term to filter results | |
| hide_empty | boolean | false | Whether to hide empty terms |
Sample Response:
{
"data": {
"categories": [
{
"id": 1,
"name": "Music",
"slug": "music",
"description": "",
"count": 5,
"taxonomy": "mec_category",
"icon": "",
"color": "",
"fallback_image": "",
"parent": 0
}
],
"pagination": {
"current_page": 1,
"per_page": 20,
"total": 1,
"total_pages": 1
}
},
"status": 200
}Notes:
- For
categories, each item includesicon,color,fallback_image, andparentfields. - For
labels, each item includescolorandstylefields. - For
speakers, each item includestype,job_title,tel,email,website,mec_index,facebook,twitter,instagram,linkedin, andthumbnailfields. - For
sponsors, each item includeslinkandlogofields. - For
tags, only default term fields (id,name,slug,description,count,taxonomy) are returned. - Speakers and sponsors must be enabled in MEC settings to be accessible.
Get Single Taxonomy Entity
GET /taxonomies/{entity}/{id}Path Parameters:
| Parameter | Type | Description |
| entity | string | The entity type. One of: categories, tags, labels, speakers, sponsors |
| id | int | The term ID |
Sample Response (Category):
{
"data": {
"category": {
"id": 1,
"name": "Music",
"slug": "music",
"description": "",
"count": 5,
"taxonomy": "mec_category",
"icon": "",
"color": "#ff0000",
"fallback_image": "",
"parent": 0
}
},
"status": 200
}Sample Response (Speaker):
{
"data": {
"speaker": {
"id": 2,
"name": "John Doe",
"slug": "john-doe",
"description": "",
"count": 3,
"taxonomy": "mec_speaker",
"type": "person",
"job_title": "CEO",
"tel": "+1234567890",
"email": "[email protected]",
"website": "https://example.com",
"mec_index": "1",
"facebook": "https://facebook.com/johndoe",
"twitter": "https://twitter.com/johndoe",
"instagram": "",
"linkedin": "",
"thumbnail": ""
}
},
"status": 200
}Sample Response (Sponsor):
{
"data": {
"sponsor": {
"id": 3,
"name": "Acme Inc",
"slug": "acme-inc",
"description": "",
"count": 2,
"taxonomy": "mec_sponsor",
"link": "https://acme.com",
"logo": "https://example.com/logo.png"
}
},
"status": 200
}Sample Response (Label):
{
"data": {
"label": {
"id": 5,
"name": "Featured",
"slug": "featured",
"description": "",
"count": 12,
"taxonomy": "mec_label",
"color": "#ff0000",
"style": ""
}
},
"status": 200
}Sample Response (Tag):
{
"data": {
"tag": {
"id": 7,
"name": "Workshop",
"slug": "workshop",
"description": "Hands-on workshop sessions",
"count": 8,
"taxonomy": ""
}
},
"status": 200
}Create Taxonomy Entity
POST /taxonomies/{entity}Path Parameters:
| Parameter | Type | Description |
| entity | string | The entity type. One of: categories, tags, labels, speakers, sponsors |
Request Body:
Common parameters for all entity types:
| Parameter | Type | Required | Description |
| name | string | Yes | The entity name |
| slug | string | No | URL-friendly slug (auto-generated if omitted) |
| description | string | No | Description of the entity |
Entity-specific parameters:
For categories:
| Parameter | Type | Required | Description |
| parent | int | No | Parent category ID |
| icon | string | No | CSS class for the category icon |
| color | string | No | Hex color code (e.g., #ff0000) |
| fallback_image | string | No | URL for fallback image |
For labels:
| Parameter | Type | Required | Description |
| color | string | No | Hex color code for the label |
| style | string | No | Label style |
For speakers:
| Parameter | Type | Required | Description |
| type | string | No | person or group. Default: person |
| job_title | string | No | Job title of the speaker |
| tel | string | No | Telephone number |
| string | No | Email address | |
| website | string | No | Website URL |
| mec_index | int | No | Display order index. Default: 99 |
| string | No | Facebook profile URL | |
| string | No | Twitter profile URL | |
| string | No | Instagram profile URL | |
| string | No | LinkedIn profile URL | |
| thumbnail | string | No | Thumbnail image URL |
For sponsors:
| Parameter | Type | Required | Description |
| link | string | No | Sponsor website URL |
| logo | string | No | Sponsor logo image URL |
Sample Request (Category):
{
"name": "Conference",
"slug": "conference",
"description": "Conference events",
"color": "#3498db",
"icon": "mec-fa-video"
}Sample Request (Speaker):
{
"name": "Jane Smith",
"job_title": "Keynote Speaker",
"email": "[email protected]",
"type": "person",
"twitter": "https://twitter.com/janesmith"
}Sample Request (Sponsor):
{
"name": "Tech Corp",
"link": "https://techcorp.com",
"logo": "https://techcorp.com/logo.png"
}Sample Request (Label):
{
"name": "VIP",
"color": "#9b59b6",
"style": ""
}Sample Request (Tag):
{
"name": "Technology",
"description": "Technology-related events"
}Sample Response:
{
"data": {
"success": 1,
"category": {
"id": 10,
"name": "Conference",
"slug": "conference",
"description": "Conference events",
"count": 0,
"taxonomy": "mec_category",
"icon": "mec-fa-video",
"color": "#3498db",
"fallback_image": "",
"parent": 0
}
},
"status": 200
}Update Taxonomy Entity
PUT /taxonomies/{entity}/{id}Path Parameters:
| Parameter | Type | Description |
| entity | string | The entity type. One of: categories, tags, labels, speakers, sponsors |
| id | int | The term ID to update |
Request Body:
Same parameters as Create. Only include the fields you want to update.
Sample Request:
{
"name": "International Conference",
"color": "#e74c3c"
}Sample Response:
{
"data": {
"success": 1,
"category": {
"id": 10,
"name": "International Conference",
"slug": "conference",
"description": "Conference events",
"count": 0,
"taxonomy": "mec_category",
"icon": "mec-fa-video",
"color": "#e74c3c",
"fallback_image": "",
"parent": 0
}
},
"status": 200
}Delete Taxonomy Entity
DELETE /taxonomies/{entity}/{id}Path Parameters:
| Parameter | Type | Description |
| entity | string | The entity type. One of: categories, tags, labels, speakers, sponsors |
| id | int | The term ID to update |
Sample Response:
{
"data": {
"success": 1
},
"status": 200
}Error Responses
Entity not found (404):
{
"data": {
"code": "404",
"message": "Taxonomy entity not found!"
},
"status": 404
}Unauthorized (401):
{
"data": {
"code": "401",
"message": "You're not authorized to manage this taxonomy!"
},
"status": 401
}Validation error (400):
{
"data": {
"code": "400",
"message": "Name field is required!"
},
"status": 400
}Custom Fields
GET /config/custom-fieldsThis 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/iconsThis 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}/weatherThis 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
}
}Related Events
GET /events/{id}/related-eventsThis 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-eventsThis 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-occurrencesThis 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-fieldsThis 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-fieldsThis 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-variationsThis 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}/feesThis 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}/ticketsThis 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
}
}Report Out Dated Content
If you think the content of this page does not reflect updated information, please let us know.
2
3