How To Connect Your Venue System To The KudosCourts Developer API

Start in the Developers dashboard by creating a named integration for the external system that will control or read availability. Think of an integration as the operational boundary for one venue system, one partner, or one deployment environment.

Keeping integrations separate matters because keys, mapped external court IDs, and readiness checks all live inside that boundary. If you merge multiple systems into one integration too early, the dashboard becomes harder to reason about and handoff becomes riskier.

As soon as the integration exists, the launchpad can track progress through keys, mappings, precheck, and the guided test console. That makes it clear what still blocks a safe handoff.

X-API-Key: YOUR_API_KEY

After the integration is created, issue a server-side API key with only the scopes the partner needs. The dashboard shows the plaintext secret once, then stores only the masked prefix and metadata afterward.

This is the moment to capture the secret in the partner's secret manager. The dashboard is intentionally optimized for a smooth handoff: the same card shows the current scopes, IP allowlist notes, and recent usage metadata after the reveal moment passes.

If the partner only needs live reads at first, start with `availability.read`. Add write scope only when they are actually ready to push availability changes into the platform.

If you want to validate the full public contract before handoff, create a temporary smoke-test key with both `availability.read` and `availability.write`, run the external write smoke once, then keep or rotate that key according to your launch policy.

kudos_live_abc123_demo_secret

The mapping table is where you connect each external court identifier to a real bookable court in the organization. The dashboard uses the same active venue and court inventory that operators already manage elsewhere in the platform.

This is the step that makes the rest of the workflow meaningful. Precheck, live reads, and write calls all depend on a valid external court ID mapping — without it, the API has no safe way to resolve the partner's identifiers to the internal booking model.

The guide should be read with the expectation that the table mirrors the live Developers dashboard exactly, but preview snippets can crop down to the relevant rows so the article stays readable.

The precheck is the fastest way to validate readiness without sending the external engineering team on a blind integration attempt. It runs server-side and checks the fixed onboarding contract: integration health, key health, required scope, mapping existence, and a live sample availability read.

That means the product can catch the most common launch blockers before anyone copies a single snippet into a server. If the check fails, the response includes enough detail to tell you whether the problem is the integration setup, the key, the selected external court, or the live availability path.

Use the precheck whenever you change mappings or rotate keys. It is not just for first launch — it is the safest quick regression scan for the whole integration setup.

The guided test console is intentionally narrow: one live, read-only availability request that runs server-side against the currently selected integration, key, mapped external court, date, and duration.

This is enough to prove the end-to-end path works without turning the dashboard into a general-purpose API playground. The operator gets a visible request shape, the response payload, and the request ID needed for support or deeper investigation.

Once that read is green, switch to the public API for one external write smoke: create a temporary unavailability window with `curl`, read the same external court back through the public availability endpoint, then delete the temporary window immediately. That proves read and write alignment without moving write execution into the browser.

Because the console is locked to a safe read path, it is ideal for onboarding review calls and internal verification. Write calls stay copy-first in v1 so operators and developers can validate them deliberately and clean them up explicitly.

{
  "request": {
    "externalCourtId": "ext-court-a",
    "date": "2026-03-16T09:00:00.000Z",
    "durationMinutes": 60,
    "includeUnavailable": true
  },
  "response": {
    "options": [
      {
        "courtId": "court-1",
        "startTime": "2026-03-16T09:00:00.000Z",
        "endTime": "2026-03-16T10:00:00.000Z",
        "status": "AVAILABLE",
        "totalPriceCents": 60000,
        "currency": "PHP"
      }
    ],
    "diagnostics": {
      "hasHoursWindows": true,
      "hasRateRules": true,
      "dayHasHours": true,
      "allSlotsBooked": false
    }
  },
  "requestId": "req_dev_01"
}

Once the integration is green, move to the snippets and docs panel. The page generates cURL and JavaScript examples from the currently selected mapped external court and test inputs, then links directly to the public OpenAPI document for the full contract.

This is where operator UX and developer DX meet: the operator can confirm the selected values look right, and the external engineering team gets a starting point that already matches the live dashboard state instead of a generic sample lifted from separate documentation.

For full handoff, package three things together: the generated read snippet, the exact mapped external court id, and the public write smoke sequence you already validated with immediate cleanup. That gives the external team both the first request and the safest write pattern.

Use the generated snippets as the handoff artifact, but keep the OpenAPI spec in the package too. The snippets explain the first request; the contract explains the whole surface.

curl -sS "https://kudoscourts.ph/api/developer/v1/courts/ext-court-a/availability?date=2026-03-16T09%3A00%3A00.000Z&durationMinutes=60&includeUnavailable=true" \
  -H "X-API-Key: kudos_live_abc123_demo_secret" \
  -H "Accept: application/json"

const url = new URL(
  "https://kudoscourts.ph/api/developer/v1/courts/ext-court-a/availability",
);
url.searchParams.set("date", "2026-03-16T09:00:00.000Z");
url.searchParams.set("durationMinutes", "60");
url.searchParams.set("includeUnavailable", "true");

const response = await fetch(url, {
  headers: { "X-API-Key": "kudos_live_abc123_demo_secret" },
});
const json = await response.json();
console.log(json);