Venuemaster3000 · API v2.4

Venuemaster API.

REST + Webhooks. JSON-only. Versioniert via Header apps3k-version: 2024-12-01. Stabilitätsgarantie nach Semver: Breaking Changes nur in neuen Versionen, alte Versionen mind. 12 Monate parallel.

Authentifizierung

Alle Requests verlangen einen Bearer-Token im Authorization-Header. Tokens werden im Workspace-Settings unter API Keys erzeugt und können auf bestimmte Scopes (events:read, bookings:write …) eingeschränkt werden.

Base URL https://api.apps3k.ch/venuemaster/v2

Fehler

Wir verwenden konventionelle HTTP-Statuscodes. 2xx = Erfolg, 4xx = Client-Fehler (validate, fix, retry), 5xx = Server-Fehler (idempotent retry mit Backoff).

Status	Code	Bedeutung
400	invalid_request	Body- oder Query-Validierung fehlgeschlagen. Details in `errors[]`.
401	unauthorized	Token fehlt oder ist ungültig.
403	forbidden_scope	Token hat den benötigten Scope nicht.
404	not_found	Ressource existiert nicht oder gehört nicht zu diesem Workspace.
409	conflict	Versionskonflikt; Idempotency-Key ggf. erneut prüfen.
429	rate_limited	Limit überschritten, `Retry-After` Header beachten.
503	temporarily_unavailable	Backend kurz nicht erreichbar; idempotent retry empfohlen.

Rate-Limits

600 req/min pro Token. Bursts bis 1200/min für 60s. Headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset in jeder Antwort.

PATCH `/events/{id}`

Aktualisiert ein bestehendes Event. Felder, die nicht im Body enthalten sind, bleiben unverändert. Sitzplan-Mutationen müssen über einen separaten Endpoint laufen (Seat plans).

Pfad-Parameter

Parameter	Typ	Pflicht	Beschreibung
id	string · uuid	Required	Event-ID (Pfadparameter).

Body-Parameter

Parameter	Typ	Pflicht	Beschreibung
title	string	Optional	Anzeigename des Events. Max. 200 Zeichen.
starts_at	string · ISO 8601	Optional	Beginn inkl. Zeitzone, z. B. `2026-09-12T19:30:00+02:00`.
ends_at	string · ISO 8601	Optional	Ende. Muss nach `starts_at` liegen.
venue_id	string · uuid	Optional	Verknüpfter Venue. Bei Wechsel wird der zugeordnete Sitzplan gelöst.
visibility	enum	Optional	`draft`, `public`, `private`, `archived`.
capacity_override	integer	Optional	Manuelle Obergrenze. `null` = automatisch nach Sitzplan.
metadata	object	Optional	Frei wählbare Key/Value-Paare. Max 20 Keys, je 500 Zeichen.

Antworten

Status	Beschreibung
200	Event erfolgreich aktualisiert. Body enthält das vollständige aktualisierte Objekt.
400	Validierungsfehler. `errors[].path` verweist auf das fehlerhafte Feld.
404	Kein Event mit dieser ID im Workspace.
409	Konflikt — Event ist bereits archiviert oder hat aktive Bookings, die das Update blockieren.

Anfrage

curl "https://api.apps3k.ch/venuemaster/v2/events/evt_8h2k...91" \
  -X PATCH \
  -H "Authorization: Bearer $APPS3K_TOKEN" \
  -H "apps3k-version: 2024-12-01" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Bach · Matthäus-Passion",
    "starts_at": "2026-09-12T19:30:00+02:00",
    "visibility": "public"
  }'

import { Apps3k } from "@apps3k/sdk";

const client = new Apps3k(process.env.APPS3K_TOKEN);

const event = await client.venuemaster.events.update("evt_8h2k...91", {
  title: "Bach · Matthäus-Passion",
  starts_at: "2026-09-12T19:30:00+02:00",
  visibility: "public"
});

from apps3k import Apps3k

client = Apps3k(api_key=os.environ["APPS3K_TOKEN"])

event = client.venuemaster.events.update(
    "evt_8h2k...91",
    title="Bach · Matthäus-Passion",
    starts_at="2026-09-12T19:30:00+02:00",
    visibility="public",
)

<?php
use Apps3k\Client;

$client = new Client(getenv("APPS3K_TOKEN"));

$event = $client->venuemaster->events->update("evt_8h2k...91", [
    "title" => "Bach · Matthäus-Passion",
    "starts_at" => "2026-09-12T19:30:00+02:00",
    "visibility" => "public",
]);

import "github.com/apps3k/apps3k-go"

client := apps3k.NewClient(os.Getenv("APPS3K_TOKEN"))

event, err := client.Venuemaster.Events.Update(ctx, "evt_8h2k...91", &apps3k.EventUpdateParams{
    Title:      apps3k.String("Bach · Matthäus-Passion"),
    StartsAt:   apps3k.Time(t),
    Visibility: apps3k.EventVisibilityPublic,
})

Antwort · 200

{
  "id": "evt_8h2k...91",
  "object": "event",
  "title": "Bach · Matthäus-Passion",
  "starts_at": "2026-09-12T19:30:00+02:00",
  "ends_at": "2026-09-12T22:15:00+02:00",
  "venue_id": "vnu_zh_tonhalle",
  "visibility": "public",
  "capacity": 1455,
  "capacity_override": null,
  "metadata": {
    "campaign": "herbst-2026"
  },
  "updated_at": "2026-05-07T14:23:08Z",
  "livemode": true
}

Antwort · 400

{
  "error": {
    "code": "invalid_request",
    "message": "ends_at must be after starts_at",
    "errors": [
      {
        "path": "ends_at",
        "code": "out_of_range"
      }
    ]
  }
}

SDK · Node

import { Apps3k } from "@apps3k/sdk";

const client = new Apps3k(process.env.APPS3K_TOKEN);

const event = await client.venuemaster.events.update(
  "evt_8h2k...91",
  { visibility: "public" }
);