[DEV-2189] Document the Decisions REST endpoint — hold merge

[Arpanexe]

⚠️ Hold merge. Publish only when we choose to (per Tony, the API can ship before the docs). Pricing is still provisional. API PR: Fliplet/fliplet-api#8775.

Product areas affected

Developer docs: docs/REST-API/fliplet-ai.md, docs/API/core/ai/models.md.

What does this PR do?

Documents POST /v1/apps/:app/ai/decisions:

• request fields and the three question types
• a curl example
• an illustrative response, plus how to read refusals, fractional scores and boolean choices
• credits (input-only, failures not charged)
• an error/status table and retry rules

It's REST only, with no Fliplet.AI wrapper, and pricing is marked provisional. OpenAI's rates (2× over 272K input tokens, +10% for regional processing) are noted. Also adds a "Decisions models" section (gpt-6-luna only, no fallback) to the model catalog.

JIRA ticket

DEV-2189

Result

Every status code and error type in the docs was checked against the API branch and against real local calls (the usage example matches what OpenAI actually returns).

Deployment instructions

None. Hold merge until we decide to publish (see top).

Author concerns

The curl example uses the production host. The earlier staging-host note is gone now that the endpoint isn't staging-only.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying fliplet-cli with    Cloudflare Pages

Latest commit:	7187d0f
Status:	✅  Deploy successful!
Preview URL:	https://0d79851c.fliplet-cli.pages.dev
Branch Preview URL:	https://feature-dev-2189-decisions-d.fliplet-cli.pages.dev

View logs

[tonytlwu]

Is it really going to be limited to staging? I'm happy with it being available on production too.

[tonytlwu]

Code review (via /fliplet-pr-review)

Requested documentation clarification: question names are optional.

Review basis: subject=5b3dbc415b3519dd667f372a67912dc43cd4bae7 standards=fliplet-engineering@0.18.0 revision=d8c727a0419f9d87a6e38a767a4b95b84380cc44+dirty source=fliplet-pr-review digest=sha256:40c49b60a8bd5384

[tonytlwu]

name is optional in OpenAI's Decisions contract. This table currently makes it appear required, although the response section correctly documents name: null for unnamed questions. Please make the optionality explicit; no Fliplet validation rule is needed.

Suggested change

	| `questions` | Yes | Array of questions, each with `type`, `instructions` and `name`. |
	| `questions` | Yes | Array of questions, each with `type`, `instructions` and optional `name`. |

Reference: https://developers.openai.com/api/reference/resources/decisions/methods/create

[tonytlwu]

Accepted documentation clarifications from Tony for DEV-2189:

Billing: retain input-only Decisions billing, matching this endpoint's provider pricing. Please qualify the current blanket claim that every successful call is charged. Suggested wording:

“For apps subject to AI credit metering, Decisions charges are calculated from input tokens only. Failed or timed-out requests are not charged. Existing V2 metering rules remain unchanged.”

Do not present an HTTP 200 as proof that deferred credit settlement has completed. Missing provider usage or accounting failures remain observable engineering exceptions; the public reference does not need queue implementation details.

Retry guidance: replace “don't retry 4xx errors without changing the request” with guidance specific to the outcome:

• Invalid payload/model (400): correct the request before retrying.
• Authentication/access (401/403): restore valid credentials or permissions first.
• Insufficient credits (402): restore credit capacity first; the same payload can then be resent.
• Rate limit (429): wait/back off and resend the same payload; honour Retry-After if supplied.
• Provider unavailable/timeout (502/504): retry cautiously after a delay. A retry is a separate request, and a timeout does not prove provider processing stopped.

Production API availability is accepted independently of documentation publication. Keep this docs PR unpublished until publication is chosen, but update its staging-only availability wording to match the intended production API release. The optional question-name correction is already captured in the inline comment; no need to duplicate it.

[tonytlwu]

Tony has agreed the following consumer-facing billing wording. Please replace the current blanket claims that every successful call/every caller is charged in docs/REST-API/fliplet-ai.md (Decisions → Credits) with:

Successful requests are subject to input-token credit charges under the app’s applicable metering rules. Failed or timed-out requests are not charged.

Retain the credit precheck / 402 explanation and provisional-pricing note. Missing-usage and accounting-failure handling should remain in internal engineering documentation; the public API reference does not need those implementation details.

This updates the billing wording requested in the earlier review comment. The optional question name and error-specific retry corrections in the existing comments still apply. Documentation publication remains a separate decision; keep the merge hold.