Public Endpoints · Developer Docs

Choose the right public surface

These routes do not use an organization API key. The artist list and profile routes expose eligible demo profiles only. Availability and calendar feeds follow separate public-visibility rules; they are not a way to read a private artist folio.

GET /api/v1/artists

Filter with q, instrument, genre, artistType or country. lastMinuteOnly and verifiedOnly accept true or false. page starts at 1 and is capped at 500; limit defaults to 20 and accepts 1–50. The example below requests one item.

The response has data.query, data.items and data.pagination. A valid response can contain no items. Do not interpret public sample results as customer access or confirmed availability.

bash

curl -sSf "https://kalinklo.com/api/v1/artists?limit=1" \
  -H "Accept: application/json"

Example with no matching demo profiles

json

{
  "success": true,
  "data": {
    "query": {
      "page": 1,
      "limit": 1,
      "q": null,
      "artistType": null,
      "instrument": null,
      "country": null,
      "genre": null,
      "lastMinuteOnly": false,
      "verifiedOnly": false
    },
    "items": [],
    "pagination": {
      "page": 1,
      "limit": 1,
      "total": 0,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPreviousPage": false
    }
  }
}

GET /api/v1/artists/{id}

Pass an artist ID or slug. Eligible demo profiles return data.requestedIdOrSlug and data.artist; missing or ineligible profiles return 404. Public location and fee fields still follow their visibility settings.

GET /api/v1/artists/{id}/availability

Pass an ID or slug. The artist must be PUBLIC, have isPublic enabled and have an eligible verification status. This route is not restricted to demo profiles. Only public calendar entries are returned, capped at 500 in the requested window. Use optional startDate, endDate and days (default 30, range 1–120). Blocks normalize to AVAILABLE or BUSY. An empty or apparently available window does not reserve a date or confirm an engagement.

GET /api/artists/{id}/calendar.ics

Pass an ID or slug. The artist must be PUBLIC with an eligible verification status. The ICS feed includes only public entries, ordered by start time, capped at 500, with a 90-day lookback. It returns text/calendar and public availability labels rather than private event details. A hidden or ineligible artist returns 404. This is a separate calendar surface, not the demo-only profile API.

Health and operations

GET /api/health/live returns 200 when the process responds. GET /api/health/ready and GET /api/health return 200 for a healthy readiness result or 503 otherwise. Anonymous bodies expose only data.status, not dependency details or build metadata. A health result does not prove a booking, payment or integration works.

json

{ "success": true, "data": { "status": "ok" } }

GET /api/version is reserved for operations. It requires configured operations credentials, not an organization API key, and deliberately returns 404 to other callers. Authorized responses wrap runtime metadata in success and data.

Validation and limits

Artist routes enforce IP rate limits. Invalid query values, such as limit=0, return 422 with error.code equal to VALIDATION_ERROR. A rate-limit rejection returns 429; respect Retry-After when supplied. A 404 must not be used to infer whether a private artist exists.