Skip to main content
Kalinklo · Artists
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
  • country (string) — base country filter
  • limit (number, default 20, max 50) — page size
  • cursor (string) — opaque pagination cursor from the previous response

Response shape:

{
  "success": true,
  "data": [
    {
      "id": "art_…",
      "slug": "…",
      "displayName": "…",
      "instruments": ["…"],
      "baseCountry": "…",
      "verificationStatus": "IDENTITY_VERIFIED"
    }
  ],
  "count": 1,
  "nextCursor": null
}

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/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

Request accessSign in