> For the complete documentation index, see [llms.txt](https://parkdot.gitbook.io/parkdot-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://parkdot.gitbook.io/parkdot-docs/parkdot-api-documentation.md).

# parkdot API documentation

## Base URL

```
https://parkdot.app/api/v1
```

## Authentication

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

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

### Generating API Keys

{% stepper %}
{% step %}

### Log in

Log in to your Parkdot account.
{% endstep %}

{% step %}

### Open API Access

Navigate to Settings → API Access.
{% endstep %}

{% step %}

### Select scope

Select scope (READ or WRITE).
{% endstep %}

{% step %}

### Generate key

Click "Generate key".
{% endstep %}

{% step %}

### Copy credentials

Copy both the key and secret (secret is shown only once).
{% endstep %}
{% endstepper %}

### 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:

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

## Error Responses

All errors return JSON with a machine-readable code:

```json
{
  "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

```http
GET /entities
```

Response:

```json
{
  "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

```http
GET /entities/{entityId}
```

Response:

```json
{
  "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

```http
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:

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

### Delete Entity

**Requires:** WRITE scope, ORG\_ADMIN role

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

{
  "entityId": "ent_123abc"
}
```

Response:

```json
{
  "success": true
}
```

## Availability

### Get Availability Summary

```http
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:

```json
{
  "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

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

Response:

```json
{
  "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

```http
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:

```json
{
  "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.

```http
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:

```json
{
  "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

```http
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:

```json
{
  "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

```http
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:

```json
{
  "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

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

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

### Export Spot Availability

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

Response: Excel file (XLSX) with spot availability timeline

## Examples

### List Entities

```bash
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

```bash
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

```bash
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

```bash
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

{% stepper %}
{% step %}

### Store credentials securely

Never commit API keys to version control.
{% endstep %}

{% step %}

### Use HTTPS

All requests must use HTTPS.
{% endstep %}

{% step %}

### Handle rate limits

Implement exponential backoff.
{% endstep %}

{% step %}

### Validate dates

Use ISO 8601 format (UTC recommended).
{% endstep %}

{% step %}

### Check responses

Always check the `code` field for error handling.
{% endstep %}

{% step %}

### Monitor usage

Track your API usage in Settings.
{% endstep %}
{% endstepper %}

## Support

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://parkdot.gitbook.io/parkdot-docs/parkdot-api-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.