SENTINEL SIGNAL

Sentinel Signal

Sentinel Utility APIs Architecture and Development Plan

Source: docs/sentinel-utility-apis-architecture-development-plan.md

All documents Docs Home Home

Document Content

Sentinel Utility APIs Architecture and Development Plan

Status: implemented behind feature flags

Architecture

Sentinel Utility APIs run synchronously inside Verify at /v1/utilities/*. They use existing Intelligence organizations, API keys, plans, database sessions, target-safety controls, Prometheus registry, product registry, and /app sessions. They do not introduce a service, queue, scheduler, crawler, credential type, or customer-visible run history.

config/products.yaml is the canonical metadata source for the bundle and its eight utility surfaces. The packaged registry projection drives runtime utility definitions, including routes, credit weights, cache TTLs, backing services, methodology versions, docs paths, and cross-sell relationships.

The request flow is:

Bearer API key or /app session
  -> utilities:read scope
  -> strict input validation and public-target normalization
  -> weighted organization/key/utility rate limit
  -> transactional credit reservation
  -> organization-isolated TTL cache or canonical Verify service
  -> consume or release reservation
  -> utilities-1.0 response and bounded operational telemetry

Canonical Backing Services

  • Robots, AI crawler policy, llms.txt, documentation discovery, and structured data use the readiness crawl/parser and domain-evidence layer.
  • API discovery uses readiness.api_surfaces.
  • API Schema Diff fetches both documents through the API Change engine and compares its canonical OpenAPI representations.
  • Agent Readiness Score is a compact projection of the unchanged readiness methodology.

Only normalized public evidence is returned. Target values and response bodies are not written to utility accounting or portfolio tables.

Accounting and Caching

Migration 0049_utility_api_usage adds one locked monthly balance per organization and one operational/accounting record per accepted call. Credits reset at UTC calendar-month boundaries. Developer, Startup, Team, and Platform receive 1,000, 10,000, 50,000, and 250,000 credits respectively; overage is disabled initially.

Credits are reserved before work, consumed for successful or usable partial responses (including cache hits), and released on failure. Stale reservations are reclaimed after ten minutes. The bounded process-local cache is organization-scoped and versioned by utility input, output schema, methodology, and backing service metadata.

Interfaces and Rollout

The launch set is the eight POST endpoints represented in the registry. Public HTML documentation lives under /docs/utilities; the same routes remain part of Verify's authoritative OpenAPI document. /app/utilities supplies CSRF-protected, non-persistent playground forms and reads the same accounting and service layers as bearer-authenticated requests.

The product remains private and incubating until production qualification. Deploy migration first with MCP_VERIFY_UTILITY_APIS_ENABLED=false and MCP_VERIFY_APP_UTILITIES_ENABLED=false; canary the API, then enable the console, and only then promote the product registry lifecycle. observed-ai-crawlers and website-stack remain deferred.