Reference
Versioning & deprecation
/v1 of the Keyword-to-Blog API is a stable public contract. Every response shape documented in JSON schemas is versioned by that V1 suffix (GenerateResponseV1, JobV1, UsageResponseV1, ErrorResponseV1, WebhookPayloadV1) — the suffix is the version, not just a naming convention.
What counts as non-breaking
These changes can ship to /v1 at any time without a version bump:
- Adding a new optional request field.
- Adding a new optional response field.
- Adding a new error code for a genuinely new failure mode.
- Loosening a validation constraint (e.g. raising a length limit).
- Adding a new endpoint.
What counts as breaking
These require a new version (/v2) rather than an in-place change to /v1:
- Removing or renaming a request or response field.
- Changing a field’s type or meaning.
- Making a previously-optional field required.
- Changing an error code’s HTTP status mapping.
- Changing the webhook signature scheme or payload shape.
- Tightening a validation constraint in a way that would reject previously-valid requests.
Deprecation & sunset
When a field or endpoint is deprecated, it keeps working — deprecation is an announcement, not an immediate removal. A deprecated field is documented as such here and continues to be populated/accepted for a minimum communicated notice period before removal in a subsequent major version. Sunset timelines and migration guidance for any deprecated surface are published on this page.
Today
There is currently no /v2 and nothing on /v1 is deprecated. Recent changes were additive: for example, quality.qa was added to article responses. Two request fields, constraints.maxWords and constraints.minWords, are still accepted but no longer affect article length, and the limits.maxWordsPerRequest field of GET /v1/usage is reported but not enforced. This page exists so that changes, when they do happen, have a clear, pre-established policy to follow rather than being decided ad hoc.