Getting started with the Configly API – Configly Help Centre

Overview

The Configly API gives you programmatic access to your Zendesk configuration data. You can list connections, browse synced config items, run health checks, simulate changes with What-If analysis, push changes to Zendesk, manage GitHub sync, and subscribe to webhook notifications.

This guide walks you through making your first API call. It takes about five minutes.

Base URL

All API requests use this base URL:

https://api.configly.app/v1

Every response includes an X-API-Version: v1 header confirming you reached the v1 surface.

Authentication

Every request must include an API key as a Bearer token:

Authorization: Bearer cly_your_key_here

API keys start with the cly_ prefix and are scoped to a single Zendesk connection. To generate a key, see How to generate and manage API keys.

Making your first request

Generate an API key

Open Settings > API Keys in your Configly connection and create a read-only key. Copy the full key value.

List your connections

curl -H "Authorization: Bearer cly_your_key" \
  https://api.configly.app/v1/connections

Read the response

{
  "data": [
    {
      "id": "clx1abc...",
      "subdomain": "yourcompany",
      "authMethod": "oauth",
      "status": "active",
      "lastSyncAt": "2026-04-15T09:30:00.000Z",
      "configCounts": {
        "triggers": 47,
        "automations": 12,
        "macros": 89
      },
      "createdAt": "2026-01-10T14:00:00.000Z",
      "updatedAt": "2026-04-15T10:00:00.000Z"
    }
  ]
}

The id field is your connection identifier. Use it in all subsequent API calls.

Response format

All successful responses use one of two envelopes:

Single object

{
  "data": { ... }
}

Paginated list

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 127,
    "totalPages": 3
  }
}

Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Query parameter \"q\" is required",
    "status": 400
  }
}

For all error codes, see Error codes reference.

Pagination

List endpoints accept page and limit query parameters. The default page size is 50, with a maximum of 100. The meta object in the response tells you how many pages exist.

curl -H "Authorization: Bearer cly_your_key" \
  "https://api.configly.app/v1/connections/{id}/configs/triggers?page=2&limit=25"

Common response headers

Header	Description
`X-API-Version`	Always `v1`. Confirms which API surface handled the request.
`X-RateLimit-Limit`	Your hourly request budget.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp when the oldest request in the window expires.
`Retry-After`	Seconds to wait before retrying (present on 429 responses only).
`X-Idempotent-Replay`	`true` when the response is a cached replay of a previous idempotent request.

Next steps

Note

This guide only scratches the surface. Each API Reference article covers one topic in depth, with full request and response examples.

How to generate and manage API keys for key lifecycle, security, and IP allowlisting.
Rate limits and usage quotas for per-tier limits and best practices.
Connections, Config items, Search for reading your Zendesk configuration.
Dependency graph and ID resolver for understanding relationships.
Snapshots and diff for comparing configuration versions.
Running health checks for automated configuration analysis.
Virtual changes, Impact analysis, and AI analysis for What-If simulation.
Apply changes and Rollback for pushing changes to Zendesk.
GitHub status and sync and Drift commits and exclusions for version control.
Webhooks API and Webhook event types for real-time notifications.
Error codes reference for the full list of error codes and their meanings.

Related to