JSON API

Off until you switch it on:

EVENTS_ROUTES=on

• Prefix events.routes.prefix (api), route names events.*, middleware events.routes.middleware (['api', 'throttle:events-api']); write routes add events.routes.auth_middleware (['auth']).
• A switch that is not set stays off — including a published config whose routes array lacks the key, since the merge is shallow.
• Publish --tag=events-routes to edit the route file: once routes/events.php exists in your app it loads instead of the package’s, and the switch still gates it.
• Writes always need a signed-in user. After your auth_middleware every write route runs the package’s own check: no signed-in user, or a guard user that is not an Eloquent model, is a 401 — even with auth_middleware = []. It runs before validation, so a guest never learns the shape of a request. Read routes and the invitation-link routes still allow guests.

Conventions

• {event} is the uuid — constrained, so /events/feed.ics never reaches it — and an event the caller may not see is a 404 exactly like a missing one, on every endpoint. {rsvp} and {tier} are scoped to the event (a ticket type by id or key); {venue} is numeric.
• Your models are referenced by alias, never by class name: {type: user, id: 42} in bodies and user:42 in paths and filters (events.organizers, events.attendees). In a body every failure — an unknown alias, a malformed key, a missing row — is the same 422 unknown_alias.
• Times in requests are wall clock in the event’s timezone or an ISO-8601 instant with an offset; responses use ISO-8601 with the event’s own offset.
• Text fields take a string (the current locale) or a locale map. Prices are decimal strings with an optional currency; responses render money-for-laravel’s MoneyResource — {minor, decimal, currency, exponent, formatted}, with minor a string and formatted for display only. A free ticket type renders price: null.
• Lists are Laravel length-aware paginators (data, links, current_page, per_page, total, …), with per_page capped at events.routes.max_per_page.

Routes

All 49 routes, grouped, with paths relative to the prefix. Rows marked “Guests too” also answer guests; every other route needs a signed-in user:

There is no payment-confirmation route: confirm from your provider’s webhook in PHP with Events::rsvps()->confirmPayment($reference).

Creating an event

{
  "title": { "en": "Jazz Night", "sk": "Jazzový večer" },
  "venue_id": 7,
  "starts_at": "2026-11-14 20:00",
  "duration": "PT3H",
  "capacity": 120,
  "max_guests": 1,
  "category": "jazz",
  "labels": ["Live", "Late night"],
  "tiers": [
    { "name": "Free entry", "key": "free" },
    { "name": "Supporter", "price": "15.00", "currency": "EUR", "capacity": 30 }
  ],
  "publish": true
}

PATCH /events/{event} changes only the fields sent, and null clears a nullable one; category (null clears) and labels (exactly these) apply in the same transaction. A new start on an announced event is refused — use POST /reschedule. ?notify=0, or notify: false in the body, writes silently.

Ticket types and venues

Ticket type bodies take name (required on create, ≤ 200), description (≤ 2000), key (≤ 64; derived from the name when omitted), price + currency, capacity, sale_starts_at, sale_ends_at, min_party (1–1000), max_party, hidden and position. Venue bodies take name (required on create), street, city, region, postal_code, country (2 letters), formatted_address, coordinates (lat,lng, [lat, lng] or {latitude, longitude}), timezone, capacity and geocode, and on create owner ({type, id}, who must allow the caller) or shared (admins and abilities.shared_venues only). Without owner or shared, a new venue is the caller’s own. On PATCH each address field changes on its own, and ownership never changes.

Your RSVP

PUT /api/events/{event}/rsvp with:

{ "response": "going", "tier": "free", "guests": 1, "note": "Wheelchair access" }

returns your own RSVP in the owner view, with your check-in code and the QR URL:

{
  "data": {
    "id": 42,
    "status": "going",
    "guests": 1,
    "party_size": 2,
    "tier": { "id": 1, "key": "free", "name": "Free entry" },
    "note": "Wheelchair access",
    "waitlist_position": null,
    "held_until": null,
    "amount": null,
    "checked_in_at": null,
    "checked_in_guests": null,
    "responded_at": "2026-11-02T18:12:40+01:00",
    "payment_url": null,
    "check_in_code": "EV1-…",
    "qr_url": "https://example.com/api/events/0195f2c4-7a1e-7c3b-9d2e-5b8a1f4c6e21/rsvp/qr.svg"
  }
}

The guest list

