Getting started

Orpheus is the operating system for wedding bands. This is its API. Everything the office, the stage and the couple's side see runs through the same resources: gigs at the centre, the products sold on each gig (ceremony, cocktail hour, reception), the ensembles that fulfil them, and the staff who fill each role.

The base URL is your Orpheus deployment plus /api/v1; the hosted demo is https://api.hireorpheus.com/api/v1. Every request and response is JSON.

1. Get a token

# a sign-in link lands in your inbox
curl -X POST https://api.hireorpheus.com/api/v1/auth/link \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@yourband.com"}'

# the link carries a token; exchange it for a 30-day bearer
curl -X POST https://api.hireorpheus.com/api/v1/auth/confirm \
  -H 'Content-Type: application/json' \
  -d '{"token":"…"}'

{ "token": "…", "expires_at": "2026-10-30T09:19:34.840Z", "user": { "id": "…", "email": "you@yourband.com", "name": "You", "roles": ["administrator"] } }

For scripts and integrations, trade that session for a long-lived key. The key is shown once.

curl -X POST https://api.hireorpheus.com/api/v1/api-keys \
  -H 'Authorization: Bearer <session token>' \
  -H 'Content-Type: application/json' \
  -d '{"label":"calendar sync"}'

2. Ask who you are

curl https://api.hireorpheus.com/api/v1/me -H 'Authorization: Bearer <token>'

The answer lists your roles and which groups you can view or edit. See Authentication.

3. Pull this month's gigs

curl -G https://api.hireorpheus.com/api/v1/gigs \
  -H 'Authorization: Bearer <token>' \
  --data-urlencode 'filter[gig_status_id]=<status id>' \
  --data-urlencode 'filter[gig_date][on_or_after]=2026-11-01' \
  --data-urlencode 'filter[gig_date][before]=2026-12-01' \
  --data-urlencode 'sort=gig_date' \
  --data-urlencode 'fields=label,gig_date,start_time,venue_id'

{
  "data": [
    { "id": "…", "label": "Chen / Blake Wedding", "gig_date": "2026-11-14", "start_time": "18:00", "venue_id": "…" }
  ],
  "meta": { "total": 1, "limit": 50, "offset": 0 }
}

4. Book one

curl -X POST https://api.hireorpheus.com/api/v1/gigs \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"label":"Okafor / Ruiz Wedding","gig_status_id":"…","gig_type_id":"…","gig_date":"2027-03-06","start_time":"18:00","guest_count":150}'

A 201 comes back with the full record. From there: add products with POST /gigs/{id}/products, apply an ensemble to a product, invite people to the roles it created. The Gigs, products, ensembles page walks that path end to end.

Conventions

Keys are snake_case. Ids are UUIDs.
Single records: { "data": … }. Lists: { "data": [...], "meta": { "total", "limit", "offset" } }.
Dates are YYYY-MM-DD, times HH:MM in the venue's local time, timestamps ISO 8601 in UTC.
PATCH is partial. Unknown or read-only fields are rejected, never silently dropped.
DELETE is hard, and answers 409 while other records still point at the row.
Every error is one shape. See Errors.

Gigs, products, ensembles