Skip to main content

​
Welcome to Harbor Parking API

Our REST API enables developers to integrate parking spot sharing functionality into any application. Built with modern standards and developer experience in mind.

​
Base URL

All API requests should be made to: 
https://harbor-parking.vercel.app/api
For local development: 
http://localhost:3000/api

​
Authentication

All endpoints require JWT authentication except where noted. Include your token in the Authorization header: 
Authorization: Bearer YOUR_JWT_TOKEN

Get Started with Authentication

Learn how to obtain and use JWT tokens for API access

​
Request/Response Format

​
Content Type

All requests and responses use JSON: 
Content-Type: application/json

​
Request Format

curl -X POST "https://harbor-parking.vercel.app/api/parking-spots" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "spot_number": "A-15",
    "location": "Level 2 Parking Garage"
  }'

​
Response Format

{
  "spot": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "spot_number": "A-15",
    "owner_id": "456e7890-e89b-12d3-a456-426614174001",
    "building_section": "Level 2 Parking Garage",
    "is_verified": false,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

​
HTTP Status Codes

The API uses standard HTTP status codes:
  • 200 OK - Request successful
  • 201 Created - Resource created successfully
  • 400 Bad Request - Invalid request data or validation errors
  • 401 Unauthorized - Missing or invalid authentication token
  • 403 Forbidden - Insufficient permissions or account not approved
  • 404 Not Found - Resource not found
  • 409 Conflict - Resource already exists or conflicts with existing data
  • 500 Internal Server Error - Unexpected server error

​
Error Response Format

All errors follow a consistent format: 
{
  "error": "Validation failed",
  "details": {
    "spot_number": {
      "_errors": ["Spot number is required"]
    }
  }
}
The API uses standard HTTP status codes to indicate the success or failure of requests. See the error examples in each endpoint documentation for details.

​
Rate Limiting

API requests are rate limited to ensure fair usage:
  • 100 requests per minute per authenticated user
  • 1000 requests per hour per authenticated user
  • Rate limit headers included in responses:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

​
API Endpoints Overview

​
Profile & Authentication

Manage user profiles and authentication

Get Profile

Retrieve authenticated user’s profile

Update Profile

Update user profile information

​
Dashboard

Get comprehensive dashboard data

Get Dashboard

Retrieve user dashboard with stats, spots, and claims

​
Parking Spots

Manage parking spot registration and ownership

List Spots

Get parking spots with filtering

Create Spot

Register a new parking spot

Update Spot

Update parking spot details

Delete Spot

Remove a parking spot

​
Availabilities

Manage parking spot availability windows

List Availabilities

Get availability windows with filtering

Create Availability

Set spot availability window

Update Availability

Modify availability details

Delete Availability

Remove availability window

​
Claims

Manage parking spot reservations

List Claims

Get claims with filtering options

Create Claim

Claim an available parking spot

Update Claim

Update claim status or details

Delete Claim

Cancel a parking spot claim

​
OpenAPI Specification

OpenAPI Specification

Complete machine-readable API specification in OpenAPI 3.0 format

​
Interactive Playground

Try API endpoints directly in your browser with live data:
The interactive playground requires a valid JWT token. Obtain one by logging into the Harbor Parking web application.

​
Webhooks (Coming Soon)

Real-time notifications for parking events:
  • New spot registrations
  • Availability changes
  • Claim submissions and updates
  • Admin approvals

​
Need Help?

Quickstart Guide

Get up and running in 5 minutes

Community Support

Connect with other developers

Report Issues

Bug reports and feature requests