API Schema Caching

Converting an OpenAPI spec to a call/response schema requires an LLM call. The result is cached in the service's note to avoid repeating this on every use.

Cache Freshness — HEAD Check

Before using a cached schema, the orchestrator does a HEAD request to the spec URL and checks ETag or Last-Modified against the value stored in the cache. If unchanged, the cached schema is used directly. If changed, the spec is re-fetched and schema generation is re-run.

Cache Format

Stored as YAML in the service's note (human-readable for inspection). Example:

service_url: http://httpbin.org
spec_url: http://httpbin.org/spec.json
cached: 2026-03-22
spec_etag: "abc123"
spec_last_modified: "Sat, 21 Mar 2026 10:00:00 GMT"
call_schema:
  # compact representation of available endpoints,
  # parameters, and expected response shapes
response_schema:
  # error response shapes by status code

Cache Invalidation

Invalidation occurs when:

• HEAD check shows ETag or Last-Modified has changed

• LLM flags the cached schema as incorrect after receiving an unexpected response

In both cases, orchestrator re-fetches the spec and re-runs schema generation (LLM call 2 in the flow).

Cache Key

The spec URL is the cache key. Stored in the service's stub note alongside the schema, so reading the note gives both registration info and cached schema in one fetch.