😎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

1

Log in

Log in to your Parkdot account.

2

Open API Access

Navigate to Settings → API Access.

3

Select scope

Select scope (READ or WRITE).

4

Generate key

Click "Generate key".

5

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": "[e-mail]",
  "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": "[e-mail]",
    "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

1

Store credentials securely

Never commit API keys to version control.

2

Use HTTPS

All requests must use HTTPS.

3

Handle rate limits

Implement exponential backoff.

4

Validate dates

Use ISO 8601 format (UTC recommended).

5

Check responses

Always check the code field for error handling.

6

Monitor usage

Track your API usage in Settings.

Support

• Email: [e-mail]

• Documentation: https://parkdot.app/api/docs

• Status: https://status.parkdot.app (future)