😎parkdot API documentation

Here is our Dev friendly API documentation.

Base URL

https://parkdot.app/api/v1

Authentication

All API requests require authentication using API Key and Secret headers:

X-API-Key: your-api-key
X-API-Secret: your-api-secret

Generating API Keys

Log in

Open API Access

Navigate to Settings → API Access.

Select scope

Select scope (READ or WRITE).

Generate key

Click "Generate key".

Copy credentials

Copy both the key and secret (secret is shown only once).

API Scopes

READ: Allows GET requests and exports
WRITE: Allows POST, PATCH, DELETE requests

Rate Limiting

Rate limits are based on your organization's plan:

Plan

Rate Limit

Starter

50 requests/minute

Scale

100 requests/minute (custom)

Enterprise

500+ requests/minute (custom)

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1698765432000

Error Responses

All errors return JSON with a machine-readable code:

{
  "error": "Human-friendly error message",
  "code": "MACHINE_CODE",
  "details": {}
}

Common Error Codes

Code

HTTP Status

Description

VALIDATION_ERROR

400

Invalid request parameters

UNAUTHORIZED

401

Missing or invalid credentials

FORBIDDEN

403

Insufficient permissions

ENTITY_NOT_FOUND

404

Entity not found

SPOT_NOT_FOUND

404

Parking spot not found

BOOKING_NOT_FOUND

404

Booking not found

SPOT_CONFLICT

409

Spot not available

BOOKING_CONFLICT

409

Booking time conflict

RATE_LIMIT_EXCEEDED

429

Too many requests

INTERNAL_ERROR

500

Server error

Entities

List All Entities

GET /entities

Response:

{
  "entities": [
    {
      "entityId": "ent_123abc",
      "entityName": "Downtown Parking Garage",
      "entityAddress": "Hviezdoslavovo námestie 12, Bratislava, Slovakia",
      "type": "GARAGE",
      "createdAt": "2025-10-27T10:00:00Z",
      "updatedAt": "2025-10-27T10:00:00Z"
    }
  ]
}

Get Entity Details

GET /entities/{entityId}

Response:

{
  "entity": {
    "entityId": "ent_123abc",
    "entityName": "Downtown Parking Garage",
    "entityAddress": "Hviezdoslavovo námestie 12, Bratislava, Slovakia",
    "floors": [
      {
        "floorId": "floor_xyz",
        "floorNumber": "-1",
        "floorSegments": [
          {
            "segmentId": "seg_abc",
            "segmentName": "A",
            "segmentParkingLots": {
              "segmentParkingLotCount": 42
            }
          }
        ]
      }
    ]
  }
}

Create Entity

Requires: WRITE scope, ORG_ADMIN role

POST /entities/create
Content-Type: application/json

{
  "createdEntityName": "Downtown Parking Garage",
  "entityType": "garage",
  "entityAddress": "Hviezdoslavovo námestie 12, Bratislava, Slovakia",
  "floorCount": 1,
  "lotCreationSchema": "F(-1):SA:L10,SB:L23"
}

Lot Creation Schema Format:

F(<label>) - Floor label
S<label> - Segment label
L<count> - Number of lots

Example: F(-1):SA:L10,SB:L23 creates:

Floor "-1"
Segment "A" with 10 lots (1-10)
Segment "B" with 23 lots (1-23)

Response:

{
  "entityId": "ent_123abc",
  "entityName": "Downtown Parking Garage",
  "entityAddress": "Hviezdoslavovo námestie 12, Bratislava, Slovakia"
}

Delete Entity

Requires: WRITE scope, ORG_ADMIN role

POST /entities/delete
Content-Type: application/json

{
  "entityId": "ent_123abc"
}

Response:

{
  "success": true
}

Availability

Get Availability Summary

GET /entities/{entityId}/availability/summary?from={ISO_DATE}&to={ISO_DATE}

Parameters:

from - Start date (ISO 8601 format)
to - End date (ISO 8601 format)

Response:

