APIs and execution contracts

Authenticated no-spend quote

Observed source: hosted-app/app/api/query-manifest/route.js. POST authenticates first, requires run_pulls scope, uses a process-local 30-request/60-minute owner bucket and bounds JSON to 131072 bytes. API-key authentication attempts a last_used_at write: no-spend does not mean no-write.

With truthy pull_plan, the route compiles an explicit selection using server-controlled price evidence. Responses include ok, issues, manifest and spend_enabled; plan can be absent on early validation failure. A ready quote is not approval to dispatch and spend_enabled is a runtime switch, not consent.

Anonymous requests return 401/signup_required, wrong scope 403/insufficient_scope, rate limiting 429/too_many_manifests. JSON read failures use the bounded reader's status. Without pull_plan the same route uses the legacy manifest branch; it must be documented and tested separately.

{
  "domain": "example.com",
  "seo_market": {
    "location_code": 2840,
    "language_code": "en",
    "confirmed": true
  },
  "pull_plan": {
    "preset": "low",
    "items": {
      "own_rankings": {
        "included": true,
        "groups": [
          {
            "id": "g1",
            "label": "Domain / locale query 1",
            "included": true,
            "active_zero": false,
            "values": {
              "rows": 500
            }
          }
        ],
        "options": {
          "clickstream": "off"
        }
      }
    }
  },
  "plan_bindings": {}
}

Synthetic request example: one current-catalog own_rankings group, 500 rows, US/English. All omitted items are OFF. This is not an Alaris quote, current external price verification or purchase approval.

Selected-plan request fields

Selection and group structure

Confirmed target bindings

Selected quote response fields

Limits, errors and side effects

Observed gaps and verification status

On 2026-09-13 the coordinator exercised the actual Next route, auth resolver and compiler with synthetic auth transport only. Eight observations record response keys, issues, selected items and auth side effects; external fetches are refused. This is module-level runtime evidence, not a listening HTTP server, live identity or independent funded acceptance.

Empty items={} and items=[] both returned HTTP 200/ready with no selected capabilities, maximum provider cost 0 and fixture tier price 1 credit. This is a readiness/schema gap, not proof that a charge occurred. Require nonempty executable scope and an object-shaped items record before acceptance.

A synthetic Firecrawl price-basis timestamp of 2000-01-01 was accepted when unit cost/source were otherwise valid. The source checks parseability but no freshness window. Lead review must establish expiry policy and stale-source refusal; this pass does not invent a threshold or activate the provider.

Existing route/compiler/review tests pass but do not cover empty-scope refusal or age-expiry requirements. Implementation and new independent tests remain assigned to the Claude engineers, whose retry gate is unresolved.

Quote source and reproduction

Sources: hosted-app/app/api/query-manifest/route.js; hosted-app/lib/pull-execution-plan.mjs; hosted-app/lib/comprehensive-pull.mjs (resolveAuthContext/resolveApiKeyContext); hosted-app/lib/bounded-http.mjs; hosted-app/lib/comprehensive-pull-handler.mjs (reservation approval gates); hosted-app/lib/plan-review-response.mjs.

Run node docs/plans/brand-studio-roadmap/quote-contract-observation-20260913.mjs for the no-external-network fixture observation. Its paired .json records observations, probe hash and execution source hash. Synthetic prices and identities must never be copied into a live quote or approval.

Existing checks: node --test tests/query-manifest-route.test.mjs tests/pull-execution-plan.test.mjs tests/plan-review-response.test.mjs. The remaining route inventory still needs field-level coverage; this reference does not certify every API.

Core public seams

Every endpoint needs a contract

Complete the route inventory with request/response schemas, auth and ownership scope, pagination and ordering, error status/reason codes, input size limits, timeouts, rate limits, idempotency, side effects and version compatibility.

Include webhook/cron, download, dynamic path and non-/api handlers where relevant. The generated inventory below discovers local /api route declarations; it does not prove deployed availability or exhaustive middleware behavior.

For each provider adapter, document exact endpoint/version, request quantities and units, locale, target identity, task ownership, paging/continuation, retry/cancel policy, response schema, rate basis, actual-cost extraction and normalization. Link official provider documentation through the existing provider pages and refresh drift-prone details before use.

Supported, parked and legacy behavior

Catalog support, adapter implementation, configuration and observed successful execution are four different states. Show all four. A free item with no working adapter is not complete. A configured key does not authorize new work.

The request ledger refuses new spending when an earlier request is reserved or uncertain. A free poll must belong to the same plan, provider task and target. Make these properties explicit at every adapter and continuation seam.

Process-local daily provider ceilings are not shared account-wide limits and can reset on process restart. Distributed enforcement and concurrent-account reconciliation require separate evidence.

AI visibility and unpriced lanes stay parked. Existing legacy stages may still be present in queue ordering; selected-plan progress must expose them truthfully as skipped instead of implying active purchased work.

Route declarations from current source

This inventory is regenerated from route files. A declared method does not prove authentication, schema coverage, runtime success or support status. Contract coverage must be checked separately.