---
name: applicaster-curation-api-skill
description: "Curation API: use when implementing or hardening a customer-hosted Applicaster Curation API endpoint that selects Smart Component presets and linked content feeds, including ctx-personalized UI composition."
---

# applicaster-curation-api-skill

Implement or harden a customer-hosted Applicaster Curation API endpoint. The **selection contract**
is the approved rule set that maps a request and verified context to an ordered list of Zapp preset
reference names and content-feed URLs. Establish it before editing backend code.

## Scope and non-negotiable gates

1. Curation selects UI composition; it does not implement the returned Pipes2 content feeds. When a
   linked feed needs work, invoke [applicaster-dsp-content-feeds](../applicaster-dsp-content-feeds/SKILL.md).
   When a required context value is not produced, invoke
   [applicaster-context-setter](../applicaster-context-setter/SKILL.md) or
   [applicaster-preference-selector](../applicaster-preference-selector/SKILL.md).
2. Do not create presets, mappings, Smart Components, endpoints, or Pipes feeds in Zapp Studio.
   Provide an exact `## Zapp Studio Configuration` guide at handoff instead.
3. Fetch current live Curation API, Smart Component, endpoint/context-key, Pipes2-feed, generic
   Pipes2 protocol, available-context-keys, and feed-validator documentation before implementation.
   Read [curation-contract.md](references/curation-contract.md) and
   [decision-guide.md](references/decision-guide.md) as local aids; live documentation is authority.
4. Do not propose backend code before inspecting the target backend and its available API
   documentation. Record a concise sourced fact summary, then ask only for undecidable product
   rules. If documentation conflicts with code, resolve the conflict before edits.
5. Obtain explicit approval for the selection contract before editing. Refresh the contract if a
   material decision changes.
6. A successful response is strict Curation JSON only: `{"entry":[{"preset_name":"...",
   "feed_url":"https://..."}]}`. Do not add a generic Pipes2 envelope or content-entry fields.
7. Validate request inputs before use and validate every successful Curation response at the
   service boundary using the target project's convention. Never return malformed Curation JSON.
8. Never log raw `ctx`, tokens, identifiers, signed URLs, request headers, or returned feed URLs.
   Base64URL is encoding, not authentication: independently verify any signal used to select
   authorization-sensitive content.
9. Complete backend validation only after project-native tests and a successful
   [curation-api-e2e](tools/curation-api-e2e/README.md) run, or report its concrete blocker.

## 1. Scope, prerequisites, and Curation model

Explain this model before discussing implementation:

1. The developer creates component or group presets in Zapp Studio.
2. Zapp maps a **reference name** to each preset.
3. This endpoint returns ordered `{ preset_name, feed_url }` entries.
4. Smart Component resolves the reference name and renders it from the linked content feed.
5. Endpoint context, including `ctx`, can select a different ordered UI for a different request.

Use this illustrative flow only to explain the model, not as a default design:

```text
languageCode=es -> rule "Spanish home" -> hero + rail reference names -> their content-feed URLs
```

An empty `entry` array intentionally renders nothing. Component and group presets are supported;
the Curation component cannot be placed inside a group. Repeated reference names are valid when
the approved selection contract intentionally renders a preset multiple times.

Completion: the Curation model is understood, and unresolved dependencies are marked blocked and
routed to their specialist skill.

## 2. Establish facts

Inspect the target project before asking questions: framework, routes, validation, tests,
configuration, deployment URL, caches, logs, source systems, identity/context handling, existing
DSP/Curation code, and backend/API documentation. Determine facts from code first.

Completion: target constraints are evidenced and backend/API documentation conflicts are resolved.

## 3. Resolve the selection contract

Ask one recommended question at a time, in dependency order. Record approved answers in the target
repository's code-adjacent, version-controlled decision table. Start from
[selection-contract.md](templates/selection-contract.md).

Resolve all material unknowns:

1. Endpoint base URL, locator, GET/POST method, request body semantics, and required headers.
2. The selectable `preset_name` reference-name list. Mapping those names to actual presets remains
   a later Zapp Studio task.
3. Source of truth, eligibility, precedence, order, repeated-preset policy, and maximum entries.
4. Every input and `ctx` key; missing, malformed, invalid, and default behavior.
5. Every selection branch, including its exact ordered entries and declared empty outcomes.
6. `feed_url` construction and approved backend-controlled or registered origins. Never forward an
   untrusted client, profile, or upstream URL.
7. Error status/body, upstream behavior, timeout budget, cache policy and cache variation.
8. Which credentials may appear in `ctx`, and which independently verified identity/entitlement
   signal authorizes protected selection.
9. Dependency owners, safe test data, and privacy-safe metrics: outcome, count, rule branch,
   latency, and failure reason only.

Completion: every selection rule is deterministic, owned, testable, and approved by the developer.

## 4. Confirm before edits

Present one implementation contract containing the fact summary, completed selection contract,
strict request/response/error behavior, security/cache/latency policy, changed files, target test
plan, E2E case file and command, dependency status, and Zapp handoff prerequisites. Wait for
explicit approval.

## 5. Implement the approved contract

Adapt to the target project's stack, router, validation, configuration, logging, test, and build
conventions. Make only the approved changes. Add project-native tests for selection branches,
input failures, empty results, reproducible errors, response validation, authorization, and cache
or timing behavior where feasible.

Persist the approved reference-name list/selection contract and E2E case file beside target code,
following that repository's convention. Use [cases.json](templates/cases.json) as the starter.

## 6. Verify and hand off

1. Run target formatting, type checks, and relevant focused tests during work; run its full suite
   before completion.
2. Run `curation-api-e2e` against a safe runnable HTTPS endpoint. It checks Curation only and
   never follows returned `feed_url` values. Use `${ENV:NAME}` placeholders for runtime secrets;
   do not commit resolved values.
3. Report files, commands/results, the redacted JSON report, blockers, and deployment needs.
4. Finish with this exact section:

## Zapp Studio Configuration

This is a manual guide; do not perform these actions.

1. Register the HTTPS endpoint and configure its required context-key delivery. Use the narrowest
   endpoint prefix; only the longest matching endpoint supplies context keys.
2. Register the Curation Pipes feed using its endpoint and locator.
3. Install Smart Component in each relevant app version, create the component/group presets, and
   map every approved reference name to its preset.
4. Bind the Curation feed as the Smart Component data source.
5. Rebuild and manually verify every applicable runtime family, including one personalized `ctx`
   scenario, expected order, empty behavior, and error fallback.

Report `backend contract passed` separately from `end-to-end verification blocked` until the
developer confirms the Zapp mapping, binding, and app/device behavior.