{
  "entityId": "ent_123abc",
  "entityName": "Downtown Parking Garage",
  "dateRange": {
    "from": "2025-11-01T00:00:00Z",
    "to": "2025-11-07T23:59:59Z"
  },
  "totalLots": 150,
  "occupiedLots": 45,
  "availableLots": 105,
  "availabilityByFloor": [
    {
      "floorNumber": "-1",
      "totalLots": 50,
      "availableLots": 32
    },
    {
      "floorNumber": "0",
      "totalLots": 100,
      "availableLots": 73
    }
  ]
}

Get Spot Availability Timeline

GET /entities/{entityId}/spots/{spotId}/availability?from={ISO_DATE}&to={ISO_DATE}

Response:

{
  "floorLabel": "-1",
  "segmentLabel": "A",
  "spotNumber": "12",
  "timeline": [
    {
      "date": "2025-11-01",
      "status": "available"
    },
    {
      "date": "2025-11-02",
      "status": "occupied",
      "type": "guest",
      "details": {
        "carPlateNumber": "BL123XY",
        "driver": "John Doe"
      }
    }
  ]
}

Spots

List Spots

GET /entities/{entityId}/spots?floor={label}&segment={label}&availableAt={ISO_DATE}

Query Parameters:

floor (optional) - Filter by floor label
segment (optional) - Filter by segment label
availableAt (optional) - Filter only available spots at date

Response:

{
  "spots": [
    {
      "id": "spot_xyz",
      "number": "12",
      "floor": "-1",
      "segment": "A"
    }
  ]
}

Booking

Book a Lot (Auto-assign)

Requires: WRITE scope

Automatically assigns the first available spot in the entity for the requested period.

POST /booking/book/lot
Content-Type: application/json

{
  "entityId": "ent_123abc",
  "bookingType": "guest",
  "vehiclePlate": "BL123XY",
  "driverFirstName": "Martin",
  "driverLastName": "Fribert",
  "driverEmail": "martin.fribert@example.com",
  "dateFrom": "2025-11-02T08:00:00Z",
  "dateTo": "2025-11-05T18:00:00Z",
  "notes": "Overnight stay – hotel guest"
}

Response:

{
  "status": "success",
  "message": "Parking spot booked successfully",
  "booking": {
    "bookingId": "booking_xyz",
    "entityId": "ent_123abc",
    "entityName": "Downtown Parking Garage",
    "assignedSpot": {
      "floorNumber": "-1",
      "segmentName": "A",
      "spotNumber": 12,
      "spotId": "spot_xyz"
    },
    "vehiclePlate": "BL123XY",
    "driverFirstName": "Martin",
    "driverLastName": "Fribert",
    "dateFrom": "2025-11-02T08:00:00Z",
    "dateTo": "2025-11-05T18:00:00Z"
  }
}

Edit Booking

Requires: WRITE scope

POST /booking/edit
Content-Type: application/json

{
  "bookingId": "booking_xyz",
  "vehiclePlate": "BL123XY",
  "driverFirstName": "Martin",
  "driverLastName": "F.",
  "dateFrom": "2025-11-02T09:00:00Z",
  "dateTo": "2025-11-05T18:00:00Z",
  "notes": "Late arrival"
}

Response:

{
  "booking": {
    "id": "booking_xyz",
    "spotId": "spot_xyz",
    "carPlateNumber": "BL123XY",
    "driverFirstName": "Martin",
    "driverLastName": "F.",
    "dateFrom": "2025-11-02T09:00:00Z",
    "dateTo": "2025-11-05T18:00:00Z",
    "note": "Late arrival"
  }
}

Get Booking Info by Plate

GET /booking/get-info?plate={PLATE_NUMBER}&at={ISO_DATE}

Parameters:

plate (required) - Vehicle plate number
at (optional) - Check at specific date/time (defaults to now)

Response:

{
  "booking": {
    "type": "guest",
    "entityId": "ent_123abc",
    "entityName": "Downtown Parking Garage",
    "assignedSpot": {
      "floorNumber": "-1",
      "segmentName": "A",
      "spotNumber": 12,
      "spotId": "spot_xyz"
    },
    "vehiclePlate": "BL123XY",
    "driverFirstName": "Martin",
    "driverLastName": "Fribert",
    "dateFrom": "2025-11-02T08:00:00Z",
    "dateTo": "2025-11-05T18:00:00Z",
    "note": "Overnight stay"
  }
}

