The “REST” part means that the state of each transaction between a client and the server is wholly contained in the response the client receives. HTTP protocol-based communications are the domain where REST APIs live, and they make full use of HTTP methods:<\/p>\n\n\n\n
- \n
GET<\/code> \u2014 retrieve data from the server<\/li>\n\n\n\nPOST<\/code> \u2014 send new data to the server (create)<\/li>\n\n\n\nPUT<\/code> \/PATCH<\/code> \u2014 update existing data on the server<\/li>\n\n\n\nDELETE<\/code> \u2014 remove data from the server<\/li>\n<\/ul>\n\n\n\nAlmost any REST API \u2014 including WordPress and The Events Calendar \u2014 uses authorization to allow or restrict what a user can do.
GET<\/code> requests are often public; operations that create, update, or delete data typically require authentication. HTTP response codes tell you what happened:200<\/code> means success,404<\/code> means not found,403<\/code> means not authorized,500<\/code> means a server error occurred. See the full list of HTTP status codes<\/a> for reference.<\/p>\n\n\n\nFor more background on the WordPress REST API specifically:<\/p>\n\n\n\n
- \n
- REST API Handbook<\/a><\/li>\n\n\n\n
- Endpoints<\/a><\/li>\n\n\n\n
- Beginner Guide<\/a><\/li>\n<\/ul>\n\n\n\n
The Events Calendar REST API<\/h2>\n\n\n\n
We built The Events Calendar REST API to allow our users and ourselves to consume and manage events from anywhere<\/strong>. In its most basic form, a REST API separates the content from its presentation, freeing developers and users from the constraints of a WordPress site and a WordPress theme. Some examples of what this enables:<\/p>\n\n\n\n
- \n
- Themes can access events, venues, and organizers’ data without using plugin PHP functions \u2014 developers can present that data in any way they want.<\/li>\n\n\n\n
- Sites not using PHP or WordPress can use a WordPress installation as a CMS to manage events while the front-end is maintained in a different language or framework.<\/li>\n\n\n\n
- Android, iOS, and other mobile developers can use a WordPress backend to manage events and present the same information across different platforms.<\/li>\n\n\n\n
- External applications and services can create, update, or sync events directly into your site programmatically.<\/li>\n<\/ul>\n\n\n\n
Since The Events Calendar REST API is built on top of the WordPress REST API<\/a>, it inherits its code, robustness, and security.<\/p>\n\n\n\n
The Events Calendar REST API is free and bundled with The Events Calendar plugin. It requires WordPress 4.5 or above. Once you have installed and activated The Events Calendar, you are ready to get started.<\/p>\n\n\n\n
Endpoints and Base URL<\/h2>\n\n\n\n
All TEC REST API calls follow the same URL structure. For events:<\/p>\n\n\n
\n[your-site-URL]\/wp-json\/tribe\/events\/v1\/{endpoint}\n<\/pre><\/div>\n\n\nBreaking this down:<\/p>\n\n\n\n
- \n
[your-site-URL]\/<\/code> \u2014 the server you are making the request to<\/li>\n\n\n\n\/wp-json\/tribe\/events\/v1<\/code> \u2014\/wp-json<\/code> is the WordPress Core REST API prefix;\/tribe\/events\/v1<\/code> identifies The Events Calendar plugin and API version<\/li>\n\n\n\n\/{endpoint}<\/code> \u2014 optional, adds specificity to what the call returns (e.g.\/events<\/code>,\/events\/6<\/code>,\/venues<\/code>)<\/li>\n<\/ul>\n\n\n\nTo access the tickets API instead of events, switch
\/events<\/code> for\/tickets<\/code>:<\/p>\n\n\n\n[your-site-URL]\/wp-json\/tribe\/tickets\/v1\/{endpoint}\n<\/pre><\/div>\n\n\nFor the full list of available endpoints for both events and tickets, see the REST API endpoints documentation<\/a>. You can also explore all available endpoints on your own site by visiting
\/wp-json\/tribe\/events\/v1\/doc<\/code> \u2014 more on this in the Self-Documenting API Reference<\/a> section below.<\/p>\n\n\n\nExample GET Requests<\/h4>\n\n\n\n
The simplest request is a
GET<\/code> to return all events. You can test this by pasting the URL directly into your browser:<\/p>\n\n\n\nGET https:\/\/demo.theeventscalendar.com\/wp-json\/tribe\/events\/v1\/events\n<\/pre><\/div>\n\n\n
This returns a JSON response that looks like this (truncated for brevity):<\/p>\n\n\n
\n{\n "events": [\n {\n "id": 1762,\n "global_id": "demo.theeventscalendar.com?id=1762",\n "author": "2",\n "status": "publish",\n "date": "2022-12-01 12:36:40",\n "url": "https:\/\/demo.theeventscalendar.com\/event\/hosted-dinner-with-chef-monica-geller\/",\n "rest_url": "https:\/\/demo.theeventscalendar.com\/wp-json\/tribe\/events\/v1\/events\/1762",\n "title": "Hosted Dinner with Chef Monica Geller",\n "description": "<p>Join Chef Monica Geller for a Hosted Dinner!<\/p>",\n "all_day": false,\n "start_date": "2017-09-21 08:00:00",\n "end_date": "2017-09-21 17:00:00",\n "timezone": "UTC+0",\n "cost": "$5",\n "categories": [...],\n "tags": [...],\n "venue": {...},\n "organizer": [...]\n }\n ],\n "rest_url": "...",\n "total": 1,\n "total_pages": 1\n}\n<\/pre><\/div>\n\n\nTo return a single event, pass its post ID as a path parameter:<\/p>\n\n\n
\nGET https:\/\/demo.theeventscalendar.com\/wp-json\/tribe\/events\/v1\/events\/1762\n<\/pre><\/div>\n\n\n
Many of the WordPress and TEC REST API parameters share names with those used in
WP_Query<\/code><\/a>. You can use standard query parameters to filter results \u2014 for example,per_page<\/code> andpage<\/code> for pagination:<\/p>\n\n\n\nGET https:\/\/demo.theeventscalendar.com\/wp-json\/tribe\/events\/v1\/events?per_page=2&page=2\n<\/pre><\/div>\n\n\n
Query Parameter Example: Tickets<\/h4>\n\n\n\n
The same approach works for the tickets endpoint. For example, to return only tickets that have Individual Attendee Collection enabled:<\/p>\n\n\n
\nGET https:\/\/demo.theeventscalendar.com\/wp-json\/tribe\/tickets\/v1\/tickets?attendee_information_available=true\n<\/pre><\/div>\n\n\n
\ud83d\udc4b You may notice that the
attendees<\/code> attribute for each ticket returns as an empty array even when you know attendees exist. This is because attendee data requires authentication to retrieve \u2014 see the Authentication<\/a> section below.<\/p>\n\n\n\nAuthentication<\/h2>\n\n\n\n
Some REST API requests require authentication to return data. For example, this endpoint is valid:<\/p>\n\n\n
\nGET https:\/\/demo.theeventscalendar.com\/wp-json\/tribe\/tickets\/v1\/attendees\n<\/pre><\/div>\n\n\n
But without authentication, a site with attendees will still return:<\/p>\n\n\n
\n{\n "rest_url": "https:\/\/demo.theeventscalendar.com\/wp-json\/tribe\/tickets\/v1\/attendees\/",\n "total": 0,\n "total_pages": 0,\n "attendees": []\n}\n<\/pre><\/div>\n\n\nSince our REST API is built on top of the WordPress API, the same authentication practices<\/a> are baked in. This ensures that sensitive information \u2014 such as attendees’ personal data \u2014 remains protected. Regardless of which method you choose, you are setting up a secret token that grants access to otherwise protected information or actions.<\/p>\n\n\n\n
Authentication Methods<\/h4>\n\n\n\n
Three options are available:<\/p>\n\n\n\n
- \n
- Basic Auth plugin<\/a><\/strong> \u2014 Recommended for simple authentication. Allows you to use your WordPress admin credentials for API requests.<\/li>\n\n\n\n
- JWT Authentication plugin<\/a><\/strong> \u2014 For more advanced JSON Web Token authentication.<\/li>\n\n\n\n
- Nonce Authentication<\/strong> \u2014 Create a nonce using
wp_create_nonce()<\/code> with the action set to'wp_rest'<\/code>. More technical to set up, but very versatile and built into WordPress.<\/li>\n<\/ol>\n\n\n\nMaking a Request with cURL (Basic Auth)<\/h4>\n\n\n\n
With the Basic Auth plugin installed and activated, you can authenticate a
GET<\/code> request using cURL by passing your WordPress username and password with the--user<\/code> flag:<\/p>\n\n\n\ncurl --user user:pass -X GET \\\n -H "Content-Type: application\/json" \\\n https:\/\/www.yoursite.url\/wp-json\/tribe\/tickets\/v1\/attendees\n<\/pre><\/div>\n\n\n
An authenticated response with one attendee looks like this:<\/p>\n\n\n
\n{\n "rest_url": "https:\/\/stable.dev.lndo.site\/wp-json\/tribe\/tickets\/v1\/attendees\/",\n "total": 1,\n "total_pages": 1,\n "attendees": [\n {\n "id": 33,\n "post_id": 29,\n "ticket_id": 30,\n "title": "Steve Harvey",\n "email": "steve@example.com",\n "checked_in": false,\n "ticket": {\n "id": "30",\n "title": "Entree",\n "raw_price": 20,\n "formatted_price": "20.00",\n "start_sale": "2024-06-01",\n "end_sale": "2024-07-01"\n },\n "payment": {\n "provider": "woo",\n "price": 20,\n "currency": "$",\n "date": "2024-06-06 15:36:16"\n }\n }\n ]\n}\n<\/pre><\/div>\n\n\nMaking a Request with AJAX (Nonce)<\/h4>\n\n\n\n
For front-end JavaScript usage, nonce authentication is the standard WordPress approach. In your PHP where the script is enqueued<\/a>, pass the nonce as a localized variable using
wp_localize_script()<\/code><\/a>:<\/p>\n\n\n\n\/\/ Localize the script with the nonce\nwp_localize_script( 'handle-of-script', 'localized_script_variables', array(\n 'ajax_url' => admin_url( 'admin-ajax.php' ),\n 'rest_endpoint' => '\/wp-json\/tribe\/tickets\/v1\/attendees\/',\n 'nonce' => wp_create_nonce( 'wp_rest' ),\n) );\n<\/pre><\/div>\n\n\n
Then in your JavaScript file, set the
X-WP-Nonce<\/code> header on the request:<\/p>\n\n\n\n$.ajax({\n url: localized_script_variables.ajax_url,\n type: 'GET',\n dataType: 'json',\n headers: {\n 'X-WP-Nonce': localized_script_variables.nonce,\n },\n success: renderAttendees\n});\n<\/pre><\/div>\n\n\nYou can test that authentication is working by triggering the AJAX call as a logged-in user versus in an incognito window.<\/p>\n\n\n\n
Authentication in a Theme: Full JavaScript Example<\/h4>\n\n\n\n
The following is a complete example of cookie-based nonce authentication used in a child theme to fetch and display events via the REST API. In
functions.php<\/code>, enqueue your script and localize the REST API root URL and nonce:<\/p>\n\n\n\n\/\/ file functions.php\n\nadd_action( 'wp_enqueue_scripts', 'twentyseventeen_parent_theme_enqueue_styles' );\n\nfunction twentyseventeen_parent_theme_enqueue_styles() {\n wp_enqueue_style( 'twentyseventeen-style', get_template_directory_uri() . '\/style.css' );\n wp_enqueue_style( 'rest-style',\n get_stylesheet_directory_uri() . '\/style.css',\n array( 'twentyseventeen-style' )\n );\n\n \/\/ Enqueue the theme script...\n wp_enqueue_script( 'rest-theme-js', get_stylesheet_directory_uri() . '\/js\/rest-theme.js', array( 'jquery' ) );\n\n \/\/ ...and localize The Events Calendar REST API root URL and nonce\n wp_localize_script( 'rest-theme-js', 'restTheme',\n array(\n 'root' => esc_url_raw( tribe_events_rest_url() ),\n 'nonce' => wp_create_nonce( 'wp_rest' )\n )\n );\n}\n<\/pre><\/div>\n\n\nIn
\/js\/rest-theme.js<\/code>, fetch and render the next 3 upcoming events when the page loads:<\/p>\n\n\n\n( function( $ ) {\n if ( undefined === restTheme ) {\n return;\n }\n\n var renderEvents = function( response ) {\n var eventsNode;\n\n if ( response.events.length > 0 ) {\n eventsNode = $( '<ul>' );\n for ( var event of response.events ) {\n var eventNode = $( '<li>' );\n eventNode.text( event.title );\n eventNode.appendTo( eventsNode );\n }\n } else {\n eventsNode = $( '<p>' );\n eventsNode.text( 'No upcoming events found!' );\n }\n\n eventsNode.appendTo( $( '#rest-events' ) );\n };\n\n var showEvents = function() {\n $.ajax( {\n url: restTheme.root + 'events',\n method: 'GET',\n beforeSend: function( xhr ) {\n xhr.setRequestHeader( 'X-WP-Nonce', restTheme.nonce );\n },\n data: { 'page': 1, 'per_page': 3 }\n } ).done( renderEvents );\n };\n\n $( document ).ready( function() { showEvents(); } );\n} )( jQuery );\n<\/pre><\/div>\n\n\nBy default, visitors and subscribers see only public events. Users with the
edit_posts<\/code> capability (Editor, Administrator) will also see private and draft events \u2014 this is true for any authentication method, not just cookie-based.<\/p>\n\n\n\nCreating Events via POST<\/h2>\n\n\n\n
The REST API supports creating new events by sending a
POST<\/code> request to the events endpoint. Because you are modifying data on the server, this operation requires authentication and appropriate user permissions (Editor or Administrator role).<\/p>\n\n\n\nThe examples below use Application Passwords<\/a> for authentication. Application Passwords authenticate REST requests without exposing your main login password \u2014 they are per-user, revocable, and designed for use over HTTPS. If you prefer a different method, you can adapt the examples to use Cookie\/Nonce<\/a> authentication instead.<\/p>\n\n\n\n
Prerequisites<\/h4>\n\n\n\n
- \n
- WordPress 5.6 or above<\/li>\n\n\n\n
- Site served over HTTPS (or a local development environment). Note: some hosts or security plugins may disable this feature.<\/li>\n<\/ul>\n\n\n\n
Generate an Application Password<\/h4>\n\n\n\n
- \n
- Log in to your WordPress dashboard with an Editor or Administrator account.<\/li>\n\n\n\n
- Go to Users \u2192 Profile<\/strong>.<\/li>\n\n\n\n
- Scroll to Application Passwords<\/strong>.<\/li>\n\n\n\n
- Enter a descriptive name (e.g. “My Script” or “Zapier”) and click Add Application Password<\/strong>.<\/li>\n\n\n\n
- Copy the generated password now<\/strong> \u2014 you will not see it again. You can revoke it at any time from the same screen.<\/li>\n<\/ol>\n\n\n\n
POST Endpoint Reference<\/h4>\n\n\n\n
- Scroll to Application Passwords<\/strong>.<\/li>\n\n\n\n
- JWT Authentication plugin<\/a><\/strong> \u2014 For more advanced JSON Web Token authentication.<\/li>\n\n\n\n
- Endpoints<\/a><\/li>\n\n\n\n
![\"\"](\"https:\/\/images.theeventscalendar.com\/kb\/uploads\/2024\/10\/CleanShot-2024-10-23-at-17.01.45@2x-1024x357.png\")
<\/figure>\n\n\n\n