Automating with the Platform API

The CloudQuery Platform API gives you programmatic access to everything in the platform UI. This guide walks through common automation patterns: triggering syncs from a CI/CD pipeline, checking policy violations, provisioning users, and managing platform configuration as code.

For a full API overview, see Platform API. For interactive endpoint documentation, see the Interactive API Reference ↗.

Prerequisites

• A CloudQuery Platform deployment with at least one integration and sync configured
• An API key with the appropriate role for your use case (created in Organization Settings → API Keys)

Choosing the right API key role

Store API keys in a secrets manager (AWS Secrets Manager, HashiCorp Vault, GitHub Actions secrets) rather than in plaintext config files.

Triggering syncs from CI/CD

A common pattern is to trigger a sync at the end of a deployment pipeline so your cloud inventory stays current after infrastructure changes.

Trigger a sync and wait for completion

Syncs are identified by name. The following script triggers a run, captures the run ID, and polls until it completes or fails:

#!/bin/bash
RUN_ID=$(curl -s -X POST \
  -H "Authorization: Bearer $CLOUDQUERY_API_KEY" \
  "https://$PLATFORM_URL/api/syncs/$SYNC_NAME/runs" \
  | jq -r '.id')
 
echo "Sync run started: $RUN_ID"
 
while true; do
  STATUS=$(curl -s \
    -H "Authorization: Bearer $CLOUDQUERY_API_KEY" \
    "https://$PLATFORM_URL/api/syncs/$SYNC_NAME/runs/$RUN_ID" \
    | jq -r '.status')
 
  echo "Status: $STATUS"
 
  if [ "$STATUS" = "completed" ]; then
    echo "Sync completed successfully"
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Sync failed"
    exit 1
  fi
 
  sleep 30
done

Enforcing policies in CI/CD

Use the Platform API to check policy violations after a sync. This lets you fail a pipeline when violations are detected — for example, blocking a deployment if it would introduce a compliance violation.

#!/bin/bash
VIOLATIONS=$(curl -s \
  -H "Authorization: Bearer $CLOUDQUERY_API_KEY" \
  "https://$PLATFORM_URL/api/policies/$POLICY_ID/violations" \
  | jq '.total_violations')
 
echo "Policy violations: $VIOLATIONS"
 
if [ "$VIOLATIONS" -gt 0 ]; then
  echo "Policy check failed: $VIOLATIONS violation(s) found"
  exit 1
fi
 
echo "Policy check passed"

Managing configuration as code

Instead of clicking through the UI, define policies and syncs in scripts or IaC tooling and apply them via the API. This gives you version control, code review, and repeatable deployments.

Create a policy

curl -s -X POST \
  -H "Authorization: Bearer $CLOUDQUERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Public S3 Buckets",
    "description": "Detects S3 buckets with public access enabled",
    "query": "SELECT account_id, name, region FROM aws_s3_buckets WHERE bucket_policy_is_public = true"
  }' \
  "https://$PLATFORM_URL/api/policies"

List existing syncs

curl -s \
  -H "Authorization: Bearer $CLOUDQUERY_API_KEY" \
  "https://$PLATFORM_URL/api/syncs" \
  | jq '[.syncs[] | {name, status: .last_run_status}]'

For the full set of create/update endpoints for syncs, alerts, and reports, see the Interactive API Reference ↗.

Provisioning users programmatically

Automate user onboarding and offboarding instead of managing it through the UI. This is useful when integrating with an identity provider or HR system.

Add a user to the platform

curl -s -X POST \
  -H "Authorization: Bearer $CLOUDQUERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role": "general:read"
  }' \
  "https://$PLATFORM_URL/api/users"

List users

curl -s \
  -H "Authorization: Bearer $CLOUDQUERY_API_KEY" \
  "https://$PLATFORM_URL/api/users" \
  | jq '[.users[] | {email, role}]'

Remove a user

curl -s -X DELETE \
  -H "Authorization: Bearer $CLOUDQUERY_API_KEY" \
  "https://$PLATFORM_URL/api/users/$USER_ID"

Pulling audit logs into external systems

Export the audit log to feed into a SIEM, data warehouse, or compliance reporting tool. Use per_page and page to paginate through results:

#!/bin/bash
# Fetch the first 1000 audit log entries and write to a file
curl -s \
  -H "Authorization: Bearer $CLOUDQUERY_API_KEY" \
  "https://$PLATFORM_URL/api/audit-logs?per_page=1000&page=1" \
  | jq '.' > audit-log-$(date +%Y%m%d).json

Filter by time range using start_time and end_time:

curl -s \
  -H "Authorization: Bearer $CLOUDQUERY_API_KEY" \
  "https://$PLATFORM_URL/api/audit-logs?start_time=2024-01-01T00:00:00Z&end_time=2024-01-31T23:59:59Z"

Next steps

• Platform API — API overview, authentication, and categories
• API Keys — create and manage API keys
• Policies — write SQL-based compliance controls
• Alerts — configure notifications for policy violations
• Interactive API Reference ↗ — full endpoint documentation