Create a Developer API application and key

View .md

Authorized collection administrators and developers can manage Developer API access from the collection’s Kismet settings. An application is the long-lived integration record. Each installation fixes its collection, environment, capability grants, and authorized browser origins. Credentials belong to an installation and cannot widen those grants.

Prerequisites

Sign in to Kismet.
Open the collection you are integrating.
Your effective collection role must be ADMIN, DEVELOPER, or GLOBAL_OWNER. An administrator has the same Developer API rights as a developer for that collection.

If an AI coding agent is doing the integration, install or connect the Kismet Developer plugin and MCP first. Claude and Codex can install the complete plugin; Lovable connects to the same public MCP through a custom Chat connector.

1. Open the Developer API settings

Open the account menu and turn on Developer mode.
Open Collections, choose the collection, and select Settings.
Select the Developer API tab.

Developer mode changes the interface and activates TEST-mode views; it does not turn an existing LIVE credential into a TEST credential. Environment is fixed on each installation.

2. Create and activate an application

Enter a name, stable lowercase slug, and optional description. Create the application, then activate it. Applications begin private and cannot receive an installation until they are active.

Use one application for one deployed integration. Create separate applications when different sites or partners need independent revocation, grants, or audit history.

3. Create an installation

Choose TEST for development and select only the capabilities the application needs. The useful minimum for natural-language discovery is:

search.read to call the collection-scoped search operation.

Most search result pages also need:

vacation_rentals.read for cards and detail reads;
media.read and amenities.read for presentation data;
rates.read for indicative calendar-backed display pricing;
reviews.read and policies.read when those sections are rendered;
collections.read for manager-level content.

Add exact browser origins only when issuing a publishable credential. Origins do not apply as wildcards: http://127.0.0.1:3000 and http://localhost:3000 are different origins.

4. Issue a credential

Use a restricted server credential for Next.js Server Components, route handlers, BFF routes, and the first natural-language search smoke. Use a publishable credential only for explicitly browser-safe reads from an authorized origin.

The complete token is shown once. Copy it immediately into a secret manager or local .env.local file. Kismet stores a one-way credential representation and cannot recover the token later. Revoke a credential immediately if it is exposed; issue a replacement rather than trying to edit it.

KISMET_API_BASE_URL=https://api.ksmt.app/v1
KISMET_DEVELOPER_API_KEY=your_one_time_server_key
KISMET_COLLECTION=juniper-holiday-home

Never use a NEXT_PUBLIC_ variable for a server credential, commit it, paste it into an agent prompt, or send it to the Developer MCP.

5. Smoke natural-language search

Install an SDK build that includes Developer API v0.7.2 search, then run this from a server-only module:

import { createKismetClient } from '@kismet-tech/sdk/server';

const client = createKismetClient({
  apiKey: process.env.KISMET_DEVELOPER_API_KEY!,
  collection: process.env.KISMET_COLLECTION!,
  baseUrl: process.env.KISMET_API_BASE_URL!,
});

const result = await client.bookableProduct.search({
  query: 'a quiet family stay near the water with a pool',
  topK: 12,
});

console.log(result.ranked);

You can verify the credential and API independently of the SDK:

curl --request POST \
  "$KISMET_API_BASE_URL/developer/collections/$KISMET_COLLECTION/search" \
  --header "Authorization: Bearer $KISMET_DEVELOPER_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"query":"a quiet family stay near the water with a pool","topK":12}'

The response should report meta.source: "developer-api". Treat ranked[] as discovery candidates, not availability, a quote, or a booking offer. Use the availability and quote surfaces for those decisions.

Common failures

Response	What to check
`401`	The credential is complete, active, unexpired, and sent as `Authorization: Bearer …`.
`403`	The installation has `search.read`, the collection is within its grants, and a publishable request has an exact authorized origin.
Empty ranking	The collection has published BookableProducts in the current search corpus; unpublished CMS records are intentionally excluded.
Deterministic fallback	The transport works, but the target environment lacks or has not populated its semantic-search corpus. Do not count fallback output as semantic-ranking evidence.

Revoke access

Open the installation, locate the safe credential inventory entry by its displayed prefix, and revoke it with a reason. Revocation is immediate. The full secret is never displayed again.