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

john.due@gmail.com

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
}


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 includes icon, color, fallback_image, and parent fields.
  • For labels, each item includes color and style fields.
  • For speakers, each item includes type, job_title, tel, email, website, mec_index, facebook, twitter, instagram, linkedin, and thumbnail fields.
  • For sponsors, each item includes link and logo fields.
  • 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": "john@example.com",
            "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

email

string

No

Email address

website

string

No

Website URL

mec_index

int

No

Display order index. Default: 99

facebook

string

No

Facebook profile URL

twitter

string

No

Twitter profile URL

instagram

string

No

Instagram profile URL

linkedin

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": "jane@example.com",
    "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-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: 21/06/2026

Was this article helpful?

Share your feedback

Cancel

Thank you!