---
title: "Prose Auto Refresh"
method: POST
path: "/billing/internal/prose-auto-refresh"
tags: ["billing"]
---

# Prose Auto Refresh

`POST /billing/internal/prose-auto-refresh`

Decide whether a just-ready snapshot should get AI explanations written.

Lives beside the other Modal-facing internal routes because it is the same
trust boundary and, like them, it can move money: the decision it reaches
may place a credit hold. The indexer cannot make this call itself -- the
policy, the selection, the billing principal and the daily cap all live in
the backend, and the ``prose_jobs`` hold/settle ledger is only ever written
from here.

``mode="authorize"`` returns the authorization for the caller to act on,
which is what lets the indexer write explanations in the container that
already holds the parsed tree. ``mode="spawn"`` (the default, and what a
pre-existing deploy sends) dispatches a dedicated container instead. Either
way the money is committed here and settled through the same ledger claim.

Always 200 with a reason. The caller is a best-effort callback on an
already-published snapshot, so "we decided not to" and "we could not decide"
must be equally harmless; an exception here would be retried by nobody and
read as a failure of an index run that in fact succeeded.

## Headers

- `x-service-token` string, required

## Request body

- ProseAutoRefreshRequest — Ask the backend whether a ready snapshot should get AI explanations. Sent by the indexer once a snapshot is ready, for either of two reasons: carry-forward flagged pages stale, or the index request carried an opt-in. Nothing in this payload is trusted for a decision: the snapshot id is a pointer, and the policy, the selection, the billing principal and the day's cap are all re-derived server-side. ``stale_count`` is carried for the log line only, so a disagreement between what Modal saw and what the backend resolves is visible rather than silent.
  - `snapshot_id` string, required
  - `stale_count` integer
  - `mode` 'authorize' | 'spawn'
  - `job_id` string, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/repowise/apis/repowise-hosted-api.md) · [All operations](https://skmtc.dev/repowise/apis/repowise-hosted-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/repowise/repowise-hosted-api/revisions/40167ba9ab58/schema)