API Quickstart

First call against the go~mus REST API in five minutes - auth, whoami, version check and a paginated index.

This page takes you from "nothing yet" to "first API response read" in five minutes. Deeper relationships are explained in Concepts and the Scenarios.

Prerequisites

  • A go~mus instance to talk to. Examples here use demo.gomus.de. Your real instance follows the pattern <instance>.gomus.<tld>, where <tld> can be de, at, ch, be or lu depending on country.
  • An API token. Tokens are issued by go~mus support or from your backend if configured. Tokens are context-sensitive: Public, User, Reseller. More under Authentication.
  • curl or your HTTP tool of choice.

Step 1: Check the version

The current API version is exposed at /api/v4/version. No auth needed.

curl https://demo.gomus.de/api/v4/version

Response (truncated):

{
  "version": {
    "system": "4.2.15.0",
    "api": "4.5.0",
    "release": "J. Fred Muggs",
    "instance": "demo.gomus.de",
    "time": "2026-05-05T06:32:55+02:00",
    "zone": "Europe/Berlin",
    "currency": "EUR",
    "per_page": 25
  }
}

version.api is the API version (for client-side feature detection). per_page is the default page size for paginated indexes on this instance and may vary per instance.

Step 2: Test your token

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://demo.gomus.de/api/v4/whoami

Response looks roughly like:

{
  "access": "user",
  "museums": []
}

access shows your role. museums: [] means all museums on this instance are visible. A specific list narrows the scope.

Step 3: A paginated index

Fetch the list of tickets:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://demo.gomus.de/api/v4/tickets?page=1"

The response contains the tickets plus a meta object:

{
  "tickets": [ ... ],
  "meta": {
    "total_count": 42,
    "page": 1,
    "per_page": 25
  }
}

With total_count and per_page you compute the total number of pages without guessing.

Step 4: Fetch a single resource

Take a ticket ID from the index, then the detail call:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://demo.gomus.de/api/v4/tickets/3

For multi-language data, append ?locale=de. Works on most endpoints.

What next

  • Concepts: the vocabulary you will keep seeing (instance, quota, reservation, order, Pay-By-Link).
  • Scenario: Website integration: full walkthrough for a museum website with event calendar, requests and direct bookings.
  • Authentication: context-aware tokens, foreign_id pattern, best practices.
  • API reference: full endpoint list in the OpenAPI spec on your instance at https://<instance>.gomus.<tld>/api-docs/ (Swagger UI, public). JSON spec directly at /api-docs/v4/swagger.json for tooling and SDK generation.

Caching note

Master data (tickets, events, tours, descriptions) changes rarely. Cache it once a day. Availabilities and seats must not be cached, those have to be live. Put a caching strategy in place before going live. Avoid routing live traffic straight to us.