Exports

Export Entity Availability

GET /entities/{entityId}/export/availability.xlsx?from={ISO_DATE}&to={ISO_DATE}

Response: Excel file (XLSX) with availability data per day

Export Spot Availability

GET /entities/{entityId}/spots/{spotId}/export.xlsx?from={ISO_DATE}&to={ISO_DATE}

Response: Excel file (XLSX) with spot availability timeline

Examples

List Entities

curl -X GET https://parkdot.app/api/v1/entities \
  -H "X-API-Key: pk_your_key" \
  -H "X-API-Secret: sk_your_secret"

Get Availability Summary

curl -X GET "https://parkdot.app/api/v1/entities/ent_123abc/availability/summary?from=2025-11-01T00:00:00Z&to=2025-11-07T23:59:59Z" \
  -H "X-API-Key: pk_your_key" \
  -H "X-API-Secret: sk_your_secret"

Book a Parking Spot

curl -X POST https://parkdot.app/api/v1/booking/book/lot \
  -H "X-API-Key: pk_your_key" \
  -H "X-API-Secret: sk_your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "ent_123abc",
    "bookingType": "guest",
    "vehiclePlate": "BL123XY",
    "driverFirstName": "Martin",
    "driverLastName": "Fribert",
    "driverEmail": "martin.fribert@example.com",
    "dateFrom": "2025-11-02T08:00:00Z",
    "dateTo": "2025-11-05T18:00:00Z",
    "notes": "Business trip parking"
  }'

Get Booking by Plate

curl -X GET "https://parkdot.app/api/v1/booking/get-info?plate=BL123XY" \
  -H "X-API-Key: pk_your_key" \
  -H "X-API-Secret: sk_your_secret"

Best Practices

Store credentials securely

Never commit API keys to version control.

Use HTTPS

All requests must use HTTPS.

Handle rate limits

Implement exponential backoff.

Validate dates

Use ISO 8601 format (UTC recommended).

Check responses

Always check the code field for error handling.

Monitor usage

Track your API usage in Settings.

Support

Email: support@parkdot.app
Documentation: https://parkdot.app/api/docs
Status: https://status.parkdot.app (future)

Last updated 3 months ago

Good night

hashtagBase URL

hashtagAuthentication

hashtagGenerating API Keys

hashtagLog in

hashtagOpen API Access

hashtagSelect scope

hashtagGenerate key

hashtagCopy credentials

hashtagAPI Scopes

hashtagRate Limiting

hashtagError Responses

hashtagCommon Error Codes

hashtagEntities

hashtagList All Entities

hashtagGet Entity Details

hashtagCreate Entity

hashtagDelete Entity

hashtagAvailability

hashtagGet Availability Summary

hashtagGet Spot Availability Timeline

hashtagSpots

hashtagList Spots

hashtagBooking

hashtagBook a Lot (Auto-assign)

hashtagEdit Booking

hashtagGet Booking Info by Plate

hashtagExports

hashtagExport Entity Availability

hashtagExport Spot Availability

hashtagExamples

hashtagList Entities

hashtagGet Availability Summary

hashtagBook a Parking Spot

hashtagGet Booking by Plate

hashtagBest Practices

hashtagStore credentials securely

hashtagUse HTTPS

hashtagHandle rate limits

hashtagValidate dates

hashtagCheck responses

hashtagMonitor usage

hashtagSupport

Base URL

Authentication

Generating API Keys

Log in

Open API Access

Select scope

Generate key

Copy credentials

API Scopes

Rate Limiting

Error Responses

Common Error Codes

Entities

List All Entities

Get Entity Details

Create Entity

Delete Entity

Availability

Get Availability Summary

Get Spot Availability Timeline

Spots

List Spots

Booking

Book a Lot (Auto-assign)

Edit Booking

Get Booking Info by Plate

Exports

Export Entity Availability

Export Spot Availability

Examples

List Entities

Get Availability Summary

Book a Parking Spot

Get Booking by Plate

Best Practices

Store credentials securely

Use HTTPS

Handle rate limits

Validate dates

Check responses

Monitor usage

Support