Skip to main content
KalinkloOS
Developer portal

Developer docs

Public Endpoints

What can be called without an API key — health, public artist search, and the ICS calendar feed.

What "public" means here

Public endpoints accept requests without an Authorization header. They are still rate-limited by IP, still emit a request ID, and still return the standard error envelope. They never expose private data — only what is already visible on the public roster.

GET /api/health

Combined health envelope. Returns liveness + readiness + minimal version metadata.

  • 200 healthy
  • 503 one or more dependencies unhealthy (envelope describes which)

GET /api/health/live

Liveness probe. The process is running and able to respond.

  • 200 alive

GET /api/health/ready

Readiness probe. Dependencies (database, queue) are reachable.

  • 200 ready
  • 503 not ready (returns envelope with which dependency is down)

GET /api/version

Build metadata. Reserved for operations — requires the INTERNAL_OPS_TOKEN bearer.

  • 200 with { buildSha, builtAt, environment } when token is correct
  • 404 to everyone else (deliberately indistinguishable from a missing route)

GET /api/v1/artists

Search the public roster.

Query parameters:

  • q (string) — free-text against display name and biographical fields
  • instrument (string) — single instrument filter
  • genre (string) — single genre filter
  • artistType (string) — artist type enum, such as SOLOIST or CONDUCTOR
  • country (string) — base country filter
  • lastMinuteOnly (boolean) — only artists marked last-minute available
  • verifiedOnly (boolean) — only artists with a completed verification timestamp
  • page (number, default 1) — page number
  • limit (number, default 20, max 50) — page size

Response shape:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "art_...",
        "slug": "...",
        "displayName": "...",
        "artistType": "SOLOIST",
        "instruments": ["Violin"],
        "genres": ["Classical"],
        "baseCountry": "Germany",
        "verificationStatus": "IDENTITY_VERIFIED",
        "links": {
          "profile": "/artists/...",
          "availability": "/api/v1/artists/.../availability"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPreviousPage": false
    }
  }
}

Unverified artists do not appear.

Status codes:

  • 200 success
  • 400 malformed parameter
  • 429 rate-limited

GET /api/v1/artists/:id

Single public artist record by ID. 404 if the ID is unknown or the artist is not public.

GET /api/v1/artists/:id/availability

Public availability blocks for a public artist, by ID or slug.

Query parameters:

  • startDate (date) — optional ISO date window start
  • endDate (date) — optional ISO date window end
  • days (number, default 30, max 120) — window size when endDate is omitted

GET /api/artists/:id/calendar.ics

ICS-format calendar feed of declared availability for one artist. Subscribable by any calendar client.

  • 200 with Content-Type: text/calendar
  • 404 if the artist disabled the public feed

Where to next