Generating content at scale

This guide covers generating content for many products: how to batch, how to reuse contextual rules so tone stays consistent, and how to stay inside your rate limit and budget.

Pipeline or content?

Both live in the Contextual Enrichment Engine.

• POST /api/v1/enrichment/pipeline derives rules and then generates content in one call. Best for a first run, or a scheduled refresh where the catalog has changed.
• POST /api/v1/enrichment/content generates content against rules you already hold. Best when you are working through a catalog in batches, because you generate the rules once instead of once per batch.

Both cost products × content types.

Reuse rules across batches

This is the single biggest lever for both consistency and cost.

# 1. Derive rules once, from a representative sample of the category.
curl -s -X POST https://ace.authoritas.com/api/v1/enrichment/rules \
  -H "Authorization: Bearer $ACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":{"type":"inline","products":'"$(cat sample.json)"'}}' \
  > rules.json

# 2. Reuse them for every batch in that category.
for batch in batches/*.json; do
  jq --slurpfile r rules.json \
     '{source:{type:"inline",products:.},contentTypes:["product-description","meta-tags"],rules:$r[0].data}' \
     "$batch" \
  | curl -s -X POST https://ace.authoritas.com/api/v1/enrichment/content \
      -H "Authorization: Bearer $ACE_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $(basename "$batch")" \
      -d @-
done

Sample per category, not per catalog. Rules describe a category's buying behaviour, so mixing unrelated categories into one sample produces vaguer rules.

Batch sizing and jobs

Anything beyond a small inline set returns 202 with a job envelope, so a long run never sits on an open connection. You do not need to tune this: send natural batches (a few hundred products) and let the engine decide. Force the behaviour with "mode": "async" or "mode": "sync" if you need to.

Track the work with the jobs endpoints:

ace jobs list --status running
ace jobs wait <id>
ace jobs results <id> --page-size 200

Language and locale

For a multi-locale catalog, detect first and pass the result through:

curl -s -X POST https://ace.authoritas.com/api/v1/utils/language \
  -H "Authorization: Bearer $ACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"products":[{"id":"1","title":"Wanderschuhe für Herren"}]}'
# => { "data": { "language": "de-DE", "confidence": 0.98, ... } }

Detection is free. Feed the returned BCP 47 code into targetLanguage on your content or pipeline request.

Content types

Request as many as you need per product. Each one adds a unit to the cost.

Best practices

1. Budget before you start. Units are products × content types. Check GET /api/v1/usage. See Credits and usage.
2. Send an idempotency key per batch. A retried batch resumes its original job rather than paying twice. Use a stable key such as the batch filename.
3. Handle partial success. A job can finish partial, with both succeededCount and failedCount set. Read /jobs/{id}/results and retry only the failures.
4. Back off on 429. Your key has a requests per minute limit. Honour Retry-After, or raise the limit under Settings, Developer console, Keys.
5. Score before and after. POST /api/v1/utils/agentic-readiness is free and shows which products are thin on data. Run it first to prioritise, and again afterwards to show the lift.
6. Prefer webhooks over polling for large runs. See Webhooks.

Summary

• Derive rules once per category, then reuse them across every batch.
• Let large requests become jobs, and track them through the jobs endpoints.
• Detect language for free and pass it through as targetLanguage.
• Use idempotency keys, handle partial results, and back off on 429.

For full schemas, see the API Reference.