GET /events/{event}/attendees lists any status for managers (?status=, default going) with the check-in record — never codes — filtered by checked_in and tier. Everyone else who may view the list sees going attendees only, as {attendee, guests}: status=interested is a 403 for them, and status, checked_in and tier are ignored — the whole list, never one narrowed to who is at the venue or who holds a hidden ticket type.

Discovery: GET /events

Built on the model’s scopes, so PHP and HTTP filter identically; query-builder splits every value on commas. The base is browse($viewer) — visible, listed, announced:

An invalid filter value is a 422 invalid_query. A page loads venues and owners, organizers, tags, posters, ticket types, the viewer’s own RSVP, the category paths and which events the viewer manages in a fixed number of queries — the count does not grow with the page.

Resources

A free event, as a guest sees it in the list:

{
  "id": "0195f2c4-7a1e-7c3b-9d2e-5b8a1f4c6e21",
  "slug": "jazz-night",
  "title": "Jazz Night",
  "description": "A live quartet, then an open jam session.",
  "phase": "scheduled",
  "schema_status": "EventScheduled",
  "attendance_mode": "offline",
  "starts_at": "2026-11-14T20:00:00+01:00",
  "ends_at": "2026-11-14T23:00:00+01:00",
  "doors_open_at": null,
  "previous_starts_at": null,
  "all_day": false,
  "timezone": "Europe/Bratislava",
  "starts_on": "2026-11-14",
  "ends_on": "2026-11-14",
  "venue": {
    "id": 7,
    "name": "Blue Note",
    "slug": "blue-note",
    "address": {
      "street": "Hlavná 1", "city": "Bratislava", "region": null, "postal_code": "811 01",
      "country": "SK", "formatted": "Hlavná 1, 811 01 Bratislava, SK"
    },
    "coordinates": { "latitude": 48.1439, "longitude": 17.1097 },
    "timezone": "Europe/Bratislava",
    "capacity": null,
    "owner": null,
    "distance_km": null,
    "deleted": false
  },
  "online_url": null,
  "organizer": { "id": 1, "type": "User" },
  "category": { "id": 3, "slug": "jazz", "name": "Jazz", "color": null, "icon": null, "path": ["Music"] },
  "labels": [{ "id": 4, "slug": "live", "name": "Live", "color": null, "icon": null }],
  "poster": null,
  "tiers": [
    {
      "id": 1, "key": "free", "name": "Free entry", "description": null, "price": null, "free": true,
      "capacity": null, "seats_left": null, "on_sale": true, "sale_starts_at": null, "sale_ends_at": null,
      "min_party": 1, "max_party": null, "position": 1
    }
  ],
  "capacity": 120,
  "seats_left": 85,
  "counts": { "going": 35, "waitlisted": 0 },
  "viewer": { "rsvp": null },
  "links": {
    "self": "https://example.com/api/events/0195f2c4-7a1e-7c3b-9d2e-5b8a1f4c6e21",
    "ics": "https://example.com/api/events/0195f2c4-7a1e-7c3b-9d2e-5b8a1f4c6e21/calendar.ics",
    "url": "https://example.com/en/events/jazz-night"
  }
}

Reference resources

Every person or team a response mentions renders through its own resource — by default {id, type}, type being the model’s class basename (User), never a class name or a morph type, even without a morph map. A missing model renders null:

Point a key at your own JsonResource — it receives the model — to add a name or an avatar. Blank means the default; anything that is not an instantiable JsonResource subclass throws, naming the key. Lists eager-load the related models, so a resource that reads only their attributes adds no queries:

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

final class PersonResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return ['id' => $this->resource->getKey(), 'name' => $this->resource->name, 'avatar' => $this->resource->avatar_url];
    }
}

// config/events.php
'resources' => [
    'organizer' => App\Http\Resources\PersonResource::class,
    'host' => EventHostResource::class,
    'attendee' => App\Http\Resources\PersonResource::class,
    'invitee' => EventInviteeResource::class,
    'actor' => EventActorResource::class,
    'venue_owner' => VenueOwnerResource::class,
],

Errors

{message, code} with the package’s status — plus reason for check-in refusals, denials for a refused transition and errors for a validation 422. Messages are translated and never name a class, and your exception handler is never changed:

{ "message": "This code is for another event.", "code": "check_in_refused", "reason": "wrong_event" }

A tag of another scope answers tag_not_found, like a missing one. A poster media-library refuses, or an unknown or expired draft, is invalid_poster.

Rate limits

Defined only when the routes are on, per minute: