Events API

The public v1 API exposes the full event lifecycle: create, list, get, update, publish, archive, restore. All endpoints require a Bearer token created in Admin → Settings → API Tokens.

For the OpenAPI spec, see /api/openapi.json on your instance — it’s the authoritative reference and is generated from the same route definitions.

Authentication


Authorization: Bearer <token>

See Authentication for token scopes and expiry.

Endpoints

Create event


curl -X POST "$API_URL/v1/events" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "wedding",
    "event_name": "Emily & Jordan Celebration",
    "event_date": "2026-06-07",
    "customer_name": "Emily Carter",
    "customer_email": "[email protected]",
    "customer_phone": "+49 30 12345678",
    "admin_email": "[email protected]",
    "require_password": true,
    "password": "Shutter123",
    "expiration_days": 45
  }'

Response (201):


{
  "id": 42,
  "slug": "wedding-emily-jordan-celebration-2026-06-07",
  "share_url": "https://picpeak.example.com/gallery/wedding-emily-jordan-celebration-2026-06-07/abc123",
  "share_token": "abc123"
}

Required fields:

Field	Type	Notes
`event_type`	string	One of the configured types (built-in or custom).
`event_name`	string	Display name.

Conditionally required fields — controlled by Event Defaults:

Field	Required when
`event_date`	`event_require_event_date` is on
`customer_name`	`event_require_customer_name` is on
`customer_email`	`event_require_customer_email` is on
`admin_email`	`event_require_admin_email` is on
`expiration_days`	`event_require_expiration` is on

Optional fields:

Field	Type	Default	Notes
`customer_phone`	string	(none)	Persisted only when `event_phone_field_enabled=true`. Max 32 chars.
`welcome_message`	string	(empty)	Markdown supported.
`require_password`	boolean	from `event_default_require_password`	When `false`, gallery is accessible via the share-link token alone.
`password`	string	(none)	Required when `require_password=true`. Min 6 chars, no all-numeric.
`expiration_days`	integer	from `general_default_expiration_days` (30)	Sets `expires_at = now + N days`. Range 1–365.
`photo_cap`	integer	`0` (unlimited)	Max number of photos.
`theme_preset`	string	from event-type recommendation	One of the bundled preset keys.
`header_style`	string	from theme preset	`hero` / `standard` / `minimal` / `none`
`is_draft`	boolean	`false`	When `true`, event is created as draft (not yet published, no `event.published` webhook).
`allow_user_uploads`	boolean	`false`	Enables guest uploads.
`upload_category_id`	integer	(none)	Required when `allow_user_uploads=true`.
`default_photo_sort`	string	`upload_date_desc`	Sort guests see first.

List events


curl "$API_URL/v1/events?limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"

Query parameters:

Param	Default	Notes
`limit`	`20`	Max 100.
`offset`	`0`	For pagination.
`is_archived`	(omit for all)	`true` / `false`.
`is_draft`	(omit for all)	`true` / `false`.
`event_type`	(omit for all)	Filter by type slug.

Get event


curl "$API_URL/v1/events/$EVENT_ID" \
  -H "Authorization: Bearer $TOKEN"

Returns the full event row plus aggregated stats (photo_count, total_size, total_views, total_downloads).

Update event


curl -X PATCH "$API_URL/v1/events/$EVENT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "expiration_days": 60, "welcome_message": "Updated copy." }'

Accepts any subset of the create-event fields. password change regenerates the share token.

Publish (draft → live)


curl -X POST "$API_URL/v1/events/$EVENT_ID/publish" \
  -H "Authorization: Bearer $TOKEN"

Flips is_draft=false. Fires the event.published webhook.

Restore from archive


curl -X POST "$API_URL/v1/events/$EVENT_ID/restore" \
  -H "Authorization: Bearer $TOKEN"

Delete


curl -X DELETE "$API_URL/v1/events/$EVENT_ID" \
  -H "Authorization: Bearer $TOKEN"

Hard delete: removes the event row, all associated photos, thumbnails, and feedback. Not recoverable.

Resend gallery email


curl -X POST "$API_URL/admin/events/$EVENT_ID/resend-email" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "password": "Shutter123" }'

Re-sends the gallery-created email to the customer. Omit password to send the no-credentials variant.

Field naming notes

The API uses customer_name, customer_email, customer_phone. Older deployments may have legacy host_name / host_email columns — migrations copy them on upgrade. Both names are accepted on input; output always uses the customer_* form.