Skip to main content
The Awardee API is versioned in the URL path. The current version is v1. There is no version header. There are no per-day or per-account version pins — every caller on /v1 sees the same surface at the same time.

​
Base URL

https://api.awardee.dev/v1
v1 is the only public version today. A future v2 will live at /v2 and run alongside /v1 until /v1 is retired.

​
Additive changes

These changes can ship to /v1 at any time, without notice. Your client must tolerate them:
  • New fields on response objects.
  • New optional fields on request bodies.
  • New endpoints, resources, or query parameters.
  • New values in open-ended string fields (e.g. a new destination.type).
  • New error details keys alongside existing ones.
  • New response headers.
  • New webhook event types. Subscribers receive only the events they explicitly enabled, so new types don’t break existing endpoints.
  • Wire-format changes that decode the same under a tolerant JSON parser — pretty-print whitespace, key ordering.
Write your client to ignore unknown fields. JSON parsers do this by default. Strict schemas (zod.strict(), Pydantic v2 with model_config = ConfigDict(extra="forbid"), etc.) will break when we add fields. Use forgiving variants.

​
Breaking changes

These ship only on a new major version (/v2, /v3, …):
  • Removing or renaming a field, endpoint, or query parameter.
  • Tightening a field’s type or accepted values (e.g. making an optional field required, narrowing an enum).
  • Changing an HTTP status code or error code for an existing condition.
  • Changing the shape of an existing response envelope or pagination format.
  • Removing an existing webhook event type.

​
Deprecation policy

When we plan to remove something:
1

Announcement

A removal is announced at least 6 months before it takes effect. Announcements go out by email to org owners and to the change log linked from the dashboard.
2

Deprecation headers

Affected endpoints start returning a Deprecation header (RFC 8594 date) and a Sunset header (the removal date) on every response. Affected webhook events ship with a deprecated: true field inside the payload metadata.
3

Dashboard surface

The dashboard’s API-key usage view flags keys that hit deprecated surface so you can find the integrations that need updating.
4

Removal

On the sunset date, the surface is removed. Calls return 410 gone with a Link header pointing at the replacement.
A removal that lives entirely inside /v1 is rare and reserved for security or compliance reasons — never for ergonomics. When it happens, the 6-month window still applies.

​
Major version retirement

When a major version is retired (e.g. /v1 after /v2 ships), the same policy applies but with a 12-month window. You will have at least a year, from the first /v2 GA release, before /v1 returns 410 gone.

​
How to track changes

  • Change log. Linked from the dashboard footer. Every additive change ships with a one-line note.
  • Deprecation headers. Log them. A Deprecation header in any response is the canonical signal that a part of your integration needs attention before its sunset date.
  • Email. Org owners receive an email when a sunset date is set or moved. Make sure at least one engineer is an owner on every org.
In production, alert on the presence of a Deprecation header in any API response. A single header in your logs is worth a thousand change-log emails.