Clients

API reference

A versioned JSON REST API at https://parkezy-api.onrender.com/v1. Every response, success or error, follows one contract, so clients handle the whole API the same way.

Endpoint groups#

/v1/host

22 routes

/v1/admin

15 routes

/v1/bookings

14 routes

/v1/me

11 routes

/v1/auth

10 routes

/v1/listings

3 routes

reviews · uploads · notifications · disputes · support

2 each routes

health · config · legal

4 routes

All 89 routes by group. Host tools and admin operations make up almost half of the surface; the driver flow itself is compact.

Group	Highlights
`/v1/auth`	register, login, Google sign-in, refresh, logout, verify email, forgot / reset / change password
`/v1/listings`	radius search with filters, listing detail, reviews (public, no sign-in needed)
`/v1/bookings`	quote, create (Idempotency-Key), list, cancel, access pass, check-out, extend, review, receipt (JSON and PDF), payment and confirm
`/v1/host`	listings and slots, photos, approve / reject, gate verification, dashboard, payout account, payouts
`/v1/me`	profile, become host, push tokens, notification preferences, favourites, delete account
`/v1/admin`	users, suspensions, disputes, payouts, platform settings, outbox dead letters
`/v1/uploads`	presigned upload, then complete (server checks size and type)
`/v1/config`	the live business rules the app uses: GST, booking limits, fees

Example: quote then book#

requesthttp

POST /v1/bookings/quote
Content-Type: application/json
{ "listing_id": "01a148ee-…", "starts_at": "2026-10-17T11:00:00Z", "ends_at": "2026-10-17T13:00:00Z" }

200 OK (values from a real test booking)json

{
  "listing_id": "01a148ee-…",
  "slot_id": null,
  "starts_at": "2026-10-17T11:00:00Z",
  "ends_at": "2026-10-17T13:00:00Z",
  "duration_minutes": 120,
  "hourly_rate": "45.00",
  "subtotal": "90.00",
  "tax_rate": "0.18",
  "tax_amount": "16.20",
  "total": "106.20",
  "currency": "INR",
  "payment_mode": "online",
  "requires_approval": false,
  "available": true
}

requesthttp

POST /v1/bookings
Authorization: Bearer <access token>
Idempotency-Key: 9f1c2b7e4d…          # same key again = same booking back
{ "listing_id": "01a148ee-…", "starts_at": "2026-10-17T11:00:00Z", "ends_at": "2026-10-17T13:00:00Z" }

Money is always a decimal string (never a float), times are ISO 8601 in UTC, and ids are UUIDv7: unique without coordination, and roughly time-ordered.

The error contract#

every error looks like thisjson

{
  "error": {
    "code": "slot_unavailable",
    "message": "This slot was just booked for that time",
    "details": null
  }
}

Status	Meaning	Example codes
400	Malformed request	invalid_characters (NUL byte)
401	Not signed in, or a bad token	not_authenticated, invalid_credentials, token_expired
403	Signed in but not allowed	not_a_host, email_not_verified, own_listing, challenge_required
404	Not found (also for things you may not see)	not_found
409	Conflicts with current state	slot_unavailable, no_availability, idempotency_mismatch, invalid_booking_transition
413	Body over 1 MiB	payload_too_large
422	Validation or a business rule failed; details explain	validation_failed, start_too_far
429	Rate limited; honour Retry-After	rate_limited
503	Temporarily unavailable; retry after Retry-After	database_busy, database_unavailable

Health and status#

readinesshttp

GET /health/ready
{ "status": "ok", "checks": { "database": "ok", "redis": "ok" } }

Interactive API docs (/docs) are switched off in production to keep the attack surface small; they are available in local and staging environments.