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 June 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
GET /api/v1/lots.geojson now accepts an optional ?bbox= viewport filter.
Map renderers can fetch only the lots inside the current viewport instead of the full dataset on every pan or zoom. Pass `?bbox=west,south,east,north` (four floats in GeoJSON lon/lat axis order) and the FeatureCollection is filtered to that box.
Latitudes must satisfy south ≤ north; a box that crosses the antimeridian (west > east) is supported. Omitting `bbox` keeps the existing behavior of returning all listed, active lots, so the change is fully backwards compatible.
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/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.
GET /api/v1/lots.geojson ships a public GeoJSON feed of all listed, active lots.
Fetch every listed, active lot as an RFC 7946 FeatureCollection — ideal for map-based discovery in Mapbox GL, Leaflet, QGIS, or geopandas without first computing a center and radius.
Each Feature carries the lot id, name, slug, address, total_spaces, lot_type, feature tags, and a url. Responses are cached with `Cache-Control: public, max-age=300`.
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 four tools and a docs resource.
`parkgraph-mcp` ships four tools — search_parking, create_parking_session, check_session_status, and end_parking_session — each a thin wrapper around the equivalent /api/v1 REST endpoint with type-safe inputs and structured outputs.
It also advertises one resource, parkgraph://docs/overview, a Markdown summary of the platform's API, authentication, and coverage for Claude Desktop and other MCP clients.
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} 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 and deterministic event id.
Webhook payloads are signed with the operator's webhook secret using HMAC-SHA256. The signature is delivered in the `X-Park-Graph-Signature` header as `sha256=<hex>`; recompute the HMAC over the raw request body and compare before acting on it.
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/reserve places an idempotent hold for pre-booked spots.
Reservation-style flows (event venue parking, hospital procedure visits) can describe what they need in a single `intent` string; Park Graph parses it, resolves a matching lot, and atomically places a short-lived hold. Every call must carry an `Idempotency-Key` header so retries are safe. Park Graph charges only when the driver activates the session on arrival; unredeemed holds release back to the pool when the hold's TTL expires.
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.