Enriching your first feed

This guide walks through your first enrichment run: what to prepare, how to call the API, how to read the result, and how to scale up.

What enrichment does

You send existing product data (titles, descriptions, images, categories) and ACE:

• Derives contextual rules for the category, so output is grounded rather than generic. See Contextual Enrichment Engine.
• Generates the content types you ask for: descriptions, meta tags, JSON-LD schema, IRL scenario cards, internal links.
• Produces channel-ready field sets for Google Shopping, Agentic Commerce, Microsoft, and Shopify.

Cost: products × content types. Check first with GET /api/v1/usage. See Credits and usage.

What you need

• An API key with enrichment:write (or admin). Create one under Settings, Developer console, Keys. Start with an ace_test_ key: it is free.
• A small set of products, two to five to begin with. Each needs at least id and title. The more real fields you send (images, category, brand, price), the better the output.

export ACE_API_KEY=ace_test_your_key_here

Step 1: Prepare a payload

{
  "source": {
    "type": "inline",
    "products": [
      {
        "id": "prod-1",
        "title": "Wireless Bluetooth Headphones",
        "description": "Noise cancelling, 20h battery.",
        "category": "Audio",
        "brand": "Acme",
        "price": 129.99
      },
      {
        "id": "prod-2",
        "title": "USB-C Charging Cable",
        "description": "Fast charge, 2m length.",
        "category": "Accessories",
        "brand": "Acme",
        "price": 14.99
      }
    ]
  },
  "contentTypes": ["product-description", "meta-tags"]
}

Save it as products.json.

Step 2: Run the pipeline

curl -s -X POST https://ace.authoritas.com/api/v1/enrichment/pipeline \
  -H "Authorization: Bearer $ACE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-run-1" \
  -d @products.json

pipeline derives the rules and then generates content against them, so it is the right entry point for a first run. The Idempotency-Key means a retry resumes this run instead of paying for a second one.

With the CLI the same call is ace pipeline -f products.json.

Step 3: Read the response

200 means the set was small enough to run inline, and the body holds the enriched products.

202 means it became a durable job:

{ "data": { "id": "job_01H...", "status": "queued", "kind": "pipeline" } }

Poll it, or wait for it in one command:

curl https://ace.authoritas.com/api/v1/jobs/job_01H... \
  -H "Authorization: Bearer $ACE_API_KEY"

# or, with the CLI
ace jobs wait job_01H...

Then page through the per-product output:

ace jobs results job_01H... --page-size 100 > enriched.json

Other statuses:

Step 4: Scale up

• Bigger batches. Send more products in source.products. Anything sizeable becomes a job automatically, so no request sits open for minutes.
• Reuse rules. Enriching many batches in one category? Call /enrichment/rules once, keep the result, and pass it as rules on each /enrichment/content call. Cheaper and more consistent.
• Connected stores. With Shopify or WooCommerce connected, swap the inline source for { "type": "store", "storeId": "...", "writeBack": true } and ACE reads the products and writes results back.
• Stop polling. Subscribe to enrichment.job.succeeded and let ACE call you. See Webhooks.

Quick reference

For full schemas see the API Reference and Contextual Enrichment Engine.