canonical: https://jentic.com/apis/parkalot.io/parkalot

# Parkalot API

Parkalot API provides parking reservation management and reporting for facilities, enabling operators to query reservations in flat or nested formats, create and release parking spot reservations in batch, delete reservations for date ranges, track reservation changes via timestamp comparison, and retrieve parking reports with item-level occupancy details. Authentication uses a scoped API key with permissions for reports, reservations, users, and setup operations.

## For AI agents

Manage parking spot reservations, track changes, and retrieve occupancy reports for Parkalot parking facilities.

## Scope

Does not control physical access gates, process payments, or manage facility setup - use only for reservation queries, batch reservation updates, deletion, change detection, and occupancy reporting.

## Capabilities

- Retrieve parking reservations in nested (grouped by day/item) or flat (one period per record) formats
- Create or release parking spot reservations in batch operations with waitlist support
- Delete user reservations across date ranges (max 31 days) by uid, externalId, or email
- Check if reservations or parking setup changed since a given unix timestamp
- Query parking reports showing item state, user assignments, and reservation timing
- Include optional item metadata: tags, descriptions, group IDs, and group names

## Use cases

### Automated Reservation Management

Integrate Parkalot reservations into an office management or visitor scheduling system. PUT `/reservations/{facilityId}` accepts a batch array where each entry specifies spot, day, shifts, and uid (null to unreserve). Use externalId or email to map users between systems, and withWaitlist to trigger automatic assignment when spots free up.

Example prompt: PUT `/reservations/{facilityId}` with an array of PublicReserveRequest objects. Set uid to the user identifier to reserve, or null to unreserve. Check the ReserveResponse array for per-request success or error.

### Real-Time Reservation Monitoring

Poll for reservation changes to drive real-time dashboards or notification workflows. GET `/reservations/{facilityId}/did-change/{fromDay}/{toDay}`?since={timestamp} returns hasChanges and per-day change flags, allowing efficient incremental syncs without fetching full data when nothing changed.

Example prompt: GET `/reservations/{facilityId}/did-change/{fromDay}/{toDay}`?since={lastSyncTimestamp} and only re-fetch reservations if hasChanges is true or a specific day's changed flag is set.

### Occupancy Reporting

Generate parking occupancy reports for compliance, billing, or analytics by querying the reports endpoint. GET `/reports/{facilityId}/readable/{fromDay}/{toDay}` returns item-level records with user assignments, reservation/release timestamps, and owner information. Use for weekly summaries, chargebacks, or identifying underutilized spots.

Example prompt: GET `/reports/{facilityId}/readable/{fromDay}/{toDay}` and parse the items array. Each ItemState record includes item name, user name, reserved_at, released_at, and group membership.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/reservations/{facilityId}/nested-day/{fromDay}/{toDay}` | Query reservations in nested format grouped by day and item |
| GET | `/reservations/{facilityId}/flat/{fromDay}/{toDay}` | Query reservations in flat format with one time period per record |
| PUT | `/reservations/{facilityId}` | Create or release parking spot reservations in batch |
| DELETE | `/reservations/{facilityId}/{fromDay}/{toDay}` | Delete user reservations for a date range |
| GET | `/reports/{facilityId}/readable/{fromDay}/{toDay}` | Retrieve parking occupancy reports |

## Key resources

- **Reservations** — Parking spot reservations organized by facility, date, item, and time periods with user assignments
- **Reports** — Parking occupancy records showing item state, user, owner, and timing for analysis
- **Items** — Individual parking spots or resources with optional tags, descriptions, and group membership

## Why Jentic

- **Setup:** Wiring the Parkalot API by hand means carrying its scoped x-api-key header, shaping the per-facility reservation and report routes, and handling retries yourself. Through Jentic you install once, import Parkalot from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Parkalot puts the facility id in the URL path (`/reservations/{facilityId}/...`), so a rule can pin your agent to one facility: it can read reservations and occupancy reports there. You choose the operations it may call, so destructive ones like reservation deletion are not included unless you add them.
- **Credential handling:** Your Parkalot API key is stored once, encrypted, by your own Jentic One instance and injected as the x-api-key header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'update reservations for a facility' or 'get a parking occupancy report', and Jentic returns the matching Parkalot operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Parklio API** — Parklio provides physical parking hardware (barriers, bollards) while Parkalot handles reservation management and occupancy tracking.
- **ParkMobile API** — ParkMobile offers similar parking session and location management but focuses on consumer parking payments rather than facility reservation systems.

## FAQ

### What authentication does the Parkalot API use?

The API uses API key authentication via the x-api-key header with scoped permissions: reports-exact-read, reservations-read, reservations-write, users-read, users-write, setup-read, setup-write, spots-read, spots-write, access-write, confirmation-settings-read/write, and integrations-settings-read/write. Jentic stores the key encrypted and injects it at execution time.

### What is the maximum date range for reservations?

Reservation queries and deletions support a maximum 31-day range between fromDay and toDay. The API returns 400 Bad Request if the range exceeds this limit.

### Can I trigger waitlist processing when releasing a spot?

Yes. Set withWaitlist=true in the PublicReserveRequest or as a query parameter on DELETE operations. This triggers automatic assignment from the waitlist when a spot becomes available.

### How do I check for reservation changes without fetching all data?

Use GET `/reservations/{facilityId}/did-change/{fromDay}/{toDay}`?since={unixTimestampInMillis}. It returns hasChanges and a per-day array of change flags, allowing incremental syncs.

### Can I limit what my agent is allowed to do with the Parkalot API?

Yes. Because you run Jentic One yourself, your own rules decide which Parkalot operations and credentials the agent can use. Since the facility id lives in the URL path (`/reservations/{facilityId}/...`), you can pin the agent to a single facility and grant only the operations you want, such as reading reservations in nested or flat format and pulling occupancy reports. Destructive calls like deleting reservations for a date range are left out unless you explicitly add them, and the scoped x-api-key stays with your instance rather than the agent's prompt.