{"openapi":"3.0.3","info":{"title":"Prompt Cache Key & Context Budgeter API","version":"1.0.0","description":"Estimates token counts per prompt block, computes deterministic SHA-256 prefix cache keys, detects cache-busting dynamic variables, recommends static-first ordering and cache breakpoints, and calculates USD savings."},"servers":[{"url":"https://api.tinplate.dev","description":"Production Edge Gateway"}],"components":{"schemas":{"PromptCacheBudgeterResponseData":{"type":"object","properties":{"model":{"type":"string","enum":["gpt-4o","gpt-4o-mini","o3-mini","claude-3-7-sonnet","claude-3-5-haiku","gemini-2.5-pro","gemini-2.5-flash"]},"total_input_tokens":{"type":"integer"},"cacheable_prefix_tokens":{"type":"integer"},"uncached_tail_tokens":{"type":"integer"},"min_cacheable_tokens_required":{"type":"integer"},"cache_eligible":{"type":"boolean"},"cache_prefix_key":{"type":"string"},"within_budget":{"type":"boolean"},"context_utilization_pct":{"type":"number"},"ordering_optimal":{"type":"boolean"},"recommended_order_ids":{"type":"array","items":{"type":"string"}},"block_breakdown":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"id":{"type":"string"},"role":{"type":"string"},"inferred_volatility":{"type":"string","enum":["static","session","turn"]},"estimated_tokens":{"type":"integer"},"cumulative_tokens":{"type":"integer"},"in_cacheable_prefix":{"type":"boolean"},"recommended_cache_breakpoint":{"type":"boolean"}},"required":["index","id","role","inferred_volatility","estimated_tokens","cumulative_tokens","in_cacheable_prefix","recommended_cache_breakpoint"]}},"cost_estimate_usd":{"type":"object","properties":{"single_uncached_call":{"type":"number"},"single_cache_write_call":{"type":"number"},"single_cache_read_call":{"type":"number"},"batch_uncached_total":{"type":"number"},"batch_cached_total":{"type":"number"},"estimated_savings_usd":{"type":"number"},"estimated_savings_pct":{"type":"number"}},"required":["single_uncached_call","single_cache_write_call","single_cache_read_call","batch_uncached_total","batch_cached_total","estimated_savings_usd","estimated_savings_pct"]},"recommendations":{"type":"array","items":{"type":"string"}}},"required":["model","total_input_tokens","cacheable_prefix_tokens","uncached_tail_tokens","min_cacheable_tokens_required","cache_eligible","cache_prefix_key","within_budget","context_utilization_pct","ordering_optimal","recommended_order_ids","block_breakdown","cost_estimate_usd","recommendations"]},"PromptCacheBudgeterRequest":{"type":"object","properties":{"model":{"type":"string","enum":["gpt-4o","gpt-4o-mini","o3-mini","claude-3-7-sonnet","claude-3-5-haiku","gemini-2.5-pro","gemini-2.5-flash"],"default":"claude-3-7-sonnet"},"blocks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":64},"role":{"type":"string","enum":["system","developer","user","assistant","tool"],"default":"user"},"content":{"type":"string","maxLength":262144},"volatility":{"type":"string","enum":["static","session","turn"]},"cacheable":{"type":"boolean"}},"required":["content"]},"minItems":1,"maxItems":200},"max_context_tokens":{"type":"integer","minimum":512,"maximum":2000000},"expected_output_tokens":{"type":"integer","minimum":0,"maximum":128000,"default":500},"estimated_cache_hits":{"type":"integer","minimum":1,"maximum":10000,"default":10}},"required":["blocks"]},"ResponseMeta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","format":"uuid"},"ms":{"type":"integer","minimum":0},"version":{"type":"string","example":"1.0.0"}}},"ErrorEnvelope":{"type":"object","required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_input"},"message":{"type":"string","example":"Request body failed validation"}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}},"parameters":{}},"paths":{"/v1/prompt-cache-budgeter":{"post":{"tags":["28_PROMPT_CACHE_BUDGETER"],"summary":"Estimate tokens, cache prefix keys, breakpoints, and USD cost savings","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptCacheBudgeterRequest"}}}},"responses":{"200":{"description":"Token budget, cache prefix key, block breakdown, and USD savings estimate","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PromptCacheBudgeterResponseData"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["ok","data","meta"]}}}},"400":{"description":"Invalid input or malformed JSON request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid authentication credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request payload exceeds subscribed plan byte cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}