GiGi Developer Portal

Why two namespaces?

We split the API into two separate URL namespaces:

• /api/v1/* — internal, used by the GiGi web app and mobile app. We change shapes freely; do not depend on these.
• /api/v2/public/* — the public, partner-facing API. Stable response shapes, semantic versioning, and a deprecation policy.

Stability promise (v2)

Within a major version (v2.x), we will only add fields, query params, and event types. Breaking changes — removing fields, renaming endpoints, changing types — happen in a new major version (v3) and the previous major continues to operate during a deprecation window.

Deprecation window

When we plan to retire a major version we commit to:

• ≥ 90 days notice at the top of every response (Deprecation header)
• An email to the contact on every active API key
• A migration guide on this page describing every shape change between the current and next major version

We do not currently issue surprise deprecations. If we need to break a v2 endpoint sooner because of a security or compliance requirement, we will say so explicitly with the reason.

Version surfacing

Every /api/v2/public/* response includes api_version: "v2" at the top level. Use it to double-check you are calling the version you think you are.

What "v0" means in our changelog

The platform itself is at v0 — we are still adding endpoints, tightening rate limits, and expanding the event catalog. The v2 in the URL is the API contract; the v0 in our changelog is the maturity of the platform shipping behind that contract. Once we cut v1 of the platform we will keep /api/v2/public/* stable per the deprecation policy above.