Internal endpoints

Summary#

A small set of routes are not for customers at all. They drive background work, run reconciliation, and complete operator sign-ins. They are protected by a single shared secret, MV_INTERNAL_SECRET, and the check fails closed: if the secret is not configured in the environment, every one of them refuses every call with HTTP 503. This page lists each route, its contract, and the operational rules around the secret.

Overview#

Why they exist#

The site is deployed as a Cloudflare Pages project. Pages never invokes a Worker's scheduled() handler, because cron triggers are a Workers-only feature. The Worker does define scheduled(), and it would run four jobs if it were ever called, but on Pages it is not.

Background work therefore has to be pushed rather than pulled. An external scheduler calls a secured HTTP endpoint, and the Worker runs whatever is due. That endpoint is POST /api/cron/run.

The same secret then serves two further needs: an internal HTTP handoff that gives a long article job its own execution budget, and a small number of operator actions that must never be reachable from a customer session.

The two gate shapes#

There are two implementations of the check, and they answer differently. Knowing which is which saves a confusing debugging session.

The standard gate protects /api/cron/run and /api/billing/sync. The diagnostic gate protects /api/dbgdfs, everything under /api/diag/, and the operator blog sign-in. The diagnostic gate is deliberately uniform so it leaks nothing: an unset secret and a wrong key look identical from outside.

The secret must be set in three places#

MV_INTERNAL_SECRET must hold the same value in all three:

If AI article generation suddenly returns 503, or background jobs stop running, a missing or mismatched value here is by far the most likely cause.

POST /api/cron/run#

The job registry#

Each job is wrapped individually, so one failing cannot abort the others. The handler returns immediately and lets the work continue in the background, exactly as a native cron trigger would.

Requests#

# Run everything that is due
curl -sS -X POST https://metricvaultai.com/api/cron/run \
  -H "x-mv-internal-secret: $MV_INTERNAL_SECRET"

# Run one job
curl -sS -X POST "https://metricvaultai.com/api/cron/run?job=rank_alerts" \
  -H "x-mv-internal-secret: $MV_INTERNAL_SECRET"

# GET form, handy from a browser
curl -sS "https://metricvaultai.com/api/cron/run?key=$MV_INTERNAL_SECRET"

Responses#

The schedulers#

Running both is harmless: the jobs decide their own real cadence, and calling the endpoint more often than anything is due simply does nothing.

The cron Worker also answers a plain GET as a manual health check, forwarding the secret and returning the Pages response. It holds no business logic and no database binding on purpose.

The workflow can be run by hand from the Actions tab, optionally naming a single job in its job input.

Removed: POST /api/article-process#

This route, together with POST /api/article-start and GET /api/article-status, was removed on 2026-09-01. Nothing in the product called it. The Article Writer runs through POST /api/premium-ai like every other dashboard tool.

It is documented here because the reason it was removed is a rule worth keeping:

/api/article-start took a request from anyone — it ran no identity check — and then fetched /api/article-process on the platform's own behalf, presenting MV_INTERNAL_SECRET. That synthetic request was built fresh, so it carried no Authorization header. By the time the AI quota check ran, the only address left anywhere in the call was the one the original, anonymous caller had typed into the request body. The gate accepted it, and the generation was billed to whichever customer the body named.

The secret was doing its job the whole time. It proved the call came from inside the platform, which was true. It could not prove anything about who asked for it, and nothing else in the chain was carrying that.

So: when a handoff needs to run work on a user's behalf, forward something the receiver can verify — the caller's own bearer token, or a signed claim minted after the identity check. A field in the request body is not an identity, and an internal secret does not turn it into one.

POST /api/billing/sync#

This is the backstop for the Stripe webhook. It pages through subscriptions 100 at a time, up to 40 pages, so it covers up to 4,000 subscriptions in one run. A subscription counts as entitling when its status is active, trialing or past_due.

Two safety properties matter:

• Revocations only follow a complete scan. If the scan does not finish, the run grants only and reports revoke_skipped: "incomplete scan — granted only, no revocations".
• Only Stripe-owned records are revoked. A plan granted manually or comped by support is never touched.

curl -sS -X POST https://metricvaultai.com/api/billing/sync \
  -H "x-mv-internal-secret: $MV_INTERNAL_SECRET"

Response, pretty-printed:

{
  "ok": true,
  "scanned": 812,
  "granted": 3,
  "unchanged": 806,
  "revoked": 2,
  "skipped_no_email": 1,
  "errors": [],
  "scan_complete": true
}

GET /api/blog/higgsfield/signin and /callback#

The blog's AI image provider is authorised as one platform-wide operator session, not per customer. There is a single stored credential row shared by every account. That is exactly why this flow is gated on the operator secret rather than on a customer session: a customer must never be able to reach it.

The sign-in route performs dynamic client registration, generates a PKCE verifier and challenge, stores a random state server-side, and redirects to the provider. States older than 15 minutes are pruned. The callback consumes the single-use state, exchanges the code, stores the tokens, and renders an HTML result page.

Related: the higgsfield background job keeps that token alive rather than racing live user requests, and /api/diag/blog-image?probe=1 reports the stored token's state without refreshing it. See Diagnostic endpoints.

Diagnostic routes#

Every route under /api/diag/ plus /api/dbgdfs sits behind the diagnostic gate. They are documented in full in Diagnostic endpoints, including which ones spend real money when called.

Operational notes#

Rotating the secret#

Rotation is a coordinated change across three systems, and there is no overlap window: the Worker compares against exactly one value.

1. Generate a new random value of at least 32 characters.
2. Set it in the Pages project environment and redeploy or wait for propagation.
3. Set it on the cron Worker with wrangler secret put MV_INTERNAL_SECRET.
4. Set it in the repository secrets.
5. Verify with a manual call: curl -sS -X POST https://metricvaultai.com/api/cron/run -H "x-mv-internal-secret: $NEW" should return {"ok":true,…}.

Between steps 2 and 4 the backup scheduler will fail its calls with 401. That is expected and harmless, because the primary scheduler covers the window and the jobs are idempotent.

What breaks if it is unset#

Verifying the whole chain#

# 1. The Pages endpoint accepts the secret
curl -sS -X POST https://metricvaultai.com/api/cron/run \
  -H "x-mv-internal-secret: $MV_INTERNAL_SECRET"

# 2. One job in isolation
curl -sS -X POST "https://metricvaultai.com/api/cron/run?job=monitor" \
  -H "x-mv-internal-secret: $MV_INTERNAL_SECRET"

# 3. The diagnostic gate agrees with the same value
curl -sS "https://metricvaultai.com/api/diag/psi?key=$MV_INTERNAL_SECRET"

If step 1 returns 503, the Pages environment variable is missing. If it returns 401, the value you sent does not match the one deployed. If steps 1 and 3 disagree, you have two different values in play.

Do not add a cron trigger to the Pages configuration#

Adding a [triggers] crons block to the Pages project's wrangler.toml will not work. Cron is a Workers feature, and this is a Pages project. The standalone cron Worker exists precisely because that is true.