Developer Platform

OpenAPI, versioning, and SDKs

Keep the API reference, schemas, generated clients, and changelog synchronized from one canonical contract.

The Developer API is generated into a machine-readable OpenAPI 3 contract rather than maintaining endpoint prose, SDK methods, and validators independently. The current document describes 37 paths, 45 operations, and 37 component schemas.

Canonical artifacts

• OpenAPI for REST resources, authentication, errors, headers, pagination, and examples.
• JSON Schema for application objects, workflow actions, webhook events, MCP tool arguments, and container endpoint contracts.
• TypeScript connector SDK and validated quickstart/webhook examples mapped to current operation IDs.
• Future generated clients or collections must derive from the same reviewed contract rather than handwritten route lists.

Versioning

Breaking contract changes belong behind an explicit API version with a published migration path. Additive fields and new resource types can usually remain compatible, but clients should ignore response fields they do not recognize.

Deprecation

When an endpoint or field must be retired, the API reference should show its replacement, deprecation date, planned sunset date, and migration guide. Response headers can surface the same information programmatically.

One change, one source

A route change updates implementation annotations and regenerates the canonical OpenAPI/Schema definition. Documentation examples, SDK methods, MCP mappings, and contract tests are validated against operation IDs so they cannot quietly disagree.