Compatibility

Version 1 of the Steve API (/api/v1) and its webhook payloads change only by adding things. An integration that works today keeps working when Steve ships new features.

What can change in v1

Steve may, without notice:

• add endpoints and webhook event types
• add optional request fields and query parameters
• add fields to responses and webhook payloads
• add values to response enums, such as a new submission status or session state
• add headers to responses

Steve does not, within v1:

• remove or rename an endpoint, field, parameter, enum value or webhook event type
• make an optional request field required, or add a new required one
• change the type or meaning of an existing field
• stop sending a field that a response or webhook payload documents as required

A rename happens in two steps. Steve adds the new name next to the old one and marks the old one deprecated: true in the API reference. The old name keeps working for the life of v1. Deprecated items are listed in the reference so you can migrate when convenient.

What your client must tolerate

Write clients as tolerant readers:

• Ignore unknown fields. A response or webhook payload can contain fields your code does not know. Do not reject the message, and do not fail strict schema validation on extra keys. Some schemas in the reference say additionalProperties: false; read that as "these are all the fields today", not as a promise that no field will be added.
• Tolerate unknown enum values. Map a status, state or event type you do not recognize to a safe default (for example "unknown, check later") instead of throwing.
• Ignore unknown webhook event types. Acknowledge them with a 2xx response so Steve does not retry them.
• Send only documented request fields. Requests stay strict: an unknown field can be rejected with 422.

Breaking changes

When a breaking change is unavoidable, it is announced in the API changelog with the affected endpoints, the reason and the migration steps. Steve's CI blocks breaking changes to the published contract unless one has been explicitly approved and recorded there.