Versioning

The Connect API is versioned in the URL path. The current version is v1, served under /api/v1. Your base URL already includes it:

https://givebear.io/api/v1

What stays stable within v1

While you are on v1, we treat these as a contract and will not change them in a breaking way:

• Resource URLs, HTTP methods, and status codes.
• Field names and types on responses (fields are snake_case).
• Error shapes: every error is { "error": { "type", "message" } } with a stable set of type values.
• Scope names and what each scope grants.
• Webhook event names and payload shape.

What we may add without a new version

Additive changes are not breaking, so they can ship at any time. Write your integration to tolerate them:

• New endpoints, new optional request fields, and new response fields.
• New values in an enum-like field (for example, a new webhook event type).
• New error type values.

Ignore response fields you do not recognize, and do not assume the set of enum values is closed.

Breaking changes

A change that removes or renames a field, changes a type, or changes existing behavior is breaking. Breaking changes ship under a new path version (for example, a future /api/v2), and v1 keeps working while you migrate. We announce breaking changes in the changelog before they take effect.

Check the version you are calling

The GET /openapi.json document describes the exact surface of the version you are calling. The @givebear/connect client always targets the version it was published for.