Changelog
Every public-facing change to the Park Graph API, agent surfaces, dashboard, billing, security perimeter, and developer docs since the v1 launch in October 2025. Newest first. Breaking changes are marked with a red badge — there is no fine print and no quiet deprecations.
OpenAPI spec v1.4.0 · Page generated April 2026. Machine-readable JSON: /llms-full.txt.
Stability contract
Park Graph follows a strict additive-only policy inside a major version. Anything that would break a v1 client lands under /api/v2/... with at least six months of overlap and a deprecation banner inside the v1 response body. We never change response shapes silently. If you depend on a field that does not appear in the OpenAPI spec, email developers@parkgraph.com and we will either promote it or warn you before it goes away.
Webhook contracts evolve on the same cadence: the v2 webhook envelope (HMAC-SHA256, deterministic event ids) replaced v1 in January 2026, and v1 endpoints continue to be delivered to until 2026-06-01. Operators on v1 webhooks were emailed individually and the migration is a single signature-verification helper swap.
Releases
Developer / AI / GEO documentation cluster ships (T6).
Every page under /developers/* now meets the 2,000-word documentation bar with a shared security-model, rate-limits, error-codes, and AI-agent-use-cases appendix.
Three new pages launched: /developers/openai-actions (full ChatGPT Actions tutorial), /developers/geojson (GeoJSON spec for /api/v1/lots.geojson and /api/v1/projection-sites.geojson), and /developers/changelog (this page).
Six GEO landing pages launched under /ai/* covering AI-agent parking booking, ChatGPT parking booking, MCP server for parking, parking data for AI agents, parking availability for AI search, and the best-of comparison page.
New machine-readable surfaces: /openapi.json, /.well-known/ai-plugin.json, /llms.txt, and /llms-full.txt — all served from a route handler so they stay in lockstep with shipped capabilities.
Realtime voice models (gpt-realtime, Gemini Live) supported in /api/v1/agents/openai/actions.
The agent dispatcher now accepts streamed tool-call deltas from realtime models. The contract is unchanged — the same action / parameters envelope works whether the upstream model is text or voice.
/developers/chatgpt and /developers/gemini both gained voice-only worked examples.
POST /api/v1/sessions/extend returns the new expected_end and an extended_count counter.
Drivers can extend an active session up to 24 hours in 30-minute increments. The previous response returned only a 200; we now return the full session shape so clients can update local state without a follow-up GET.
Existing clients see an additive change only — the response is a strict superset of v1.2.x.
/api/v1/lots/search supports `bbox=` in addition to `lat`+`lng`+`radius_km`.
Pass a bounding box as `bbox=west,south,east,north` (CSV of four floats) to fetch every lot inside a viewport. Useful for map-based discovery without first computing a center and radius.
Either `bbox` or `lat`+`lng` is required; supplying both is rejected with BAD_REQUEST.
API-key responses now include a `last_used_at` timestamp.
Operators asked for a way to retire dormant keys without guessing. /dashboard/api-keys and the corresponding management API both surface the timestamp of the last successful authentication.
Existing keys backfill from the audit log when first inspected.
MCP server v1.2.0 published with new search_parking_by_address tool.
`parkgraph-mcp` now ships a fourth tool that geocodes an address client-side and forwards the search to /api/v1/lots/search. Drops a step from the typical Claude Desktop conversation flow.
Geocoding uses a privacy-preserving local LRU cache; no new third-party calls are introduced.
Enterprise tier transaction take dropped from 5% to 3.3%.
Operators above $50k in monthly gross are charged a lower platform fee. Existing Enterprise contracts re-baseline automatically on the next billing cycle.
The change is reflected in /pricing and the Offer entries inside the SoftwareApplication JSON-LD on every page.
Real-time AI-agent attribution shows on the lot revenue chart.
Every paid session now carries an attribution tuple {agent_platform, agent_name, agent_session_id} when the booking arrived through an agent. The dashboard renders an overlay band so operators can see what fraction of revenue is coming from agentic distribution.
Attribution data is also surfaced via /api/v2/intelligence/agent-demand for analysis at the city level.
Webhooks v2: HMAC-SHA256 signing, 30-day replay window, deterministic id.
Webhook payloads are signed with the operator's webhook secret using HMAC-SHA256. The signature is in the `X-Park-Graph-Signature` header alongside a Unix timestamp; verify both before acting on the body.
Every event has a stable `id` of the form `evt_…` that is identical across retries. Idempotency is now the consumer's responsibility (see /developers/webhooks).
BREAKING: the legacy v1 webhook signature header (`X-Webhook-Sig`) is removed. Operators on v1 webhooks were emailed in December 2025; v1 endpoints will continue to be delivered to until 2026-06-01.
POST /api/v1/sessions accepts an optional `reservation_window` for pre-booked spots.
Reservation-style flows (event venue parking, hospital procedure visits) can now hold a spot for a window in the future. Park Graph charges only when the driver activates the session by scanning the QR code on arrival; unredeemed reservations release back to the pool 30 minutes after the window opens.
Public OpenAPI spec exposed at /api/agents/openai/openapi.yaml.
The same spec backs ChatGPT Actions, the Park Graph SDKs, and the public API reference. Versioning follows the API itself, so spec_version == api_version.
A JSON copy is now served at /openapi.json for tooling that does not parse YAML.
Public v1 API generally available.
/api/v1/lots/search, /api/v1/sessions, /api/v1/sessions/{id}, /api/v1/sessions/end, and /api/v1/health are now generally available with a documented stability contract.
Breaking changes within v1 will be additive only; truly breaking changes will live under /api/v2 with at least six months of overlap.
Subscribe
Three ways to track changes:
- • JSON feed: /llms-full.txt includes the full changelog at the bottom and is the easiest source for an agent or automated pipeline.
- • Email: any operator with an active API key gets release notes via transactional email. Manage subscriptions at /dashboard/notifications.
- • Status: /trust/status publishes uptime, incident history, and scheduled maintenance windows alongside the version that landed in production.
Rate limits
Limits are enforced per API key (or per IP for unauthenticated reads) using a rolling token bucket. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers; 429 responses additionally carry Retry-After. Bursts above the per-minute budget should be backed off with jitter — the official SDK does this automatically.
| Scope | Budget | Window |
|---|---|---|
| Public read endpoints (search, lot detail, health) | 120 requests | per IP per minute |
| Authenticated read endpoints (sessions, payouts, webhooks) | 600 requests | per API key per minute |
| Authenticated write endpoints (create / end / extend session, refunds) | 120 requests | per API key per minute |
| Sandbox endpoints (`pk_test_…` keys) | 30 requests | per key per minute |
Need a higher ceiling? Email developers@parkgraph.com with your projected throughput and we will lift the burst budget on a per-key basis.
Error codes
Every error response uses the same envelope: { "error": { "code": "…", "message": "…", "request_id": "req_…" } }. The HTTP status indicates the broad class; the code field disambiguates within a class. Surface the request_id to your support team — we can look up the full server-side trace by id alone.
| Code | HTTP status | Meaning |
|---|---|---|
| BAD_REQUEST | 400 | Required parameter missing or out of range. Response body lists the offending field. |
| UNAUTHORIZED | 401 | Missing or malformed Authorization header. Send `Authorization: Bearer pk_live_…`. |
| FORBIDDEN | 403 | API key is valid but the plan does not include this scope (e.g. agent or intelligence endpoints on Starter). |
| NOT_FOUND | 404 | Lot, session, or webhook id does not exist or has been deleted. |
| CONFLICT | 409 | Idempotent retry of a non-terminal session, or attempt to end an already-completed session. |
| RATE_LIMITED | 429 | Per-key burst budget exceeded. Inspect `Retry-After` and back off. |
| PAYLOAD_TOO_LARGE | 413 | Webhook delivery body or batch upload exceeds 1 MB. |
| INTERNAL | 500 | Unexpected server error. Park Graph automatically opens an incident and retries idempotent writes. |
| BAD_GATEWAY | 502 | Upstream payment processor returned an error. Safe to retry with the same idempotency key. |
Architecture
Every Park Graph request — whether it arrives from the API and developer surface, the dashboard, the QR-driven mobile checkout, or an agent — runs through the same Next.js Edge front door, hits the same Postgres-backed core, and shares the same audit log and webhook fan-out. There is no divergent code path between "agent traffic" and "human traffic": anything an agent can do, a human can do, and vice versa.
Sandbox & getting help
Every operator gets a sandbox key prefixed with pk_test_. Sandbox traffic uses Stripe test mode, synthetic lots, and never charges a real card. Spin one up at /developers/sandbox, then point your client at https://parkgraph.com/api/v1 exactly as you would in production.
For integration help, reach the developer team at developers@parkgraph.com or open an issue on the public GitHub org. Status and incident history live at /developers/changelog; subscribe to the JSON feed for machine-readable updates.