API versions and changes
How the API version appears, which changes to expect inside a version, and where changes are announced.
How the version appears
The version is part of every path, right after /api:
Use app as the subdomain for a shared workspace, or your workspace's own
subdomain for a dedicated one (see Quickstart).
v1 is the only version. The path is the only place a version appears: there
is no version header or query parameter, and webhook deliveries carry no version
field.
Changes inside v1
Changes ship inside v1 without a new version number.
Additive changes
These can appear in v1 at any time:
- New endpoints.
- New optional request fields and query parameters.
- New fields in responses and in webhook bodies.
- New webhook events in
GET /api/v1/webhooks/events.
Build your integration so they do not break it:
- Ignore response and webhook fields you do not recognise.
- Do not fail when an optional field is missing from a response.
- Read webhook event names from
GET /api/v1/webhooks/eventsinstead of hard-coding the list.
Requests are strict
Most endpoints reject a body field or query parameter they do not declare, and
answer 422. Send only the parameters the
API reference lists for the endpoint.
Breaking changes
A change that removes or renames an endpoint or a field, or changes the shape of
an existing value, can break a working integration. Changes of this kind have
shipped inside v1. The API changelog marks each one
Breaking.
Deprecated endpoints
These endpoints still work and each has a replacement. No removal date is set.
| Deprecated | Use instead |
|---|---|
GET /api/v1/object/data/select-options/:objectSlug | GET /api/v1/object/data/select-options/:objectSlug/:fieldSlug, which returns one field's options a page at a time |
GET /api/v1/object/field/select/:objectSlug | GET /api/v1/object/field/active/:objectSlug?types=select,status,priority |
Where changes are announced
- API changelog: dated changes to the endpoints an API key or OAuth token can reach, their request and response fields, webhooks, and authentication.
- Release notes: what each Corteksa release contains.