REST API Guide
Events Manager has a REST API for events, locations, tickets, bookings, categories and tags. It is part of the free plugin and runs on the WordPress REST API, so it needs no setup beyond a user to authenticate as. Events Manager Pro adds routes of its own for coupons, transactions, booking forms, attendance and RSVP.
This page gets you to a working request and explains the parts that differ from the WordPress core API. For every endpoint, parameter and response field, use the generated endpoint reference.
You need a WordPress user with the capabilities for what you want to do, pretty permalinks enabled (so /wp-json/ resolves), and HTTPS on any site reachable from the internet.
Base URL and namespaces
All routes sit under your site's REST root, which is /wp-json/ on a standard install.
| Namespace | Plugin | Base URL |
|---|---|---|
events-manager/v1 | Events Manager | https://example.com/wp-json/events-manager/v1 |
events-manager-pro/v1 | Events Manager Pro Pro | https://example.com/wp-json/events-manager-pro/v1 |
The core resources are:
| Route | Methods | What it is |
|---|---|---|
/events | GET, POST | List or create events |
/events/{id} | GET, PATCH, DELETE | One event |
/events/{id}/availability | GET | Spaces left, per event and per ticket |
/events/{id}/tickets | GET, POST | An event's tickets |
/tickets/{id} | GET, PATCH, DELETE | One ticket |
/locations, /locations/{id} | GET, POST, PATCH, DELETE | Locations |
/locations/countries, /regions, /states, /towns | GET | The places your locations are in, for building filters |
/bookings | GET, POST | List or create bookings |
/bookings/{id} | GET, PATCH, DELETE | One booking |
/bookings/{id}/status | POST | Approve, reject or cancel a booking |
/categories, /tags and /{id} | GET, POST, PATCH, DELETE | Event categories and tags |
/media | POST | Upload an image to use as a featured image |
Updates use PATCH, and you send only the fields you want to change.
Authentication
Every route requires a logged-in user, including the ones that read public events. A request with no credentials gets a 401 response. There are three ways to authenticate.
Application passwords
This is the method to use for scripts and server-to-server integrations. Application passwords are a WordPress core feature.
-
Log in as the user the integration should act as, and go to Users then Profile.
-
Under Application Passwords, type a name for the integration and click Add New Application Password.
-
Copy the password shown. WordPress displays it once.
-
Send it with the username as HTTP Basic authentication on every request.
curl --user "apiuser:xxxx xxxx xxxx xxxx xxxx xxxx" \
https://example.com/wp-json/events-manager/v1/events
WordPress only offers application passwords over HTTPS, or on a site whose environment type is local. Create a dedicated user with the lowest role that covers the job, so that revoking the integration doesn't affect a person's account.
OAuth (Bearer tokens)
Events Manager includes an OAuth 2.0 server, built for connecting AI assistants. An access token it issues is sent as Authorization: Bearer <token> and works on the events-manager/v1 and events-manager-pro/v1 namespaces as well as the MCP endpoint. It is rejected with 403 on every other REST route. Setting up a client and the approval screen are covered in AI and MCP.
Cookie and nonce
JavaScript running in wp-admin or on the front end for a logged-in visitor can use the visitor's session. Send a REST nonce in the X-WP-Nonce header:
wp_localize_script( 'my-script', 'myEvents', array(
'root' => esc_url_raw( rest_url( 'events-manager/v1/' ) ),
'nonce' => wp_create_nonce( 'wp_rest' ),
) );
const response = await fetch( myEvents.root + 'events?scope=future', {
headers: { 'X-WP-Nonce': myEvents.nonce },
} );
const { items, pagination } = await response.json();
Without the nonce, WordPress treats a cookie-authenticated request as logged out.
List events
curl --user "apiuser:xxxx xxxx xxxx xxxx xxxx xxxx" \
"https://example.com/wp-json/events-manager/v1/events?scope=future&category=music&per_page=5"
The response has two keys, items and pagination:
{
"items": [
{
"name": "Harbor Lights Jazz Night",
"id": 42,
"type": "single",
"post_id": 118,
"slug": "harbor-lights-jazz-night",
"status": "publish",
"content": "...",
"bookings": { "enabled": true }
}
],
"pagination": { "total": 12, "total_pages": 3, "page": 1, "per_page": 5 }
}
The example is shortened. Each event also carries its dates and times, location, categories, tags and image.
The filters are a subset of the event search attributes used by shortcodes: search, scope, status, active_status, cancelled, active, category, tag, location, location_id, town, state, country, region, near, near_unit, near_distance, event_type, event_archetype, orderby, order, blog, private, private_only and timeslots.
By default a list contains published events only, and private events only if the user can read them. Add context=edit to include unpublished events. That takes effect only for a user with the edit_others_events capability.
The same request from PHP on another site:
$response = wp_remote_get(
add_query_arg( array( 'scope' => 'future', 'per_page' => 5 ), 'https://example.com/wp-json/events-manager/v1/events' ),
array(
'headers' => array(
'Authorization' => 'Basic ' . base64_encode( MY_EM_API_USER . ':' . MY_EM_API_PASSWORD ),
),
'timeout' => 15,
)
);
if ( is_wp_error( $response ) || wp_remote_retrieve_response_code( $response ) !== 200 ) {
return;
}
$data = json_decode( wp_remote_retrieve_body( $response ), true );
foreach ( $data['items'] as $event ) {
echo esc_html( $event['name'] ) . '<br />';
}
Define the two constants in wp-config.php. Don't put credentials in a theme or plugin file that is committed or shared.
Create an event
Send a JSON body to POST /events. Two fields are required: event_name and event_start_date.
curl --user "apiuser:xxxx xxxx xxxx xxxx xxxx xxxx" \
--header "Content-Type: application/json" \
--request POST \
--data '{
"event_name": "Sunrise Beach Yoga",
"event_start_date": "2027-06-12",
"event_start_time": "07:00",
"event_end_time": "08:00",
"content": "<p>Bring a mat and water.</p>",
"post_status": "publish"
}' \
https://example.com/wp-json/events-manager/v1/events
With wp_remote_post():
$response = wp_remote_post( 'https://example.com/wp-json/events-manager/v1/events', array(
'headers' => array(
'Authorization' => 'Basic ' . base64_encode( MY_EM_API_USER . ':' . MY_EM_API_PASSWORD ),
'Content-Type' => 'application/json',
),
'body' => wp_json_encode( array(
'event_name' => 'Sunrise Beach Yoga',
'event_start_date' => '2027-06-12',
'event_start_time' => '07:00',
'event_end_time' => '08:00',
'content' => '<p>Bring a mat and water.</p>',
'post_status' => 'publish',
) ),
'timeout' => 15,
) );
if ( wp_remote_retrieve_response_code( $response ) === 201 ) {
$event = json_decode( wp_remote_retrieve_body( $response ), true );
$event_id = $event['id'];
}
A successful create returns 201 and the saved event. Things to know:
- Field names match the event editor's form fields (
event_name,event_start_date,event_timezoneand so on), so the body is the same shape whether it comes from the form, the REST API or an AI tool. The reference lists them all, including tickets and recurrence rules. event_end_datedefaults to the start date.event_timezonedefaults to the site's timezone. Setevent_all_daytotruefor an all-day event.post_statuscan bepublish,pending,draftorprivate. A user without thepublish_eventscapability can't publish, and the event is saved as pending.- If a
featured_imagecan't be fetched, the event is still created and the response includes awarningsentry describing the problem. - To change the event later, send only the changed fields to
PATCH /events/{id}.
How ids work
Events and timeslots
An event's id in the API is its Events Manager event id, not its WordPress post id. The post id is returned separately as post_id. It is a number for an ordinary event. An event with timeslots is addressed as event_id:timeslot_id, which is a string:
| Id | Refers to |
|---|---|
42 | Event 42 |
42:7 | Timeslot 7 of event 42 |
Use the id exactly as the API returned it, in the URL and in request bodies. GET /events/42:7/availability returns the spaces left in that timeslot, and a booking for it sends "event_id": "42:7". Add timeslots=1 to an event list to get timeslots as separate items.
A booking's event_id field uses the same form, so a booking for a timeslot points back to the timeslot it was made for.
Bookings
A booking has a numeric id and a 32-character uuid. Either works wherever a booking id goes in a URL:
GET /wp-json/events-manager/v1/bookings/315
GET /wp-json/events-manager/v1/bookings/5f2c9a4e8b1d4c7fa3e6d0b9c8a7f6e5
Prefer the uuid in anything a customer can see, such as a link in an email, because it can't be guessed from another booking's number.
Create a booking
POST /bookings needs the event and the tickets, keyed by ticket id:
{
"event_id": 42,
"em_tickets": {
"96": { "spaces": 2 }
},
"booking_comment": "Window table if possible"
}
Get the ticket ids from GET /events/42/tickets. The booking belongs to the authenticated user and goes through the same validation as the booking form, so required form fields, ticket limits and availability all apply. With Events Manager Pro, a user who can manage the event's bookings can book on behalf of someone else by sending user_name and user_email. Pro
To change a booking's status, post the numeric status to /bookings/{id}/status:
curl --user "apiuser:xxxx xxxx xxxx xxxx xxxx xxxx" \
--header "Content-Type: application/json" \
--request POST \
--data '{ "status": 1, "send_email": true }' \
https://example.com/wp-json/events-manager/v1/bookings/315/status
| Status | Meaning |
|---|---|
0 | Pending |
1 | Approved |
2 | Rejected |
3 | Cancelled |
4 | Awaiting Online Payment |
5 | Awaiting Payment |
send_email defaults to true, which sends the same emails as changing the status in wp-admin.
Pagination
List routes take page and per_page. per_page defaults to 20 and is capped at 100. limit is accepted as another name for per_page.
The totals come back twice: in the pagination object of the body, and in the X-WP-Total and X-WP-TotalPages response headers that WordPress clients expect. To read everything, request pages until page equals total_pages.
Permissions
Authentication says who is asking. What they may do follows the same capabilities as wp-admin, checked for the route and then again for the specific item.
| Action | Capability needed |
|---|---|
| Read events, locations, tickets, categories, tags | Any logged-in user. Private and unpublished items need the matching read or edit capability. |
| Create or update events | edit_events, and edit_others_events for another user's event |
| Delete events | delete_events or delete_others_events |
| Create or update locations | edit_locations, and edit_others_locations for another user's location |
| Delete locations | delete_locations or delete_others_locations |
| Create, update or delete tickets | manage_bookings or manage_others_bookings, for that event |
| Read bookings | A user sees their own bookings. manage_bookings adds bookings for their own events, and manage_others_bookings adds all bookings. |
| Create a booking | Any logged-in user |
| Update or delete a booking, change its status | manage_bookings or manage_others_bookings, for that booking's event |
| Create or update categories and tags | edit_event_categories |
| Delete categories and tags | delete_event_categories |
| Upload media | upload_files |
Fields that only a booking manager may set, such as booking_status on a new booking, are dropped from requests by users without that capability. The request still succeeds.
Errors
Errors use the WordPress REST format: a machine-readable code, a message, and the HTTP status in data.status.
{
"code": "em_api_event_not_found",
"message": "Event not found.",
"data": { "status": 404 }
}
| Status | When | Example code |
|---|---|---|
400 | The data failed validation | em_api_event_invalid, em_api_booking_status_invalid |
401 | No valid credentials | rest_forbidden |
403 | Authenticated, but not allowed | em_api_event_forbidden, em_api_booking_forbidden |
404 | No item with that id | em_api_event_not_found, em_api_booking_not_found |
409 | The action conflicts with existing data | em_api_ticket_has_bookings |
500 | The save or delete failed | em_api_event_save_failed |
Validation errors also carry data.errors, a list with one message per problem, the same messages the form would show. Check code in your own code and show message to people.
Troubleshooting
Every request returns 401
Check that the request reaches WordPress with its Authorization header. Some Apache setups running PHP as CGI or FastCGI remove it. WordPress's own .htaccess rules pass it on, so re-save Settings then Permalinks to rewrite them. Then confirm the username is the login name, not the display name, and that the application password hasn't been revoked.
The Application Passwords section is missing from the profile
The site is not on HTTPS, or a security plugin has switched application passwords off.
A request returns 404 with "rest_no_route"
The path or the method is wrong. Updates use PATCH, not PUT. On a site without pretty permalinks, use https://example.com/?rest_route=/events-manager/v1/events.
An event I created doesn't appear in the list
It was probably saved as pending or draft. Lists contain published events unless you ask with context=edit as a user who can edit others' events. Request the event directly with GET /events/{id} to see its status.