# unowli Partner API

> unowli lists events in Germany. Software providers (restaurant and bar back offices, event management tools, small apps) can deliver their events to unowli as schema.org/Event over a small HTTP API. Delivered events run through the same checks as every other source and appear in the unowli app, in search engines and in AI assistants. Server to server only. Keys are issued on request: philipp@unowli.app.

## Documents

- [OpenAPI 3.1](https://www.unowli.app/partner/openapi.json): machine readable description of all endpoints and schemas
- [This file](https://www.unowli.app/partner/llms.txt)

## Deliver events (scope write)

Header: Authorization: Bearer <delivery key> (format unowli_wr_...). Content-Type: application/json.

- POST https://www.unowli.app/partner/intake/events : one event, an array of up to 50 events, {"events": [...]} or an ItemList. Same identifier = same event (update).
- PUT https://www.unowli.app/partner/intake/events/{identifier} : create or update one event (idempotent).
- DELETE https://www.unowli.app/partner/intake/events/{identifier} : withdraw one event.
- GET https://www.unowli.app/partner/intake/events : your deliveries (state=active|withdrawn, limit, offset). GET https://www.unowli.app/partner/intake/events/{identifier} : one delivery.
- GET https://www.unowli.app/partner/intake/usage : today's counters and all limits.

Minimal event:

```json
{
  "@context": "https://schema.org",
  "@type": "MusicEvent",
  "identifier": "gig-4711",
  "name": "Jazz im Keller",
  "startDate": "2027-03-13T20:30:00+01:00",
  "endDate": "2027-03-13T23:00:00+01:00",
  "location": {
    "@type": "Place",
    "name": "Kulturkeller Beispiel",
    "address": {
      "@type": "PostalAddress",
      "streetAddress": "Hauptstraße 1",
      "postalCode": "60311",
      "addressLocality": "Frankfurt am Main"
    },
    "geo": {
      "@type": "GeoCoordinates",
      "latitude": 50.1109,
      "longitude": 8.6821
    }
  },
  "description": "Ein Abend mit dem Quartett. Einlass 19:30 Uhr.",
  "image": "https://www.example-venue.de/media/jazz.jpg",
  "url": "https://www.example-venue.de/events/gig-4711",
  "offers": {
    "@type": "Offer",
    "price": "18.00",
    "priceCurrency": "EUR",
    "url": "https://tickets.example-venue.de/gig-4711"
  }
}
```

Withdraw by status (nothing else needed):

```json
{"identifier":"gig-4711","eventStatus":"https://schema.org/EventCancelled"}
```

## Rules the checks apply

- identifier (your own ID), name, startDate and location are required. Unknown properties are ignored and listed in warnings.
- startDate needs a time of day. With an offset (+01:00 or Z) it is exact, without one it is Berlin local time. A date without time and a start at exactly 00:00 Berlin are rejected, never guessed. Start must lie in the future, within 400 days.
- endDate is optional; send it only when the organiser states an end. It must follow the start by at most 7 days. unowli never shows an estimated end.
- location: name plus geo (latitude, longitude), or a known unowli place (identifier = place UUID, or url = https://www.unowli.app/location/<slug>). Keys fixed to one place ignore the block. Places must lie in municipalities unowli covers.
- unowli makes no statement about the state of an event. eventStatus EventCancelled, EventPostponed and EventMovedOnline withdraw the event. availability (SoldOut and so on) is ignored. A name that states a cancellation or move is rejected; sold-out markers are removed from the name.
- Online-only events, sales events and event series objects are not accepted.
- description, image and credit are plain text and https URLs only (HTML is stripped, URLs are never fetched). They are shown only when your account has granted the rights for texts and images; until then they are used internally for tagging and not shown.
- Prices: EUR only. The lowest offer price is used; offers.url becomes the ticket link.
- Result per event: created, updated, unchanged, withdrawn or rejected. visibility: live, awaiting_review (new accounts are reviewed first) or not_listed. A rejected event lists every problem in errors.

## Limits

- 50 events and 262144 bytes per call, 120 calls per hour.
- 600 processed events per day, 150 new events per day (default; updates and withdrawals still work), 10 new places per day, 5000 active upcoming events.
- 429 carries Retry-After. Send each change once; resend whole feeds at most hourly.

## Terms

Delivery needs a key and accepted delivery terms; both are handed out together on request. Write to philipp@unowli.app.

The delivery terms (version 2026-10-13.v1-anlieferung, valid since 13.10.2026) are published here: https://github.com/Keltaos/unowli-api/blob/main/TERMS.md