Configuration as Code

PickLayer applications can be described entirely as YAML and managed like source code. Export your current configuration, commit it to a repository, edit it, preview what will change, and apply it — with full version history and one-command rollback.

What is configuration as code?

Every meaningful piece of an application’s setup — providers, models, billing plans, relay connectors, quota plans, notification automations, email templates — can be serialized to a single YAML file. You can:

• Export the current state to capture a baseline.
• Diff a proposed YAML against live state before touching anything.
• Import to apply changes atomically, creating an audited version record each time.
• Roll back to any prior version with a single API call.

This makes promotion across environments (dev → staging → prod), disaster recovery, and team-based review workflows tractable without clicking through a console.

YAML schema

The full field-by-field reference is in CONFIG_FILE_SCHEMA.md. A minimal skeleton looks like:

version: '1.0'
application:
  name: My App
  description: Customer-facing chat
 
providers:
  - preset_id: openai
    name: OpenAI production
    fields:
      apiKey: "{{REDACTED}}"   # fill in before import
 
models:
  - model_string: openai/gpt-4o
    name: GPT-4o
    enabled: true

Secrets exported via the API are replaced with {{REDACTED}} placeholders. Fill in real values (or use environment variable substitution in your CI pipeline) before importing.

Workflows

Capture a baseline

# Exchange your secret key for an org token
TOKEN=$(curl -s https://api.picklayer.ai/v1/graphql \
  -H 'Content-Type: application/json' \
  -H 'x-hasura-role: public' \
  -d '{"query":"mutation { ExchangeSecretKey(secretKey: \"sk_live_...\") { data { organizationToken } } }"}' \
  | jq -r '.data.ExchangeSecretKey.data.organizationToken')
 
# Export the current configuration
curl -sS "https://api.picklayer.ai/config/export?application_id=<app-uuid>" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -r '.yaml' > app-config.yaml

Preview changes before applying

curl -sS -X POST "https://api.picklayer.ai/config/diff" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"application_id\": \"<app-uuid>\", \"yaml_content\": $(cat app-config.yaml | jq -Rs .)}"

The response breaks down creates, updates, and deletes per entity type so you can review exactly what will change.

Dry-run an import

Pass "dry_run": true to the import endpoint to verify the full import pipeline (parse, validate, diff) without writing anything:

curl -sS -X POST "https://api.picklayer.ai/config/import" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"application_id\": \"<app-uuid>\", \"yaml_content\": $(cat app-config.yaml | jq -Rs .), \"dry_run\": true}"

Apply to production

curl -sS -X POST "https://api.picklayer.ai/config/import" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"application_id\": \"<app-uuid>\", \"yaml_content\": $(cat app-config.yaml | jq -Rs .)}"

A successful import returns a version_id. Store this in your deployment metadata so you can roll back to it precisely.

Roll back

curl -sS -X POST "https://api.picklayer.ai/config/rollback" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"application_id": "<app-uuid>", "version_id": "<target-version-uuid>"}'

Rollback re-imports the YAML stored in the target version, creating a new version record. The historical version is preserved unchanged.

REST endpoint summary

All endpoints use the builder API base (https://api.picklayer.ai) and require Authorization: Bearer <org-token>.

For full request/response shapes, see §12.5 of the Builder API Reference.

Version history

Every import and rollback creates a version record with:

• version_number — monotonically increasing integer
• status — pending → active (or failed); prior active version moves to superseded
• applied_at, applied_by — timestamp and actor ID for audit
• changes_summary — count of creates, updates, and deletes
• yaml_content — the full YAML that was applied (preserved for rollback)

Browse history with GET /config/versions?application_id=<id> and inspect any version with GET /config/versions/:version_id.

Sync mode vs. default mode

By default, import only creates and updates entities — it never deletes. This is safe for partial updates (you can import a YAML that only describes a subset of your entities and existing entities not mentioned are untouched).

Pass "sync_mode": true to enable deletion of entities that are present in the live state but absent from the imported YAML. Use sync mode when you want the live state to exactly match the file.

Notes

• Secrets in exported YAML are always {{REDACTED}}. You must supply real values (or reference environment secrets in your CI) before re-importing.
• Large imports (many entity changes) include a partial_failure_warning in the response. If an error occurs mid-import, some changes may have been applied while others were not. Review the response changes array and the audit log.
• The import endpoint has a 2 MB body limit to accommodate large YAML files.
• Rate limits: export/diff/versions = 60 req/min; import/rollback = 10 req/min per application.