Hype5 Docs

Hype5 Theater 0.7.0 · Beta — by invitation

REST API

On this page

Hype5 Theater offers three public, read-only REST routes under the namespace hype5-theater/v1, and adjusts some core WordPress REST routes so that they follow the plugin's visibility rules. The routes under hype5-theater/v1/app/ are the private API of the Hype5 app: they require a logged-in user with access to the app, may change in any release and are not a public contract.

All public routes are GET, need no authentication and return JSON. Paths below are relative to the REST root, for example https://example.com/wp-json/hype5-theater/v1/productions.

GET /hype5-theater/v1/productions

Published productions, in WordPress's default order (newest first).

Parameter Default Notes
per_page 12 Clamped to 1–100.

Each item:

Field Type Notes
id integer
title string WordPress title; for a password-protected production it carries WordPress's Protected: prefix.
url string Permalink.
excerpt string Teaser, or the WordPress excerpt; empty unless the production is public to everyone (Theater 0.7.0: also after a password was entered, and for a translation whose original is unpublished, so the list never depends on the visitor's password). Before 0.7.0: empty while this visitor must enter a password for the production or another language version of it.
premiere string Premiere date as stored (YYYY-MM-DD) or empty.
protected boolean true when the production, its original-language version or its reader's-language version has a password.
status string Repertory status: coming, playing, paused, archived (empty storage is reported as playing).
elab_id integer ELAB identifier, or 0.
elab_url string ELAB link, or empty.

GET /hype5-theater/v1/performances

Upcoming performances, earliest first.

Parameter Default Notes
per_page 20 Clamped to 1–100.
production 0 Production ID.

Without production, only performances of productions that are public to everyone are returned: published without a password, both in the original language and in the reader's language. With production, the list is empty when the production is not published or when this visitor still has to enter its password (on any language version); a visitor who has entered the password (WordPress's password cookie) receives the performances. Answers filtered to a production with a password carry no-cache headers (Theater 0.7.0), as do credits answers for such a production.

Each item:

Field Type Notes
id, production_id integer production_id is the original-language production.
production, production_url string Title and link in the reader's language when that version is published.
venue string or null Venue title; null when there is no venue or it is not published.
starts_at_utc, ends_at_utc string or null ISO 8601 in UTC, for example 2026-11-14T17:00:00Z; ends_at_utc may be null.
timezone string The performance's own time zone (IANA name or offset).
status string scheduled, sold_out, cancelled or postponed. Cancelled and postponed future performances are included.
room string
ticket_url string URL of the first ticket offer, or empty (kept for older clients).
ticket_offers array Each offer: provider, label, url, price_min, price_max, currency, availability (available, sold_out, closed, unknown), note, sort_order.

Internal notes and attendance are never included. A client should apply its own purchase rule; the plugin shows a purchase link only for a future, scheduled performance whose offer has a URL and availability available or unknown.

GET /hype5-theater/v1/productions/{id}/credits

Public credits of a published production, in editor order.

Response When
404 hype5t_not_found The ID is not a published production, or its original-language production (which owns the credits) is not published.
401 hype5t_password_required This visitor must enter a password for the production, its original-language version or its reader's-language version.

Each item:

Field Type Notes
id integer Credit row ID.
person_id integer or null null for a name without a profile.
person string Display name. Credits whose profile is not published are left out.
person_url string or null null when the profile page is not allowed or there is no profile.
role string The job.
character string
group string cast, creative, production, technical, thanks (or a legacy value).
alternate_group string or null Rows with the same value form an alternating set.

Hidden credits are never returned.

Core WordPress routes

The post types hype5t_production, hype5t_person and hype5t_venue and the taxonomies hype5t_genre, hype5t_audience, hype5t_warning and hype5t_profession are registered with show_in_rest, so the core routes /wp/v2/hype5t_production and so on exist. The plugin changes them as follows:

  • People with a hidden profile are left out of /wp/v2/hype5t_person for users who cannot edit people, and a single request for one returns 404 hype5t_profile_hidden unless the user can edit it.
  • Sitemaps leave out people with a hidden profile, and so do /wp/v2/search, site search and feeds (also translations of a hidden original).
  • Registered meta. The Hype5 post types do not declare custom-fields support, so core responses carry no meta object. If a site adds that support, the plugin masks values for users who cannot edit the production: the premiere venue is reported only while that venue is published, and a password-protected production's Hype5 values are emptied except premiere, repertory status and ELAB identifiers, unless the request carries the right password parameter.

WordPress itself protects the content and excerpt of password-protected posts in core responses. For productions the plugin extends that rule to every language version in the chain and, since Theater 0.7.0, keeps them protected in core REST answers also for a visitor who entered the password on the production's page (such answers never depend on the password cookie, so they stay cacheable); core's own password parameter still opens a post's own password — only that: a translation protected through its original's password cannot be opened through core REST (use the plugin routes, or the production's page). Requests outside the production's own page never use the password cookie — also core REST or AJAX requests the production's page makes from the browser. A schedule held in a page's content is not scoped by a hype5_production URL parameter inside a REST request, so content.rendered never depends on the cookie either. content.protected / excerpt.protected are true for every version with a password in its chain. A published translation whose original-language production is unpublished returns empty content and excerpt to users who may not read the original. Search (?search=, /wp/v2/search) follows the same rules as WordPress's site search: visitors who are not logged in do not find any version of a production with a password in its chain.

Private app routes

/hype5-theater/v1/app/* serves the Hype5 app: productions, credits, people, performances, venues, appearance, vocabularies, settings and the overview. Every route requires a logged-in user with a Hype5 Theater administration capability (the app is on and hype5_theater_fuajee_enabled does not switch it off) and the same capability as the corresponding classic screen; answers are not cached. These routes are an implementation detail of the app. Do not build integrations on them.