API Reference
Agent Features

Agent Features

These endpoints are designed specifically for AI agents and automation workflows. They enable config validation, simulation, change tracking, and migration -- capabilities that are only possible because of the API-first architecture.

Validate Config

POST /v1/projects/:id/validate

Validates the entire project configuration. Returns errors (blocking issues that would prevent correct behavior) and warnings (non-blocking suggestions for improvement).

Example

curl -X POST https://agentwallie.com/api/v1/projects/PROJECT_ID/validate \
  -H "Authorization: Bearer sk_your_private_key"

Response 200 OK

{
  "valid": false,
  "errors": [
    {
      "type": "missing_paywall",
      "message": "Campaign 'Onboarding Flow' audience 'Free Users' references paywall 'pw_deleted' which does not exist",
      "path": "campaigns[0].audiences[0].experiment.variants[0].paywallId"
    }
  ],
  "warnings": [
    {
      "type": "unpublished_paywall",
      "message": "Paywall 'Draft Design' is referenced in an active campaign but has status 'draft'",
      "path": "paywalls.pw_draft123"
    },
    {
      "type": "no_audiences",
      "message": "Campaign 'Summer Sale' has no audiences configured",
      "path": "campaigns[1]"
    }
  ]
}

Dry-Run Simulation

POST /v1/projects/:id/dry-run

Simulate which paywall a hypothetical user would see for a given placement. Returns the full evaluation path: campaign, audience, experiment, variant, and paywall.

Request Body

FieldTypeRequiredDescription
user_attributesobjectYesSimulated user attributes (e.g., { "plan": "free", "age": 25 })
placement_namestringYesPlacement to evaluate (e.g., "app_launch")
device_infoobjectNoSimulated device info (e.g., { "platform": "ios" })
entitlementsstring[]NoUser's current entitlements
frequency_stateobjectNoSimulated frequency state

Example

curl -X POST https://agentwallie.com/api/v1/projects/PROJECT_ID/dry-run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_your_private_key" \
  -d '{
    "user_attributes": {
      "subscription_status": "free",
      "session_count": 5,
      "seed": 42
    },
    "placement_name": "feature_gate",
    "device_info": {
      "platform": "ios",
      "os_version": "17.2"
    }
  }'

Response 200 OK

{
  "matched": true,
  "evaluation_path": {
    "campaign": {
      "id": "camp_abc123",
      "name": "Feature Gate Campaign"
    },
    "audience": {
      "id": "aud_001",
      "name": "Power Users"
    },
    "experiment": {
      "id": "exp_001",
      "variant": {
        "id": "var_002",
        "paywallId": "pw_premium"
      }
    },
    "paywall": {
      "id": "pw_premium",
      "name": "Premium Upgrade",
      "version": 3
    }
  },
  "filters_evaluated": [
    { "field": "user.subscription_status", "operator": "is", "value": "free", "result": true },
    { "field": "device.session_count", "operator": "gte", "value": 5, "result": true }
  ]
}

Dry-run is particularly useful for agents that want to verify campaign configurations before deploying. Test different user profiles to ensure the right paywalls show to the right users.

Changelog

GET /v1/projects/:id/changelog

Returns the history of configuration changes for a project.

Query Parameters

ParameterTypeDescription
limitnumberMax entries to return (default 50)
offsetnumberEntries to skip for pagination

Example

curl "https://agentwallie.com/api/v1/projects/PROJECT_ID/changelog?limit=10" \
  -H "Authorization: Bearer sk_your_private_key"

Response 200 OK

{
  "entries": [
    {
      "id": "log_001",
      "action": "paywall.published",
      "entityType": "paywall",
      "entityId": "pw_abc123",
      "timestamp": "2025-03-15T10:30:00.000Z",
      "details": { "version": 3, "name": "Premium Upgrade" }
    },
    {
      "id": "log_002",
      "action": "campaign.updated",
      "entityType": "campaign",
      "entityId": "camp_abc123",
      "timestamp": "2025-03-15T10:25:00.000Z",
      "details": { "changes": { "status": { "from": "inactive", "to": "active" } } }
    }
  ],
  "total": 47,
  "limit": 10,
  "offset": 0
}

Diff Config

POST /v1/projects/:id/diff-config

Compare the current project config against a proposed config. Returns a list of additions, modifications, and removals.

Request Body

FieldTypeRequiredDescription
proposed_configobjectYesThe proposed configuration to compare against current

Example

curl -X POST https://agentwallie.com/api/v1/projects/PROJECT_ID/diff-config \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_your_private_key" \
  -d '{
    "proposed_config": {
      "campaigns": [
        {
          "id": "camp_abc123",
          "name": "Onboarding Flow v2",
          "status": "active"
        }
      ]
    }
  }'

Response 200 OK

{
  "changes": [
    {
      "path": "campaigns[0].name",
      "from": "Onboarding Flow",
      "to": "Onboarding Flow v2"
    },
    {
      "path": "campaigns[0].placements",
      "from": [{ "name": "onboarding_complete" }],
      "to": null
    }
  ]
}

Compile Config

POST /v1/projects/:id/compile-config

Compiles the project configuration into the optimized format delivered to SDKs. Use this to preview exactly what the SDK will receive, or to generate a static config for offline/embedded use.

Query Parameters

ParameterTypeDescription
formatstringOutput format: json (default) or plist

Example

curl -X POST https://agentwallie.com/api/v1/projects/PROJECT_ID/compile-config \
  -H "Authorization: Bearer sk_your_private_key"

Response 200 OK

{
  "compiled_at": "2025-03-15T10:30:00.000Z",
  "version": 12,
  "config": {
    "campaigns": [...],
    "paywalls": [...],
    "products": [...]
  }
}

The compiled config is the same payload the SDK fetches at runtime. Use this endpoint to inspect or cache the config for CI pipelines and automated testing.

Superwall Migration

POST /v1/projects/:id/duplicate-from-superwall

Import a Superwall-compatible configuration into AgentWallie. Accepts campaigns, paywalls, and products and creates them in the project.

Request Body

FieldTypeRequiredDescription
campaignsarrayNoSuperwall campaign objects to migrate
paywallsarrayNoSuperwall paywall objects to migrate
productsarrayNoSuperwall product objects to migrate

Example

curl -X POST https://agentwallie.com/api/v1/projects/PROJECT_ID/duplicate-from-superwall \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_your_private_key" \
  -d '{
    "campaigns": [
      { "name": "My Superwall Campaign", "placements": ["app_launch"] }
    ],
    "paywalls": [
      { "name": "Original Paywall", "components": [] }
    ],
    "products": [
      { "name": "Annual Pro", "store_product_id": "com.app.annual_pro" }
    ]
  }'

See the Migration Guide for a detailed walkthrough.

WebhooksDebugging