Cowdidocs
API ReferenceAPI version

Roll back the organization's last API version upgrade

POST
/v1/organizations/{organizationId}/version/rollback

Returns the organization to the version its last upgrade replaced, at once. A rollback is possible for 72 hours after the upgrade. Requires the org:connect:write permission on the organization. Returns 409 API_VERSION_ROLLBACK_UNAVAILABLE when there is no upgrade to roll back or the 72 hours have passed.

Authorization

oauth2
AuthorizationBearer <token>

Create a client with POST /v1/oauth/clients, then exchange its credentials for an access token. AUTHORIZATION_CODE clients act on behalf of a signed-in user and always use PKCE; CLIENT_CREDENTIALS clients act as themselves. A client may only be granted scopes its creator already holds — read the grantable list from GET /v1/oauth/clients/scopes.

In: header

Path Parameters

organizationId*string

Unique identifier of the organization.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/organizations/greenwheels/version/rollback"
{  "version": "2026-09-17",  "latest": "2026-09-17",  "rollback_to": "2026-09-17",  "rollback_expires_at": "2026-09-20T09:12:00Z",  "available": [    {      "version": "2026-09-17",      "summary": "Retires the routes renamed in the API naming review."    }  ]}
{  "code": "BAD_REQUEST",  "description": "Bad Request"}
{  "code": "UNAUTHORISED",  "description": "Unauthorised"}
{  "code": "FORBIDDEN",  "description": "Forbidden"}
{  "version": "2026-09-17",  "latest": "2026-09-17",  "rollback_to": "2026-09-17",  "rollback_expires_at": "2026-09-20T09:12:00Z",  "available": [    {      "version": "2026-09-17",      "summary": "Retires the routes renamed in the API naming review."    }  ]}
{  "code": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}
{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

Get the organization's API version GET

Returns the version the organization's requests run on when they send no `Cowdi-Version` header, the latest version, the rollback that is still possible, and every released version. Requires the `org:connect:read` permission on the organization. A request can run on another version for one call with the `Cowdi-Version` header.

Upgrade the organization to the latest API version POST

Moves the organization to the latest version at once. From then on, requests without a `Cowdi-Version` header run on it, and routes retired in it answer `410`. The version it replaced stays available for a rollback for 72 hours. An organization already on the latest version stays as it is. Requires the `org:connect:write` permission on the organization. Test the latest version first by sending it in the `Cowdi-Version` header.