Skip to content
Quikstik Developers

Request an availability snapshot

POST
/availability/snapshot-requests
curl --request POST \
  --url https://quikstik-core.fly.dev/availability/snapshot-requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-tenant-id: 2489E9AD-2EE2-8E00-8EC9-32D5F69181C0' \
  --data '{ "offering_variant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "window": { "start": "example", "end": "example" }, "quantity": 1, "participant_count": 1, "resource_requirements": [ { "kind": "example", "resource_type": "example", "quantity": 1 } ] }'

Requests a point-in-time availability snapshot for an offering variant, time window, and (optional) participant/resource requirements.

This endpoint is intentionally read/query oriented:

  • It does not allocate inventory.
  • It does not execute booking workflows.
  • It does not guarantee the snapshot can be used to reserve anything.

The snapshot is a contract vocabulary placeholder aligned to the future command/event seam: commerce.request_availability_snapshot (command) and commerce.availability.snapshot_generated (event).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
x-tenant-id
required
string format: uuid

Tenant identifier (UUID).

Authn/authz semantics are intentionally TBD for this contract slice; this header exists to keep the contract explicitly multi-tenant from day 0.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
offering_variant_id
required
string format: uuid
window
required
object
start
required

RFC3339 timestamp.

string
end
required

RFC3339 timestamp.

string
quantity

Quantity requested (participants/items); semantics TBD.

integer
nullable >= 1
participant_count

Participant count (if applicable); semantics TBD.

integer
nullable
resource_requirements
Array<object>
nullable
object
kind
required

Resource requirement kind (vocabulary only). Examples: equipment, staff, venue. Allowed values and semantics are TBD.

string
resource_type

Resource type identifier (TBD).

string
nullable
quantity
integer
nullable >= 1

Example generated

{
  "offering_variant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "window": {
    "start": "example",
    "end": "example"
  },
  "quantity": 1,
  "participant_count": 1,
  "resource_requirements": [
    {
      "kind": "example",
      "resource_type": "example",
      "quantity": 1
    }
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

Authoritative availability snapshot (recompute-on-request; advisory, not a reservation)

Media typeapplication/json
object
snapshot_id
required
string format: uuid
generated_at_ms
required

Unix epoch milliseconds.

integer format: int64
window
required
object
start
required

RFC3339 timestamp.

string
end
required

RFC3339 timestamp.

string
lines
required
Array<object>
object
offering_variant_id
required
string format: uuid
start_time

Start time (RFC3339). Null when the offering is not slot-based (TBD).

string
nullable
status
required

Availability status (vocabulary only). Examples: available, unavailable, inquire, unknown. Allowed values and semantics are TBD (do not infer algorithmic behavior).

string
available_quantity

Non-binding count (TBD).

integer
nullable
notes

Human-readable hint only.

string
nullable
basis

How available_quantity was arrived at. Present on every line read from the capacity chain (absent only for unknown/unconfigured lines). offered = chain_remaining − withheld; withheld is seats reserved for other demand classes on this departure. Lets any reader reconcile the storefront number against the pools without a database.

object
chain_remaining
required

Minimum of limit − committed over the leaf and every ancestor.

integer
withheld
required
integer
offered
required
integer

Example generated

{
  "snapshot_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "generated_at_ms": 1,
  "window": {
    "start": "example",
    "end": "example"
  },
  "lines": [
    {
      "offering_variant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "start_time": "example",
      "status": "example",
      "available_quantity": 1,
      "notes": "example",
      "basis": {
        "chain_remaining": 1,
        "withheld": 1,
        "offered": 1
      }
    }
  ]
}