{"components":{"schemas":{"Account":{"additionalProperties":false,"example":{"api_key_id":"key_00000000-0000-4000-8000-000000000001","available_usd":"24.695000000","currency":"usd","funding_enabled":true,"id":"local-playground","pricing_version":"local-v5-monthly-fees","stripe_test_mode":true},"properties":{"api_key_id":{"description":"Non-secret ID of the currently authenticated key.","type":"string"},"available_usd":{"description":"Signed fixed-decimal USD credit balance. Requests are admitted only while the balance is positive; the final settled charge of an in-flight request may take it below zero until the next top-up. Spending thresholds stop new calls; the last response and its tools can take the final charge beyond them.","example":"0.050000000","pattern":"^-?[0-9]+\\.[0-9]{9}$","type":"string"},"currency":{"const":"usd"},"funding_enabled":{"type":"boolean"},"id":{"type":"string"},"pricing_version":{"type":"string"},"stripe_test_mode":{"type":"boolean"}},"required":["id","currency","available_usd","pricing_version","funding_enabled","stripe_test_mode","api_key_id"],"type":"object"},"AggregatedInferenceUsage":{"additionalProperties":false,"description":"Input includes cached input and cache creation, which are subsets. Output includes reasoning. Includes reported physical turns and compaction. Search units are kept separate across providers.","example":{"cache_creation_input_tokens":0,"cached_input_tokens":2000,"input_tokens":6000,"output_tokens":1000,"web_search_requests_by_unit":{"calls":5,"grounded_prompts":0,"queries":0}},"properties":{"cache_creation_input_tokens":{"example":0,"minimum":0,"type":"integer"},"cached_input_tokens":{"example":2000,"minimum":0,"type":"integer"},"input_tokens":{"example":6000,"minimum":0,"type":"integer"},"output_tokens":{"example":1000,"minimum":0,"type":"integer"},"web_search_requests_by_unit":{"additionalProperties":false,"example":{"calls":5,"grounded_prompts":0,"queries":0},"properties":{"calls":{"minimum":0,"type":"integer"},"grounded_prompts":{"minimum":0,"type":"integer"},"queries":{"minimum":0,"type":"integer"}},"required":["calls","queries","grounded_prompts"],"type":"object"}},"required":["input_tokens","cached_input_tokens","cache_creation_input_tokens","output_tokens","web_search_requests_by_unit"],"type":"object"},"Artifact":{"additionalProperties":false,"properties":{"bytes":{"description":"Size of the downloadable bytes, including JWE encoding overhead when encrypted.","type":"integer"},"content_type":{"type":"string"},"conversion_id":{"type":"string"},"deleted_at":{"format":"date-time","type":["string","null"]},"download_url":{"description":"Same-origin path. Requires the same Bearer API key; never a public signed link in this local build.","type":"string"},"encryption":{"$ref":"#/components/schemas/ArtifactEncryption"},"expires_at":{"format":"date-time","type":["string","null"]},"filename":{"type":"string"},"format":{"enum":["docx","pdf","md","html","txt"]},"id":{"type":"string"},"input_eligible":{"description":"False for encrypted artifacts; they must be decrypted locally and re-uploaded.","type":"boolean"},"prompt_id":{"type":"string"},"sha256":{"description":"SHA-256 of the exact downloadable bytes (ciphertext for encrypted artifacts).","type":"string"},"variant":{"enum":["tracked_changes","clean","converted"]}},"required":["id","format","filename","content_type","variant","sha256","bytes","download_url","input_eligible","expires_at"],"type":"object"},"ArtifactEncryption":{"additionalProperties":false,"properties":{"alg":{"enum":["RSA-OAEP-256"],"type":"string"},"enc":{"enum":["A256GCM"],"type":"string"},"format":{"enum":["jwe"],"type":"string"},"key_id":{"description":"Base64url SHA-256 JWK thumbprint of the recipient public key (RFC7638).","type":"string"}},"required":["format","alg","enc","key_id"],"type":"object"},"Citation":{"additionalProperties":false,"properties":{"endIndex":{"type":"integer"},"id":{"type":"string"},"startIndex":{"type":"integer"},"title":{"type":"string"},"url":{"type":"string"}},"required":["id","url","title"],"type":"object"},"Continuation":{"additionalProperties":false,"properties":{"history_compacted":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"reason":{"type":"string"},"reasoning_state":{"enum":["new","reused","reset","compacted","unavailable"]}},"required":["reasoning_state","history_compacted"],"type":"object"},"Conversion":{"additionalProperties":true,"properties":{"completed_at":{"format":"date-time","type":["string","null"]},"content_deleted_at":{"format":"date-time","type":["string","null"]},"content_expires_at":{"format":"date-time","type":["string","null"]},"created_at":{"format":"date-time","type":"string"},"error":{"anyOf":[{"additionalProperties":false,"properties":{"code":{"type":"string"},"details":{"additionalProperties":true,"type":"object"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},{"type":"null"}]},"id":{"type":"string"},"input":{"properties":{"bytes":{"type":"integer"},"file_id":{"type":"string"},"filename":{"type":"string"},"format":{"description":"Empty after request content has been deleted.","enum":["pdf","docx","md","html","txt","rtf","odt","image",""]},"sha256":{"type":"string"}},"required":["file_id","format","filename","bytes","sha256"],"type":"object"},"metadata":{"$ref":"#/components/schemas/Metadata"},"mode":{"description":"Empty after request content has been deleted.","enum":["deterministic","vision",""]},"object":{"const":"conversion"},"output":{"properties":{"artifact":{"anyOf":[{"$ref":"#/components/schemas/Artifact"},{"type":"null"}]},"format":{"description":"Empty after request content has been deleted.","enum":["docx","pdf","md","html","txt",""]}},"required":["format","artifact"],"type":"object"},"output_encrypted":{"type":"boolean"},"retention":{"$ref":"#/components/schemas/RetentionOptions"},"status":{"enum":["queued","running","succeeded","failed","cancelled"]},"usage":{"anyOf":[{"$ref":"#/components/schemas/Usage"},{"type":"null"}]}},"required":["id","object","status","mode","input","output","metadata","created_at","output_encrypted","usage","completed_at","content_expires_at","content_deleted_at","error"],"type":"object"},"ConversionRequest":{"additionalProperties":false,"properties":{"inference":{"$ref":"#/components/schemas/InferenceRequest"},"input":{"additionalProperties":false,"properties":{"file_id":{"type":"string"}},"required":["file_id"],"type":"object"},"limits":{"$ref":"#/components/schemas/Limits"},"metadata":{"$ref":"#/components/schemas/Metadata"},"output":{"additionalProperties":false,"properties":{"format":{"enum":["docx","pdf","md","html","txt"]}},"required":["format"],"type":"object"},"output_encryption":{"$ref":"#/components/schemas/OutputEncryption"},"retention":{"$ref":"#/components/schemas/RetentionOptions"}},"required":["input","output"],"type":"object"},"Cost":{"additionalProperties":false,"description":"Settled customer charges. Itemized base, CPU and inference fees are disjoint and sum exactly to total_usd. Inference includes model processing and web search. No overlapping platform subtotal. Balances and limits are separate from cost.","example":{"itemized":{"base_fee_usd":"0.250000000","cpu_fee_usd":"0.005000000","inference_fee_usd":"0.050000000"},"total_usd":"0.305000000"},"properties":{"itemized":{"additionalProperties":false,"properties":{"base_fee_usd":{"example":"0.250000000","pattern":"^[0-9]+\\.[0-9]{9}$","type":"string"},"cpu_fee_usd":{"example":"0.005000000","pattern":"^[0-9]+\\.[0-9]{9}$","type":"string"},"inference_fee_usd":{"example":"0.050000000","pattern":"^[0-9]+\\.[0-9]{9}$","type":"string"}},"required":["base_fee_usd","cpu_fee_usd","inference_fee_usd"],"type":"object"},"total_usd":{"example":"0.305000000","pattern":"^[0-9]+\\.[0-9]{9}$","type":"string"}},"required":["total_usd","itemized"],"type":"object"},"Error":{"additionalProperties":false,"properties":{"error":{"additionalProperties":false,"properties":{"code":{"type":"string"},"details":{"additionalProperties":true,"type":"object"},"message":{"type":"string"}},"required":["code","message"],"type":"object"}},"required":["error"],"type":"object"},"File":{"additionalProperties":false,"properties":{"bytes":{"type":"integer"},"created_at":{"format":"date-time","type":"string"},"deleted_at":{"format":"date-time","type":["string","null"]},"expires_at":{"format":"date-time","type":["string","null"]},"filename":{"description":"Empty once expired or deleted.","type":"string"},"id":{"type":"string"},"lifetime":{"enum":["ephemeral","persistent"],"type":"string"},"sha256":{"type":"string"},"status":{"enum":["uploaded","expired","deleted"],"type":"string"}},"required":["id","filename","bytes","sha256","status","created_at","expires_at"],"type":"object"},"FundingOrder":{"additionalProperties":false,"properties":{"amount_cents":{"type":"integer"},"automatic":{"type":"boolean"},"created_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"status":{"enum":["pending","succeeded","failed","needs_reconciliation","requires_action"]}},"required":["id","amount_cents","automatic","status","created_at"],"type":"object"},"InferenceRequest":{"additionalProperties":false,"properties":{"billing":{"description":"Which party pays for inference. Omitted or \"revise\" is automatic: the account's stored key for the resolved provider is used when present (billed by the provider, no Revise inference charge), otherwise managed inference applies. \"provider\" requires a stored key for the resolved provider and fails admission with provider_key_required instead of falling back. Provider resolution includes defaults and predecessor inheritance, so an omitted provider still uses the account key.","enum":["revise","provider"]},"model":{"type":"string"},"provider":{"enum":["openai","anthropic","xai","gemini"]}},"required":[],"type":"object"},"Ledger":{"additionalProperties":false,"properties":{"data":{"items":{"additionalProperties":false,"properties":{"available_delta_usd":{"description":"Signed net change to the credit balance for this entry. Historical reservation holds and their releases net to zero.","example":"0.050000000","pattern":"^-?[0-9]+\\.[0-9]{9}$","type":"string"},"created_at":{"format":"date-time","type":"string"},"id":{"type":"integer"},"kind":{"type":"string"},"prompt_id":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","kind","prompt_id","available_delta_usd","created_at"],"type":"object"},"type":"array"},"limit":{"const":50}},"required":["data","limit"],"type":"object"},"Limits":{"additionalProperties":false,"description":"The base fee is graduated per API account each UTC calendar month: requests 1-1000 $0.05, 1001-5000 $0.035, 5001-10000 $0.02, then $0.01. Each newly accepted request counts once across all keys, including later failures/cancellations. Retries with the same idempotency key do not count again. The rate is pinned on admission; CPU and inference rates do not change with volume.","example":{"max_inference_cost_usd":"3.000000000","max_platform_cost_usd":"2.000000000","max_seconds":900},"properties":{"max_inference_cost_usd":{"description":"Soft spending threshold checked against reported inference cost, including premium and search. No predicted cost is reserved; the last response may exceed this amount and is billed in full. On a request billed by the account's own provider key the threshold meters the provider's list-price spend instead; Revise still charges nothing for that inference.","oneOf":[{"pattern":"^[0-9]+(\\.[0-9]{1,9})?$","type":"string"},{"maximum":1000000,"minimum":0,"type":"number"}]},"max_platform_cost_usd":{"description":"Soft spending threshold. New model calls stop when observed platform cost reaches this amount; active responses and tools finish and are billed in full.","oneOf":[{"pattern":"^[0-9]+(\\.[0-9]{1,9})?$","type":"string"},{"maximum":1000000,"minimum":0,"type":"number"}]},"max_seconds":{"description":"Soft work budget in seconds (minimum 120). Active model responses finish normally; no new turn starts after the deadline, and exports may finish later.","maximum":3600,"minimum":120,"type":"integer"}},"required":[],"type":"object"},"Message":{"additionalProperties":false,"properties":{"citations":{"items":{"$ref":"#/components/schemas/Citation"},"type":"array"},"content":{"type":"string"},"incomplete":{"type":"boolean"},"role":{"const":"assistant"}},"required":["role","content","incomplete"],"type":"object"},"Metadata":{"additionalProperties":{"maxLength":512,"type":"string"},"example":{"customer":"acme","environment":"production"},"maxProperties":16,"propertyNames":{"maxLength":64,"minLength":1},"type":"object"},"Model":{"additionalProperties":false,"properties":{"default_for_provider":{"example":true,"type":"boolean"},"id":{"example":"gpt-5.6-luna","type":"string"},"name":{"example":"GPT 5.6 Luna","type":"string"},"provider":{"enum":["openai","anthropic","xai","gemini"],"type":"string"}},"required":["id","provider","name","default_for_provider"],"type":"object"},"ModelList":{"additionalProperties":false,"example":{"data":[{"default_for_provider":true,"id":"gpt-5.6-luna","name":"GPT 5.6 Luna","provider":"openai"}],"default":{"model":"gpt-5.6-luna","provider":"openai"}},"properties":{"data":{"items":{"$ref":"#/components/schemas/Model"},"type":"array"},"default":{"additionalProperties":false,"properties":{"model":{"type":"string"},"provider":{"enum":["openai","anthropic","xai","gemini"],"type":"string"}},"required":["provider","model"],"type":"object"}},"required":["data","default"],"type":"object"},"NativeCommentThread":{"additionalProperties":true,"description":"Unmodified native ReviseCommentThread projection; camelCase fields and many-to-one suggestion links are retained.","properties":{"anchor":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}]},"relatedSuggestionIds":{"items":{"type":"string"},"type":"array"},"replies":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"root":{"additionalProperties":true,"type":"object"}},"required":["root","replies"],"type":"object"},"NativeTrackedChange":{"additionalProperties":true,"description":"Unmodified native ReviseTrackedChange projection.","properties":{"blockIds":{"items":{"type":"string"},"type":"array"},"commentThreadId":{"type":"string"},"id":{"type":"string"},"kind":{"type":"string"}},"required":["id","kind"],"type":"object"},"OutputEncryption":{"additionalProperties":false,"description":"Encrypt exported artifact bytes using compact JWE, RSA-OAEP-256 and A256GCM. Only encrypted files are downloadable. Disables prompt continuation and artifact reuse; cannot be combined with previous_prompt_id or artifact_id input. Prompts require editing or export_document=true.","properties":{"format":{"enum":["jwe"],"type":"string"},"public_key_pem":{"description":"RSA SubjectPublicKeyInfo PEM (BEGIN PUBLIC KEY), 2048–8192 bits. Private keys, certificates and key URLs are rejected.","maxLength":16384,"type":"string"}},"required":["format","public_key_pem"],"type":"object"},"Prompt":{"additionalProperties":false,"properties":{"api_key_id":{"description":"Non-secret ID of the key that originally submitted this prompt; null when not recorded. Idempotent retries preserve the original key.","type":["string","null"]},"artifacts":{"items":{"$ref":"#/components/schemas/Artifact"},"type":"array"},"changes":{"description":"Omitted when disabled by the stored response_options. Otherwise returns the existing native schema.","items":{"$ref":"#/components/schemas/NativeTrackedChange"},"type":"array"},"comments":{"description":"Omitted when disabled by the stored response_options. Otherwise returns the existing native schema.","items":{"$ref":"#/components/schemas/NativeCommentThread"},"type":"array"},"completed_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"content_deleted_at":{"format":"date-time","type":["string","null"]},"content_expires_at":{"description":"24 hours after terminal completion. Result content and new continuation become unavailable at this deadline.","format":"date-time","type":["string","null"]},"continuation":{"$ref":"#/components/schemas/Continuation"},"conversation_expires_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"conversation_id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"error":{"anyOf":[{"additionalProperties":false,"properties":{"code":{"type":"string"},"details":{"additionalProperties":true,"type":"object"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},{"type":"null"}]},"id":{"type":"string"},"incomplete":{"description":"True when the request returned a partial result.","type":"boolean"},"inference":{"additionalProperties":false,"properties":{"billing":{"description":"The billing that applied at admission; fixed for the life of the request even if account keys change later.","enum":["revise","provider"]},"model":{"type":"string"},"provider":{"enum":["openai","anthropic","xai","gemini"]}},"required":["provider","model","billing"],"type":"object"},"limits":{"additionalProperties":false,"properties":{"max_inference_cost_usd":{"example":"0.050000000","pattern":"^-?[0-9]+\\.[0-9]{9}$","type":"string"},"max_platform_cost_usd":{"example":"0.050000000","pattern":"^-?[0-9]+\\.[0-9]{9}$","type":"string"},"max_seconds":{"type":"integer"}},"required":["max_platform_cost_usd","max_inference_cost_usd","max_seconds"],"type":"object"},"message":{"anyOf":[{"$ref":"#/components/schemas/Message"},{"type":"null"}]},"metadata":{"$ref":"#/components/schemas/Metadata"},"output_encrypted":{"description":"True disables continuation and reuse. Artifacts are encrypted for the supplied public key.","type":"boolean"},"previous_prompt_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"retention":{"$ref":"#/components/schemas/RetentionOptions"},"status":{"enum":["queued","running","paused","succeeded","failed","cancelled"]},"stop_reason":{"description":"Limit that ended further agent work. The current result is returned; successful partial results incur the base fee even without inference, plus actual billable usage.","enum":["spending_limit","time_limit"],"type":"string"},"usage":{"anyOf":[{"$ref":"#/components/schemas/Usage"},{"type":"null"}]}},"required":["id","conversation_id","previous_prompt_id","status","created_at","completed_at","conversation_expires_at","message","continuation","artifacts","usage","metadata","inference","limits","error","api_key_id","output_encrypted"],"type":"object"},"PromptRequest":{"additionalProperties":false,"description":"Prompt the shared Revise agent. Native web search is enabled by default. Provider-reported token usage and search fees are included in inference charges, with the configured premium and soft customer spending thresholds. When the account holds a provider key for the resolved provider the request runs on that key: the key is pinned at admission, deleting or replacing it fails the request at its next model call with credential_unavailable (no managed fallback), and provider error text is withheld from results.","example":{"document_access":"read","metadata":{"customer":"acme","environment":"development"},"prompt":"Rewrite this paragraph in a clear, professional tone: We got your request and will get back to you soon."},"properties":{"document_access":{"default":"read","enum":["read","comment","edit"]},"export_document":{"type":"boolean"},"inference":{"$ref":"#/components/schemas/InferenceRequest"},"inputs":{"items":{"$ref":"#/components/schemas/Target"},"maxItems":1,"type":"array"},"limits":{"$ref":"#/components/schemas/Limits"},"metadata":{"$ref":"#/components/schemas/Metadata"},"output_encryption":{"$ref":"#/components/schemas/OutputEncryption"},"previous_prompt_id":{"type":"string"},"prompt":{"maxLength":1048576,"minLength":1,"type":"string"},"response_options":{"$ref":"#/components/schemas/ResponseOptions"},"retention":{"$ref":"#/components/schemas/RetentionOptions"}},"required":["prompt"],"type":"object"},"ResponseOptions":{"additionalProperties":false,"description":"Persisted response policy. False omits the corresponding top-level JSON field from submission, polling, history and replay responses; it does not change the document or native state. Omitted options inherit from an unencrypted predecessor or reused artifact, otherwise default to true.","properties":{"include_changes":{"default":true,"type":"boolean"},"include_comments":{"default":true,"type":"boolean"}},"type":"object"},"RetentionOptions":{"additionalProperties":false,"properties":{"delete_after_webhook_id":{"description":"Account-owned endpoint subscribed to prompt.completed or conversion.completed, matching the request kind. Its successful acknowledgement deletes request content and ephemeral source. Download everything before returning 2xx.","pattern":"^wh_[0-9a-f-]{36}$","type":"string"}},"required":["delete_after_webhook_id"],"type":"object"},"Target":{"additionalProperties":false,"oneOf":[{"not":{"required":["artifact_id"]},"required":["file_id"]},{"not":{"required":["file_id"]},"required":["artifact_id"]}],"properties":{"artifact_id":{"type":"string"},"file_id":{"type":"string"},"role":{"const":"target"}},"required":["role"],"type":"object"},"Usage":{"additionalProperties":false,"description":"Customer-facing settled charges and usage. Supplier costs, margins and internal reconciliation diagnostics are not exposed. Historical charges are never recalculated using current prices.","example":{"cost":{"itemized":{"base_fee_usd":"0.050000000","cpu_fee_usd":"0.001000000","inference_fee_usd":"0.010000000"},"total_usd":"0.061000000"},"inference":{"billed_by":"revise","cache_creation_input_tokens":0,"cached_input_tokens":400,"input_tokens":1200,"output_tokens":200,"web_search_requests":1,"web_search_unit":"calls"},"platform":{"tool_cpu_rate_usd_per_second":"0.001000000","tool_cpu_seconds":"1.000000"},"pricing_version":"local-v5-monthly-fees"},"properties":{"conversion":{"additionalProperties":false,"description":"Present on settled conversion receipts. The base_fee_usd cost item is max(minimum_fee_usd, output_words multiplied by the per-word rate).","properties":{"minimum_fee_usd":{"example":"0.100000000","pattern":"^-?[0-9]+\\.[0-9]{9}$","type":"string"},"output_words":{"minimum":0,"type":"integer"},"rate_usd_per_1000_words":{"example":"0.020000000","pattern":"^-?[0-9]+\\.[0-9]{9}$","type":"string"}},"required":["output_words","rate_usd_per_1000_words","minimum_fee_usd"],"type":"object"},"cost":{"$ref":"#/components/schemas/Cost"},"inference":{"additionalProperties":false,"description":"Includes model input, cache reads/writes, output and reasoning, compaction, and native web/X search or Google grounding. Search units depend on provider. Provider-reported usage counts are omitted on older receipts. For conversions, managed scan inference is included in the output-word conversion fee, so inference_fee_usd is zero. Aggregate token counts do not imply a single inference rate; historical per-category rates are not available in this receipt.","properties":{"billed_by":{"description":"\"provider\" when the account's own key paid the supplier: inference_fee_usd is then zero, token counts are still reported, and no supplier amount is exposed.","enum":["revise","provider"]},"cache_creation_input_tokens":{"minimum":0,"type":"integer"},"cached_input_tokens":{"minimum":0,"type":"integer"},"input_tokens":{"minimum":0,"type":"integer"},"output_tokens":{"minimum":0,"type":"integer"},"web_search_requests":{"minimum":0,"type":"integer"},"web_search_unit":{"enum":["calls","queries","grounded_prompts"],"type":"string"}},"required":["billed_by"],"type":"object"},"platform":{"additionalProperties":false,"properties":{"tool_cpu_rate_usd_per_second":{"example":"0.050000000","pattern":"^-?[0-9]+\\.[0-9]{9}$","type":"string"},"tool_cpu_seconds":{"example":"1.250000","pattern":"^[0-9]+\\.[0-9]{6}$","type":"string"}},"required":["tool_cpu_seconds","tool_cpu_rate_usd_per_second"],"type":"object"},"pricing_version":{"type":"string"}},"required":["pricing_version","platform","inference","cost"],"type":"object"},"UsageBucket":{"additionalProperties":false,"description":"Only occupied buckets are returned. Bounds are clipped to the requested interval. Both bounds are null for bucket=none. Missing dimension values are null, distinct from empty strings.","example":{"bucket_end":"2026-09-07T00:00:00Z","bucket_start":"2026-09-06T00:00:00Z","cost":{"itemized":{"base_fee_usd":"0.100000000","cpu_fee_usd":"0.002000000","inference_fee_usd":"0.020000000"},"total_usd":"0.122000000"},"dimensions":{"metadata.customer":"acme"},"inference_usage":{"cache_creation_input_tokens":0,"cached_input_tokens":800,"input_tokens":2400,"output_tokens":400,"web_search_requests_by_unit":{"calls":2,"grounded_prompts":0,"queries":0}},"request_count":2,"tool_cpu_seconds":"2.000000"},"properties":{"bucket_end":{"example":"2026-09-07T00:00:00Z","format":"date-time","type":["string","null"]},"bucket_start":{"example":"2026-09-06T00:00:00Z","format":"date-time","type":["string","null"]},"cost":{"$ref":"#/components/schemas/Cost"},"dimensions":{"additionalProperties":{"type":["string","null"]},"example":{"metadata.customer":"acme"},"maxProperties":3,"type":"object"},"inference_usage":{"anyOf":[{"$ref":"#/components/schemas/AggregatedInferenceUsage"},{"type":"null"}],"description":"Null if any receipt in this aggregate lacks inference counters; charge totals remain complete. Empty aggregates have zero counters.","example":{"cache_creation_input_tokens":0,"cached_input_tokens":800,"input_tokens":2400,"output_tokens":400,"web_search_requests_by_unit":{"calls":2,"grounded_prompts":0,"queries":0}}},"request_count":{"example":2,"minimum":0,"type":"integer"},"tool_cpu_seconds":{"example":"2.000000","pattern":"^[0-9]+\\.[0-9]{6}$","type":"string"}},"required":["bucket_start","bucket_end","dimensions","request_count","tool_cpu_seconds","inference_usage","cost"],"type":"object"},"UsageReport":{"additionalProperties":false,"example":{"bucket":"day","data":[{"bucket_end":"2026-09-07T00:00:00Z","bucket_start":"2026-09-06T00:00:00Z","cost":{"itemized":{"base_fee_usd":"0.100000000","cpu_fee_usd":"0.002000000","inference_fee_usd":"0.020000000"},"total_usd":"0.122000000"},"dimensions":{"metadata.customer":"acme"},"inference_usage":{"cache_creation_input_tokens":0,"cached_input_tokens":800,"input_tokens":2400,"output_tokens":400,"web_search_requests_by_unit":{"calls":2,"grounded_prompts":0,"queries":0}},"request_count":2,"tool_cpu_seconds":"2.000000"},{"bucket_end":"2026-09-08T00:00:00Z","bucket_start":"2026-09-07T00:00:00Z","cost":{"itemized":{"base_fee_usd":"0.150000000","cpu_fee_usd":"0.003000000","inference_fee_usd":"0.030000000"},"total_usd":"0.183000000"},"dimensions":{"metadata.customer":"acme"},"inference_usage":{"cache_creation_input_tokens":0,"cached_input_tokens":1200,"input_tokens":3600,"output_tokens":600,"web_search_requests_by_unit":{"calls":3,"grounded_prompts":0,"queries":0}},"request_count":3,"tool_cpu_seconds":"3.000000"}],"end":"2026-09-08T00:00:00Z","group_by":["metadata.customer"],"start":"2026-09-06T00:00:00Z","time_basis":"completed_at","totals":{"cost":{"itemized":{"base_fee_usd":"0.250000000","cpu_fee_usd":"0.005000000","inference_fee_usd":"0.050000000"},"total_usd":"0.305000000"},"inference_usage":{"cache_creation_input_tokens":0,"cached_input_tokens":2000,"input_tokens":6000,"output_tokens":1000,"web_search_requests_by_unit":{"calls":5,"grounded_prompts":0,"queries":0}},"request_count":5,"tool_cpu_seconds":"5.000000"}},"properties":{"bucket":{"enum":["hour","day","month","none"],"example":"day"},"data":{"example":[{"bucket_end":"2026-09-07T00:00:00Z","bucket_start":"2026-09-06T00:00:00Z","cost":{"itemized":{"base_fee_usd":"0.100000000","cpu_fee_usd":"0.002000000","inference_fee_usd":"0.020000000"},"total_usd":"0.122000000"},"dimensions":{"metadata.customer":"acme"},"inference_usage":{"cache_creation_input_tokens":0,"cached_input_tokens":800,"input_tokens":2400,"output_tokens":400,"web_search_requests_by_unit":{"calls":2,"grounded_prompts":0,"queries":0}},"request_count":2,"tool_cpu_seconds":"2.000000"},{"bucket_end":"2026-09-08T00:00:00Z","bucket_start":"2026-09-07T00:00:00Z","cost":{"itemized":{"base_fee_usd":"0.150000000","cpu_fee_usd":"0.003000000","inference_fee_usd":"0.030000000"},"total_usd":"0.183000000"},"dimensions":{"metadata.customer":"acme"},"inference_usage":{"cache_creation_input_tokens":0,"cached_input_tokens":1200,"input_tokens":3600,"output_tokens":600,"web_search_requests_by_unit":{"calls":3,"grounded_prompts":0,"queries":0}},"request_count":3,"tool_cpu_seconds":"3.000000"}],"items":{"$ref":"#/components/schemas/UsageBucket"},"maxItems":1000,"type":"array"},"end":{"example":"2026-09-08T00:00:00Z","format":"date-time","type":"string"},"group_by":{"example":["metadata.customer"],"items":{"type":"string"},"maxItems":3,"type":"array","uniqueItems":true},"start":{"example":"2026-09-06T00:00:00Z","format":"date-time","type":"string"},"time_basis":{"const":"completed_at","example":"completed_at"},"totals":{"$ref":"#/components/schemas/UsageTotals","example":{"cost":{"itemized":{"base_fee_usd":"0.250000000","cpu_fee_usd":"0.005000000","inference_fee_usd":"0.050000000"},"total_usd":"0.305000000"},"inference_usage":{"cache_creation_input_tokens":0,"cached_input_tokens":2000,"input_tokens":6000,"output_tokens":1000,"web_search_requests_by_unit":{"calls":5,"grounded_prompts":0,"queries":0}},"request_count":5,"tool_cpu_seconds":"5.000000"}}},"required":["start","end","time_basis","bucket","group_by","totals","data"],"type":"object"},"UsageTotals":{"additionalProperties":false,"example":{"cost":{"itemized":{"base_fee_usd":"0.250000000","cpu_fee_usd":"0.005000000","inference_fee_usd":"0.050000000"},"total_usd":"0.305000000"},"inference_usage":{"cache_creation_input_tokens":0,"cached_input_tokens":2000,"input_tokens":6000,"output_tokens":1000,"web_search_requests_by_unit":{"calls":5,"grounded_prompts":0,"queries":0}},"request_count":5,"tool_cpu_seconds":"5.000000"},"properties":{"cost":{"$ref":"#/components/schemas/Cost"},"inference_usage":{"anyOf":[{"$ref":"#/components/schemas/AggregatedInferenceUsage"},{"type":"null"}],"description":"Null if any receipt in this aggregate lacks inference counters; charge totals remain complete. Empty aggregates have zero counters.","example":{"cache_creation_input_tokens":0,"cached_input_tokens":2000,"input_tokens":6000,"output_tokens":1000,"web_search_requests_by_unit":{"calls":5,"grounded_prompts":0,"queries":0}}},"request_count":{"example":5,"minimum":0,"type":"integer"},"tool_cpu_seconds":{"example":"5.000000","pattern":"^[0-9]+\\.[0-9]{6}$","type":"string"}},"required":["request_count","tool_cpu_seconds","inference_usage","cost"],"type":"object"},"Webhook":{"additionalProperties":false,"properties":{"created_at":{"example":"2026-09-08T12:00:00Z","format":"date-time","type":"string"},"deleted_at":{"example":null,"format":"date-time","type":["string","null"]},"events":{"example":["prompt.completed","prompt.failed"],"items":{"enum":["prompt.completed","prompt.failed","prompt.cancelled","prompt.paused","conversion.completed","conversion.failed","conversion.cancelled"],"type":"string"},"maxItems":7,"minItems":1,"type":"array","uniqueItems":true},"id":{"example":"wh_21ff52db-63f9-4a1c-a1ab-8d1a9f11c201","type":"string"},"signing_secret":{"description":"Returned only on creation and its idempotent replay. Store securely.","example":"whsec_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=","type":"string"},"url":{"example":"https://example.com/webhooks/revise","format":"uri","type":"string"}},"required":["id","url","events","created_at","deleted_at"],"type":"object"},"WebhookDelivery":{"additionalProperties":false,"properties":{"attempts":{"example":2,"minimum":0,"type":"integer"},"created_at":{"example":"2026-09-08T12:00:00Z","format":"date-time","type":"string"},"delivered_at":{"example":null,"format":"date-time","type":["string","null"]},"event_id":{"example":"evt_b70793a8-0a0c-4e8f-827d-f1ddba77703f","type":"string"},"event_type":{"example":"prompt.completed","type":"string"},"id":{"example":"del_36106431-4db2-459a-92d9-08ce744d5aac","type":"string"},"last_error":{"example":"http_error","type":["string","null"]},"last_http_status":{"example":503,"type":["integer","null"]},"next_attempt_at":{"example":"2026-09-08T12:02:00Z","format":"date-time","type":["string","null"]},"status":{"enum":["pending","sending","delivered","exhausted","cancelled"],"example":"pending","type":"string"}},"required":["id","event_id","event_type","status","attempts","next_attempt_at","last_http_status","last_error","created_at","delivered_at"],"type":"object"},"WebhookDeliveryList":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/WebhookDelivery"},"type":"array"},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"type":"object"},"WebhookList":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/Webhook"},"type":"array"}},"required":["data"],"type":"object"},"WebhookRetry":{"additionalProperties":false,"properties":{"id":{"type":"string"}},"required":["id"],"type":"object"}},"securitySchemes":{"apiKey":{"description":"API-owned opaque key created by the local admin command.","scheme":"bearer","type":"http"}}},"info":{"description":"Queued document prompting and file conversion. Conversion supports the same formats as revise.io/converter, including semantic PDF/image scanning. USD responses are exact decimal strings. Same-origin downloads require Bearer auth. Account provider keys (BYOK) are pinned at admission. Request content expires 24 hours after terminal completion; encrypted artifacts use compact JWE RSA-OAEP-256/A256GCM.","title":"Revise document API","version":"0.1.0"},"openapi":"3.1.0","paths":{"/api/v1/account":{"get":{"operationId":"getAccount","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}},"description":"The signed credit balance and funding capabilities."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Read the account credit balance"}},"/api/v1/account/ledger":{"get":{"operationId":"getLedger","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ledger"}}},"description":"Read the latest 50 credit entries"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Read the latest 50 credit entries"}},"/api/v1/account/topups/{id}":{"get":{"operationId":"getTopup","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FundingOrder"}}},"description":"Read funding status without payment secrets"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Read funding status without payment secrets"}},"/api/v1/artifacts/{id}":{"get":{"operationId":"getArtifact","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artifact"}}},"description":"Read metadata for an immutable output variant"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Read metadata for an immutable output variant"}},"/api/v1/artifacts/{id}/content":{"get":{"operationId":"downloadArtifact","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/jose":{"example":"protected.encrypted_key.iv.ciphertext.tag","schema":{"type":"string"}},"application/vnd.openxmlformats-officedocument.wordprocessingml.document":{"schema":{"format":"binary","type":"string"}}},"description":"DOCX file"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Download the exact DOCX variant"}},"/api/v1/convert":{"get":{"operationId":"listConversions","parameters":[{"in":"query","name":"limit","schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"cursor","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"enum":["queued","running","succeeded","failed","cancelled"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Conversion"},"type":"array"},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"type":"object"}}},"description":"Conversion page"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"List account conversions, newest first"},"post":{"description":"Conversions cost $0.02 per 1,000 words in the converted output, with a $0.10 minimum. The charge is proportional per word rather than rounded to started 1,000-word units. Managed PDF/image scanning inference is included; when BYOK is selected, the provider separately bills its own inference. Vision conversion rasterizes pages in order and sends up to 10 distinct page images per model request.","operationId":"createConversion","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"maxLength":200,"minLength":1,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversion"}}},"description":"Queued conversion"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Queue a file conversion"}},"/api/v1/convert/{id}":{"get":{"operationId":"getConversion","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversion"}}},"description":"Conversion"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Read conversion status, receipt, and output artifact"}},"/api/v1/convert/{id}/cancel":{"post":{"operationId":"cancelConversion","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversion"}}},"description":"Cancellation requested"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Cancel a queued or running conversion; no body"}},"/api/v1/convert/{id}/content":{"delete":{"description":"Permanently delete retained conversion content and artifact bytes. Metadata and accounting receipts remain available. Repeated deletion succeeds.","operationId":"deleteConversionContent","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted; status, receipt and idempotency tombstone remain"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Delete conversion content"}},"/api/v1/files":{"post":{"operationId":"uploadFile","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"maxLength":200,"minLength":1,"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"additionalProperties":false,"properties":{"file":{"description":"One file with a supported filename. Maximum 18 MiB; 100 files/256 MiB per local account.","format":"binary","type":"string"},"lifetime":{"default":"ephemeral","description":"Ephemeral files can be claimed by one request and are deleted immediately on success. Failed or cancelled requests retain their source for 24 hours; unused uploads expire 24 hours after upload. Persistent templates remain until explicit deletion.","enum":["ephemeral","persistent"],"type":"string"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}},"description":"Idempotent upload replay"},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}},"description":"Upload one immutable target file (DOCX, UTF-8 TXT, MD or HTML)"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Upload one immutable source (PDF, DOCX, MD, HTML, TXT, RTF, ODT, PNG, JPEG, WebP or GIF)"}},"/api/v1/files/{id}":{"delete":{"operationId":"deleteFile","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted; tombstone retained for idempotency"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Delete an uploaded file; rejects active use with 409"},"get":{"operationId":"getFile","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}},"description":"Read uploaded source metadata"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Read uploaded source metadata"}},"/api/v1/models":{"get":{"description":"Authenticated discovery using the same exact model set as prompt admission. No credits or inference are consumed. Pass id as inference.model and provider as inference.provider. Sorted by provider then model ID; complete list, no pagination. Optional provider filter uses gemini, not google. default is the API-wide selection when inference is omitted and is unchanged by filtering; default_for_provider marks the selection when a provider is specified without a model. Names come from the shared model registry, falling back to the raw ID for retained aliases. This is a supported-model catalog, not a live availability, provider-credential or capacity check. Prices and capability claims are omitted. Unknown, duplicate or empty filters return 400.","operationId":"listModels","parameters":[{"description":"Optional exact public provider.","in":"query","name":"provider","schema":{"enum":["openai","anthropic","xai","gemini"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"default_for_provider":true,"id":"gpt-5.6-luna","name":"GPT 5.6 Luna","provider":"openai"}],"default":{"model":"gpt-5.6-luna","provider":"openai"}},"schema":{"$ref":"#/components/schemas/ModelList"}}},"description":"Model catalog"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"List supported prompt models and defaults"}},"/api/v1/prompt":{"post":{"operationId":"createPrompt","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"maxLength":200,"minLength":1,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Prompt"}}},"description":"Queued. The request is admitted while the account balance is positive; its spending thresholds stop new model calls based on observed costs; the final charge can exceed them."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Queue a prompt with its maximum authorized cost"}},"/api/v1/prompt/{id}":{"get":{"operationId":"getPrompt","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Prompt"}}},"description":"Read status and the immutable terminal result"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Read status, receipt, and unexpired result"}},"/api/v1/prompt/{id}/cancel":{"post":{"operationId":"cancelPrompt","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Prompt"}}},"description":"Cancel work; no request body"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Cancel work; no request body"}},"/api/v1/prompt/{id}/content":{"delete":{"description":"No body. Returns 409 for active work or legacy dependent requests requiring the content. Persistent source templates are excluded.","operationId":"deletePromptContent","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted; status, receipt and idempotency tombstone remain"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Delete all request content and ephemeral source"}},"/api/v1/prompt/{id}/resume":{"post":{"operationId":"resumePrompt","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"limits":{"additionalProperties":false,"properties":{"max_inference_cost_usd":{"oneOf":[{"pattern":"^[0-9]+(\\.[0-9]{1,9})?$","type":"string"},{"maximum":1000000,"minimum":0,"type":"number"}]},"max_platform_cost_usd":{"oneOf":[{"pattern":"^[0-9]+(\\.[0-9]{1,9})?$","type":"string"},{"maximum":1000000,"minimum":0,"type":"number"}]}},"required":["max_platform_cost_usd","max_inference_cost_usd"],"type":"object"}},"required":["limits"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Prompt"}}},"description":"Raise absolute cost limits on a paused prompt"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Raise absolute cost limits on a paused prompt"}},"/api/v1/prompts":{"get":{"description":"Returns the same Prompt objects as GET /v1/prompt/{id}. Pass next_cursor as cursor for the next page; null means the end. Ordering is created_at descending, then ID descending. Cursors belong to the authenticated account. Newly submitted requests do not shift subsequent pages. Invalid limits or cursors return 400. Filters combine with AND. Repeat the same filters on each page. Status reflects current state, so this is not a frozen snapshot of mutable fields. Unknown and duplicate parameters return 400.","operationId":"listPrompts","parameters":[{"in":"query","name":"limit","schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"}},{"description":"The next_cursor returned by the previous page.","in":"query","name":"cursor","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"enum":["queued","running","paused","succeeded","failed","cancelled"],"type":"string"}},{"description":"Exact conv_ ID.","in":"query","name":"conversation_id","schema":{"type":"string"}},{"description":"Exact key_ ID of the submitting key. Older unattributed prompts do not match.","in":"query","name":"api_key_id","schema":{"type":"string"}},{"description":"Inclusive lower creation-time bound (RFC3339 with timezone).","in":"query","name":"created_after","schema":{"format":"date-time","type":"string"}},{"description":"Exclusive upper creation-time bound (RFC3339 with timezone).","in":"query","name":"created_before","schema":{"format":"date-time","type":"string"}},{"description":"Exact AND matches, e.g. metadata[customer]=Acme. Keys up to 64 bytes; values up to 512 bytes.","explode":true,"in":"query","name":"metadata","schema":{"additionalProperties":{"maxLength":512,"type":"string"},"maxProperties":16,"type":"object"},"style":"deepObject"}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/Prompt"},"maxItems":100,"type":"array"},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"type":"object"}}},"description":"A page of prompts"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"List account prompts, newest first"}},"/api/v1/usage":{"get":{"description":"Account-scoped, receipt-based aggregation by completion time, including succeeded, failed and cancelled requests with settled receipts; pending requests are excluded. Filters combine with AND. No document, comment, prompt, artifact, supplier-cost or margin data is read or returned. Totals cover the entire filtered interval and reconcile with receipt charges, not current rates. Model/provider dimensions describe the requested configuration. No implied blended rates are returned. Money uses exact decimal strings. Rows sort by bucket then dimensions; each request contributes once. More than 1000 rows returns 422 with no partial report: narrow filters/range, reduce dimensions or use coarser buckets. Queries time out after five seconds (503). Reports use one database statement snapshot; no snapshot cursor or pagination. Fixed past completion windows stabilize once settled; future/open windows grow as requests finish. Unknown, empty or repeated parameters return 400; empty metadata filter values are allowed.","operationId":"getUsage","parameters":[{"description":"Inclusive completion time. Defaults to 30 days before end. RFC3339 timezone required.","in":"query","name":"start","schema":{"format":"date-time","type":"string"}},{"description":"Exclusive completion time. Defaults to now. Range must be positive and at most 366 days; hourly ranges at most 31 days.","in":"query","name":"end","schema":{"format":"date-time","type":"string"}},{"description":"UTC calendar buckets, or no time bucketing. Empty time buckets are omitted.","in":"query","name":"bucket","schema":{"default":"day","enum":["hour","day","month","none"],"type":"string"}},{"description":"Comma-separated distinct dimensions, maximum three: api_key_id, provider, model, status, document_access, pricing_version, metadata.KEY (KEY 1–64 bytes). Missing values form null groups. Example: api_key_id,metadata.customer.","in":"query","name":"group_by","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"enum":["succeeded","failed","cancelled"],"type":"string"}},{"description":"Exact conv_ ID.","in":"query","name":"conversation_id","schema":{"type":"string"}},{"description":"Exact key_ ID of the submitting key. Older unattributed prompts do not match.","in":"query","name":"api_key_id","schema":{"type":"string"}},{"description":"Exact AND matches, e.g. metadata[customer]=Acme. Keys up to 64 bytes; values up to 512 bytes.","explode":true,"in":"query","name":"metadata","schema":{"additionalProperties":{"maxLength":512,"type":"string"},"maxProperties":16,"type":"object"},"style":"deepObject"},{"description":"Exact requested provider. Gemini uses the public name gemini.","in":"query","name":"provider","schema":{"enum":["openai","anthropic","xai","gemini"],"type":"string"}},{"description":"Exact requested model ID; use with provider to disambiguate.","in":"query","name":"model","schema":{"maxLength":256,"type":"string"}},{"description":"Exact admitted document permission; not inferred from tool behavior.","in":"query","name":"document_access","schema":{"enum":["read","comment","edit"],"type":"string"}},{"description":"Exact pricing version pinned at admission.","in":"query","name":"pricing_version","schema":{"maxLength":256,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"bucket":"day","data":[{"bucket_end":"2026-09-07T00:00:00Z","bucket_start":"2026-09-06T00:00:00Z","cost":{"itemized":{"base_fee_usd":"0.100000000","cpu_fee_usd":"0.002000000","inference_fee_usd":"0.020000000"},"total_usd":"0.122000000"},"dimensions":{"metadata.customer":"acme"},"inference_usage":{"cache_creation_input_tokens":0,"cached_input_tokens":800,"input_tokens":2400,"output_tokens":400,"web_search_requests_by_unit":{"calls":2,"grounded_prompts":0,"queries":0}},"request_count":2,"tool_cpu_seconds":"2.000000"},{"bucket_end":"2026-09-08T00:00:00Z","bucket_start":"2026-09-07T00:00:00Z","cost":{"itemized":{"base_fee_usd":"0.150000000","cpu_fee_usd":"0.003000000","inference_fee_usd":"0.030000000"},"total_usd":"0.183000000"},"dimensions":{"metadata.customer":"acme"},"inference_usage":{"cache_creation_input_tokens":0,"cached_input_tokens":1200,"input_tokens":3600,"output_tokens":600,"web_search_requests_by_unit":{"calls":3,"grounded_prompts":0,"queries":0}},"request_count":3,"tool_cpu_seconds":"3.000000"}],"end":"2026-09-08T00:00:00Z","group_by":["metadata.customer"],"start":"2026-09-06T00:00:00Z","time_basis":"completed_at","totals":{"cost":{"itemized":{"base_fee_usd":"0.250000000","cpu_fee_usd":"0.005000000","inference_fee_usd":"0.050000000"},"total_usd":"0.305000000"},"inference_usage":{"cache_creation_input_tokens":0,"cached_input_tokens":2000,"input_tokens":6000,"output_tokens":1000,"web_search_requests_by_unit":{"calls":5,"grounded_prompts":0,"queries":0}},"request_count":5,"tool_cpu_seconds":"5.000000"}},"schema":{"$ref":"#/components/schemas/UsageReport"}}},"description":"Complete filtered usage report"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Aggregate settled account usage and customer charges"}},"/api/v1/webhooks":{"get":{"operationId":"listWebhooks","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookList"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"List active webhook endpoints (no signing secrets)"},"post":{"description":"Maximum 10 active endpoints. HTTPS port 443 and public addresses only. Signing secret is encrypted at rest. Same key/body replays creation; different body returns 409.","operationId":"createWebhook","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"maxLength":128,"minLength":1,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"events":{"items":{"enum":["prompt.completed","prompt.failed","prompt.cancelled","prompt.paused","conversion.completed","conversion.failed","conversion.cancelled"],"type":"string"},"maxItems":7,"minItems":1,"type":"array","uniqueItems":true},"url":{"example":"https://app.example.com/hooks/revise","format":"uri","type":"string"}},"required":["url","events"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Register an HTTPS webhook endpoint"}},"/api/v1/webhooks/{id}":{"delete":{"operationId":"deleteWebhook","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted (idempotent); an in-flight request may already have reached the receiver"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Disable endpoint and cancel pending deliveries"}},"/api/v1/webhooks/{id}/deliveries":{"get":{"description":"Newest first, scoped cursor. Retained for 30 days. Payloads, target response bodies, and secrets are not returned.","operationId":"listWebhookDeliveries","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"limit","required":false,"schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"cursor","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryList"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"List delivery history"}},"/api/v1/webhooks/{id}/deliveries/{delivery_id}/retry":{"post":{"description":"No body. Up to 3 manual retry cycles within 7 days. Preserves notification ID and bytes; never restores deleted content. Retry acknowledgements after deletion remain safe.","operationId":"retryWebhookDelivery","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"delivery_id","required":true,"schema":{"type":"string"}},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"maxLength":128,"minLength":1,"type":"string"}}],"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRetry"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Retry an exhausted delivery"}}},"security":[{"apiKey":[]}],"servers":[{"url":"/"}]}