Apply changes

Important

Apply endpoints push real changes to your live Zendesk instance. Always preview first and review the impact analysis before confirming.

Overview

The apply endpoints let you push virtual changes from Configly into your live Zendesk instance. A series of safeguards ensure that changes are reviewed and auditable before they reach production.

Safeguards

Every apply operation enforces the following protections:

#	Safeguard	Detail
1	READ_WRITE API key	Only API keys with `READ_WRITE` permission can call apply endpoints.
2	Write OAuth scope	The Zendesk connection must have been authorised with read and write OAuth scope.
3	Mandatory preview	The first apply per API key must be preceded by a successful `POST /v1/apply/preview`.
4	Change reason required	A `changeReason` field (minimum 10 characters) is mandatory on every apply request.
5	Idempotency-Key header	Supported on all write operations with a 24-hour deduplication window.
6	No force parameter	Drift detection cannot be bypassed via the API. If Configly detects that Zendesk config has changed since the last snapshot, the apply is rejected with a `409 CONFLICT`.

Preview changes

POST /v1/apply/preview

Performs a dry run of the apply operation and returns a preview of what would change. This call also satisfies the mandatory preview requirement for subsequent applies using the same API key.

Field	Type	Required	Description
`connectionId`	string	Yes	The Zendesk connection to preview
`changeIds`	string[]	No	Narrow the preview to specific virtual change IDs

curl -X POST https://api.configly.app/v1/apply/preview \
  -H "Authorization: Bearer cly_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "your_connection_id"
  }'

POST /v1/apply

Pushes all (or selected) virtual changes to your live Zendesk instance. You must have called POST /v1/apply/preview at least once before your first apply.

Field	Type	Required	Description
`connectionId`	string	Yes	The Zendesk connection to apply to
`changeReason`	string	Yes	Audit trail reason (minimum 10 characters)
`changeIds`	string[]	No	Apply only these virtual change IDs. Omit to apply all.

Headers

Header	Required	Description
`Idempotency-Key`	Recommended	A unique string to prevent duplicate applies within 24 hours

curl -X POST https://api.configly.app/v1/apply \
  -H "Authorization: Bearer cly_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-20260416-001" \
  -d '{
    "connectionId": "your_connection_id",
    "changeReason": "Deploy updated trigger conditions for Q2 routing rules"
  }'

Note

If the same Idempotency-Key is sent within 24 hours, the cached response is returned with an X-Idempotent-Replay: true header. The body fields are ignored on replay.

Apply a single change

POST /v1/apply/single/:virtualChangeId

Applies a single virtual change by its ID. The same safeguards apply: READ_WRITE key, write OAuth scope, mandatory preview, and a changeReason in the request body.

Parameter	Location	Description
`virtualChangeId`	URL path	The ID of the virtual change to apply
`changeReason`	Body	Audit trail reason (minimum 10 characters)

curl -X POST https://api.configly.app/v1/apply/single/vc_abc123 \
  -H "Authorization: Bearer cly_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "changeReason": "Apply single trigger update for priority routing"
  }'

Apply history

GET /v1/apply/history

Returns a paginated list of past apply operations for a connection. This is a read-only endpoint, so READ_ONLY permission is sufficient.

Parameter	Location	Required	Description
`connectionId`	Query	Yes	The Zendesk connection to query
`page`	Query	No	Page number (default 1)
`limit`	Query	No	Results per page (default 20, max 100)

curl "https://api.configly.app/v1/apply/history?connectionId=your_connection_id&page=1&limit=10" \
  -H "Authorization: Bearer cly_your_key"

Each history entry includes the operation ID, change reason, timestamp, and per-object results showing what was applied and whether each object succeeded.

Error codes

Status	Code	Description
400	`PREVIEW_REQUIRED`	You must call `POST /v1/apply/preview` before your first apply
400	`VALIDATION_ERROR`	Invalid request body, missing `changeReason`, or no changes to apply
401	`INVALID_API_KEY`	Missing or invalid API key
403	`WRITE_SCOPE_REQUIRED`	The API key does not have `READ_WRITE` permission
403	`FORBIDDEN`	The Zendesk connection does not have write OAuth scope
404	`NOT_FOUND`	Virtual change or connection not found
409	`CONFLICT`	Drift detected: Zendesk config has changed since the last snapshot
429	`RATE_LIMITED`	Too many requests. Check the `X-RateLimit-*` response headers.

To undo an apply, see Rollback. To create virtual changes, see Virtual changes.

Related to