GET group availability
View .mdGET /v1/developer/collections/{collection}/groups/availability
Operation ID: getGroupAvailability
Canonical building/neighborhood union selection over published collection inventory. Calendar-plane estimates, never chargeable quotes. lowestStay is withheld unless coverage is complete and all prices comparable. Current base-calendar coverage is explicitly partial: lowestObservedStays preserves qualified base estimates without claiming the cheapest supplier rate plan. Missing evidence is unknown, not sold out. A declared host is required; staging links never fall back to production. No request-time supplier fan-out.
Contract status
Section titled “Contract status”| Field | Value |
|---|---|
| Maturity | beta |
| Required capability | rates.read |
| Freshness class | synced-commercial |
| Quota cost | 1 |
All operations require a Kismet Developer Bearer credential. Collection and resource authority is resolved from the credential’s installation grants; identifiers in the URL never grant access.
Request parameters
Section titled “Request parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
guests |
query | integer | yes | |
host |
query | string | yes | |
groupType |
query | building | no | |
groupSlug |
query | array |
no | |
neighborhoodSlug |
query | array |
no | |
checkIn |
query | string | yes | |
checkOut |
query | string | yes | |
collection |
path | string | yes |
Request body
Section titled “Request body”This operation has no JSON request body.
Set KISMET_API_ORIGIN=https://api.ksmt.app and configure KISMET_DEVELOPER_API_KEY in your environment. Run server-credential requests from your backend, not browser code.
curl --request GET \ "$KISMET_API_ORIGIN/v1/developer/collections/example-collection/groups/availability?guests=4&host=staging.example.com&checkIn=2027-01-11&checkOut=2027-01-16" \ --header "Authorization: Bearer $KISMET_DEVELOPER_API_KEY" \ --header "Accept: application/json"Responses
Section titled “Responses”| Status | Meaning |
|---|---|
| 200 | Success. |
| 400 | Invalid request parameters or body. |
| 401 | Missing, invalid, expired, or inappropriate credential/session. |
| 403 | Credential lacks the required grant/capability, or an origin/CSRF check failed. |
| 429 | Rate limit or quota exceeded; inspect response metadata before retrying. |
| 503 | A required Kismet dependency is temporarily unavailable. |
200 response schema
Section titled “200 response schema”Content type: application/json. Required fields, nullable values, and nested structures are defined below.
View complete response schema
{ "type": "object", "required": [ "data", "meta" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "groupId", "groupSlug", "classification", "availability", "completeness", "lowestStay", "lowestObservedStays", "coverage", "reasons", "retrievedAt", "dataAsOf", "expiresAt", "navigation" ], "properties": { "groupId": { "type": "string" }, "groupSlug": { "type": "string" }, "classification": { "type": "object", "additionalProperties": false, "required": [ "semanticType" ], "properties": { "semanticType": { "type": "string", "enum": [ "UNCLASSIFIED", "BUILDING", "NEIGHBORHOOD" ] } } }, "availability": { "type": "string", "enum": [ "available", "unavailable", "unknown" ] }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] }, "lowestStay": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "productId", "supplier", "roomTypeId", "ratePlanId", "checkIn", "checkOut", "guests", "currency", "totalMinor", "averageNightlyMinor", "nights", "priceBasis", "priceKind", "included", "excluded", "unknownComponents", "dataAsOf", "expiresAt" ], "properties": { "productId": { "type": "string" }, "supplier": { "type": "string" }, "roomTypeId": { "type": [ "null", "string" ] }, "ratePlanId": { "type": [ "null", "string" ] }, "checkIn": { "type": "string" }, "checkOut": { "type": "string" }, "guests": { "type": "integer" }, "currency": { "type": "string" }, "totalMinor": { "type": "integer" }, "averageNightlyMinor": { "type": "integer" }, "nights": { "type": "integer" }, "priceBasis": { "type": "string" }, "priceKind": { "type": "string", "enum": [ "estimate", "quote" ] }, "included": { "type": "array", "items": { "type": "string" } }, "excluded": { "type": "array", "items": { "type": "string" } }, "unknownComponents": { "type": "array", "items": { "type": "string" } }, "dataAsOf": { "type": "string" }, "expiresAt": { "type": "string" } } }, { "type": "null" } ] }, "lowestObservedStays": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "productId", "supplier", "roomTypeId", "ratePlanId", "checkIn", "checkOut", "guests", "currency", "totalMinor", "averageNightlyMinor", "nights", "priceBasis", "priceKind", "included", "excluded", "unknownComponents", "dataAsOf", "expiresAt" ], "properties": { "productId": { "type": "string" }, "supplier": { "type": "string" }, "roomTypeId": { "type": [ "null", "string" ] }, "ratePlanId": { "type": [ "null", "string" ] }, "checkIn": { "type": "string" }, "checkOut": { "type": "string" }, "guests": { "type": "integer" }, "currency": { "type": "string" }, "totalMinor": { "type": "integer" }, "averageNightlyMinor": { "type": "integer" }, "nights": { "type": "integer" }, "priceBasis": { "type": "string" }, "priceKind": { "type": "string", "enum": [ "estimate", "quote" ] }, "included": { "type": "array", "items": { "type": "string" } }, "excluded": { "type": "array", "items": { "type": "string" } }, "unknownComponents": { "type": "array", "items": { "type": "string" } }, "dataAsOf": { "type": "string" }, "expiresAt": { "type": "string" } } } }, "coverage": { "anyOf": [ { "type": "object", "required": [ "members", "available", "unavailable", "unknown", "suppliers" ], "properties": { "members": { "type": "integer", "minimum": 0 }, "available": { "type": "integer", "minimum": 0 }, "unavailable": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 }, "suppliers": { "type": "array", "items": { "type": "object", "required": [ "supplier", "checked", "complete" ], "properties": { "supplier": { "type": "string" }, "checked": { "type": "integer", "minimum": 0 }, "complete": { "type": "boolean" } } } } } }, { "type": "object", "required": [ "windows", "completeWindows", "byArrival" ], "properties": { "windows": { "type": "integer", "minimum": 0 }, "completeWindows": { "type": "integer", "minimum": 0 }, "byArrival": { "type": "array", "items": { "type": "object", "required": [ "checkIn", "members", "available", "unavailable", "unknown", "suppliers" ], "properties": { "checkIn": { "type": "string" }, "members": { "type": "integer", "minimum": 0 }, "available": { "type": "integer", "minimum": 0 }, "unavailable": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 }, "suppliers": { "type": "array", "items": { "type": "object", "required": [ "supplier", "checked", "complete" ], "properties": { "supplier": { "type": "string" }, "checked": { "type": "integer", "minimum": 0 }, "complete": { "type": "boolean" } } } } } } } } } ] }, "reasons": { "type": "array", "items": { "type": "string" } }, "retrievedAt": { "type": "string" }, "dataAsOf": { "type": [ "null", "string" ] }, "expiresAt": { "type": "string" }, "arrivalWindow": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "days": { "type": "integer" } } }, "stayLength": { "type": "integer" }, "guests": { "type": "integer" }, "navigation": { "type": "object", "required": [ "url", "status" ], "properties": { "url": { "type": [ "null", "string" ] }, "status": { "type": "string", "enum": [ "declared", "unmapped" ] } } } } } }, "meta": { "type": "object", "required": [ "guests", "host", "retrievedAt", "calendarDayTimezone", "priceKind" ], "properties": { "guests": { "type": "integer" }, "host": { "type": "string" }, "retrievedAt": { "type": "string" }, "calendarDayTimezone": { "type": "string" }, "priceKind": { "type": "string" } } } }}