Versioning
The public API uses the /api/v1 path. The OpenAPI info.version identifies the published contract revision, while /api/v1 identifies the compatibility line. Clients should pin the OpenAPI revision used to generate or validate their integration and review the Changelog before each production release.
Compatibility rules
| Change | Expected client action |
|---|---|
| New endpoint or optional request field | No immediate change. Adopt it when useful. |
| New response field | Ignore unknown fields and continue processing known fields. |
| New enum or status value | Preserve and display the raw value. Do not fail parsing or trigger an irreversible action. |
| New validation rule | Read the returned field errors, correct the request, and rerun readiness checks. |
| Deprecated field or operation | Move to the documented replacement before the published removal date. |
| Breaking request, response, auth, or behavior change | Follow the migration guide and before-and-after example published before the change reaches production. |
Clients must not depend on response property order, undocumented fields, dashboard routes, numeric record references, or values that appear only in one example.
Deprecation notices
A deprecation notice states the affected operation or field, customer impact, replacement, migration action, announcement date, and removal date. When applicable, responses can also include standard Deprecation, Sunset, and Link headers. Treat those headers as operational alerts and surface them in integration monitoring.
SpaceMedia does not silently repurpose an existing field with a different meaning. A change that cannot remain compatible requires a migration guide before release.
Changelog review
The public changelog includes customer-visible API additions, behavior changes, authentication or capability changes, error and rate-limit changes, webhook event changes, deprecations, and migrations. Weeks containing only internal maintenance are omitted.
Before upgrading a generated client:
- Download the current OpenAPI contract.
- Compare it with the revision pinned by your build.
- Review changelog entries between the two revisions.
- Regenerate the client and inspect the diff.
- Run contract, staging, retry, upload, webhook, and end-to-end release tests.
- Promote the same tested client build to production.
Report an unexpected change
Provide the method and path, timestamp with timezone, public resource reference, expected contract revision, sanitized response, and request correlation information when available. Never send credentials, bearer tokens, signing secrets, payment details, or customer files.
Common questions
How much notice do I get for a breaking change? Breaking changes are announced with a migration path and sunset information. Compatible additions can ship at any time, so clients must tolerate new fields and values.
What counts as a compatible addition? New optional request fields, new response fields, new enum values, and new operations. None of these should break a correctly written client.
Where do I track changes? The Delivery API changelog, which also has a feed you can subscribe to.
I found undocumented behavior. What should I do? Report it rather than depending on it. Undocumented behavior is not part of the contract and can change without notice.
Was this page helpful?