{"openapi":"3.1.0","info":{"title":"Brale Network API","version":"1.5.0","description":"Public API for querying stablecoins, branded assets, and cross-chain value movement on the Brale network. All endpoints are free, open, and require no authentication.","contact":{"name":"Brale","url":"https://brale.xyz","email":"support@brale.xyz"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://brale.network/api"}],"tags":[{"name":"Value Type","description":"Tokenized value definitions (stablecoins, branded assets)"},{"name":"Transfer Type","description":"Ledgers and rails carrying value (Base, Solana, etc.)"},{"name":"Price","description":"Reference prices and primary market volume data for value types"},{"name":"Token List","description":"Uniswap Token List format exports"},{"name":"LLM Context","description":"Structured context for AI/LLM consumption"},{"name":"Analytics","description":"Network summary statistics"},{"name":"Discovery","description":"Machine-readable endpoint listing"},{"name":"MCP","description":"Model Context Protocol (JSON-RPC 2.0)"}],"paths":{"/value-type/list":{"get":{"operationId":"listValueTypes","summary":"List all value types","tags":["Value Type"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data","count"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ValueType"}},"count":{"type":"integer"}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/value-type/{id}":{"get":{"operationId":"getValueType","summary":"Get a single value type by ID or symbol","tags":["Value Type"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Value type symbol (e.g. SBC, USDC, CFUSD)"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ValueType"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/value-type/{id}/transfer-type/list":{"get":{"operationId":"listTransferTypesForValueType","summary":"List transfer types supporting a given value type","tags":["Value Type"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Value type ID or symbol"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data","count"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TransferTypeRef"}},"count":{"type":"integer"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/transfer-type/list":{"get":{"operationId":"listTransferTypes","summary":"List all transfer types","tags":["Transfer Type"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data","count"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TransferType"}},"count":{"type":"integer"}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/transfer-type/{id}":{"get":{"operationId":"getTransferType","summary":"Get a single transfer type by ID or slug","tags":["Transfer Type"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Transfer type slug (e.g. base, solana)"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/TransferType"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/transfer-type/{id}/value-type/list":{"get":{"operationId":"listValueTypesForTransferType","summary":"List value types available on a given transfer type","tags":["Transfer Type"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Transfer type ID or slug"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data","count"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ValueTypeRef"}},"count":{"type":"integer"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/price/list":{"get":{"operationId":"listPrices","summary":"List prices and primary market data for all value types","description":"Returns reference prices with 24h primary-market volume data (mints, burns, transfers) for every tracked value type.","tags":["Price"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data","count"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"count":{"type":"integer"}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/price/{value_type}":{"get":{"operationId":"getPrice","summary":"Get price and primary market data for a value type","description":"Returns the reference price with 24h primary-market volume aggregated across all chains, plus a per-chain breakdown.","tags":["Price"],"parameters":[{"name":"value_type","in":"path","required":true,"schema":{"type":"string"},"description":"Value type symbol (e.g. USDC, SBC)"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PriceDetail"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/price/{value_type}/{transfer_type}":{"get":{"operationId":"getPriceByChain","summary":"Get price and primary market data for a value type on a specific chain","description":"Returns the reference price with 24h primary-market volume scoped to a single transfer type (chain).","tags":["Price"],"parameters":[{"name":"value_type","in":"path","required":true,"schema":{"type":"string"},"description":"Value type symbol (e.g. SBC)"},{"name":"transfer_type","in":"path","required":true,"schema":{"type":"string"},"description":"Transfer type slug (e.g. base, solana)"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PriceChain"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/tokenlist/brale.json":{"get":{"operationId":"getTokenListBrale","summary":"Full Brale token list in Uniswap Token List format","tags":["Token List"],"responses":{"200":{"description":"Uniswap Token List JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenList"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/tokenlist/uniswap.json":{"get":{"operationId":"getTokenListUniswap","summary":"EVM-only token list in Uniswap Token List format","tags":["Token List"],"responses":{"200":{"description":"Uniswap Token List JSON (EVM chains only)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenList"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/tokenlist/{transfer_type}":{"get":{"operationId":"getTokenListByTransferType","summary":"Token list filtered to a specific transfer type","tags":["Token List"],"parameters":[{"name":"transfer_type","in":"path","required":true,"schema":{"type":"string"},"description":"Transfer type slug (e.g. base, solana)"}],"responses":{"200":{"description":"Uniswap Token List JSON for the specified transfer type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenList"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/llms/value-types.json":{"get":{"operationId":"getLlmValueTypes","summary":"Structured AI context for value types","tags":["LLM Context"],"responses":{"200":{"description":"LLM-optimized value type data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LlmContext"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/llms/transfer-types.json":{"get":{"operationId":"getLlmTransferTypes","summary":"Structured AI context for transfer types","tags":["LLM Context"],"responses":{"200":{"description":"LLM-optimized transfer type data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LlmContext"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/llms/static-context.json":{"get":{"operationId":"getLlmStaticContext","summary":"Complete platform context for AI consumption","tags":["LLM Context"],"responses":{"200":{"description":"Full platform context including value types, transfer types, and metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LlmFullContext"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/analytics/summary":{"get":{"operationId":"getAnalyticsSummary","summary":"Network summary statistics","tags":["Analytics"],"responses":{"200":{"description":"Aggregate network stats","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsSummary"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/capabilities":{"get":{"operationId":"getCapabilities","summary":"Machine-readable endpoint listing","tags":["Discovery"],"responses":{"200":{"description":"List of available API endpoints with descriptions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapabilitiesResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/errors":{"get":{"operationId":"getErrorCatalog","summary":"Machine-readable error catalog","description":"Returns all API error codes, HTTP status mappings, rate limit policy, MCP error codes, and recovery hints. Agents should consult this endpoint to understand error handling and retry strategies.","tags":["Discovery"],"responses":{"200":{"description":"Structured error catalog with codes, recovery hints, and rate limit policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorCatalog"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/market/{value_type}/{transfer_type}":{"get":{"operationId":"getMarketData","summary":"Detailed primary market activity (planned)","description":"Returns 501 Not Implemented. When available, will provide directional breakdown (mints vs burns), time-bucketed volume, and recent trade list for a value type on a specific chain.","tags":["Price"],"parameters":[{"name":"value_type","in":"path","required":true,"schema":{"type":"string"},"description":"Value type symbol (e.g. SBC)"},{"name":"transfer_type","in":"path","required":true,"schema":{"type":"string"},"description":"Transfer type slug (e.g. base, solana)"}],"responses":{"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"Not yet implemented","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlannedEndpoint"}}}}}}},"/quote":{"post":{"operationId":"getQuote","summary":"Request a mint/redeem quote (planned)","description":"Returns 501 Not Implemented. When available, will return an actionable price quote with expiry for minting or redeeming a value type.","tags":["Price"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["value_type","transfer_type","direction","amount"],"properties":{"value_type":{"type":"string","description":"Value type symbol (e.g. SBC)"},"transfer_type":{"type":"string","description":"Transfer type slug (e.g. base)"},"direction":{"type":"string","enum":["mint","burn"]},"amount":{"type":"string","description":"Amount in normalized units (e.g. \"1000.00\")"}}}}}},"responses":{"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"Not yet implemented","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlannedEndpoint"}}}}}}},"/mcp":{"post":{"operationId":"mcpRequest","summary":"MCP Streamable HTTP endpoint","description":"Accepts JSON-RPC 2.0 requests conforming to the Model Context Protocol.","tags":["MCP"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"integer"}]},"method":{"type":"string"},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"integer"},{"type":"null"}]},"result":{},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{}}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"schemas":{"ProgramRef":{"description":"Reference to an issuer program managing one or more value types.","type":"object","required":["id","name","operator","slug"],"properties":{"id":{"type":"string","examples":["stablecoin"]},"name":{"type":"string","examples":["Stable Coin"]},"operator":{"type":"string","examples":["stablecoin.xyz"]},"slug":{"type":"string","examples":["stablecoin"]}}},"TransferTypeRef":{"description":"Compact reference to a transfer type (blockchain or ledger) with the contract address for this deployment.","type":"object","required":["id","slug","display_name","contract_address"],"properties":{"id":{"type":"string","examples":["base"]},"slug":{"type":"string","examples":["base"]},"display_name":{"type":"string","examples":["Base"]},"contract_address":{"type":"string","examples":["0x1234..."]}}},"ValueTypeRef":{"description":"Compact reference to a value type (stablecoin or branded asset) with contract address on a specific chain.","type":"object","required":["id","symbol","display_name","contract_address"],"properties":{"id":{"type":"string","examples":["USDC"]},"symbol":{"type":"string","examples":["USDC"]},"display_name":{"type":"string","examples":["USD Coin"]},"contract_address":{"type":"string","examples":["0x1234..."]}}},"ValueType":{"description":"A tokenized value type such as a fiat stablecoin or branded asset. Includes metadata, issuer program, and all chain deployments.","type":"object","required":["id","symbol","display_name","description","value_type","decimals","logo_url","website_url","program","transfer_types","contract_addresses"],"properties":{"id":{"type":"string","examples":["SBC"]},"symbol":{"type":"string","examples":["SBC"]},"display_name":{"type":"string","examples":["Stable Coin"]},"description":{"type":["string","null"]},"value_type":{"type":"string","examples":["fiat_stablecoin"]},"decimals":{"type":"integer","examples":[6]},"logo_url":{"type":["string","null"]},"website_url":{"type":["string","null"],"examples":["https://brale.xyz"]},"program":{"$ref":"#/components/schemas/ProgramRef"},"transfer_types":{"type":"array","items":{"$ref":"#/components/schemas/TransferTypeRef"}},"contract_addresses":{"type":"object","additionalProperties":{"type":"string"},"examples":[{"base":"0x1234..."}]}}},"TransferType":{"description":"A blockchain or ledger that carries value types. Includes network metadata and all value types deployed on it.","type":"object","required":["id","slug","display_name","ecosystem_family","network_type","is_evm","is_testnet","is_private_ledger","native_symbol","status","availability_note","explorer_url","value_types"],"properties":{"id":{"type":"string","examples":["base"]},"slug":{"type":"string","examples":["base"]},"display_name":{"type":"string","examples":["Base"]},"ecosystem_family":{"type":"string","examples":["evm"]},"network_type":{"type":"string","examples":["mainnet"]},"is_evm":{"type":"boolean"},"is_testnet":{"type":"boolean"},"is_private_ledger":{"type":"boolean"},"native_symbol":{"type":"string","examples":["ETH"]},"status":{"type":"string","enum":["active","inactive"],"examples":["active"]},"availability_note":{"type":["string","null"],"description":"Explains why a transfer type may have no public value types (e.g. private ledger)."},"explorer_url":{"type":["string","null"],"examples":["https://basescan.org"]},"value_types":{"type":"array","items":{"$ref":"#/components/schemas/ValueTypeRef"}}}},"ReferencePrice":{"description":"The issuer-declared peg price. For all current Brale value types this is 1:1 USD.","type":"object","required":["price"],"properties":{"price":{"type":"string","examples":["1.00"]}}},"PrimaryMarket":{"description":"Primary market data derived from real on-chain mint/burn/transfer transactions over the last 24 hours.","type":"object","required":["price","volume_24h_usd","mints_24h_usd","burns_24h_usd","transfers_24h_usd","tx_count_24h","last_observed_at"],"properties":{"price":{"type":"string","examples":["1.00"]},"volume_24h_usd":{"type":"string","examples":["1617701.65"]},"mints_24h_usd":{"type":"string","examples":["675954.09"]},"burns_24h_usd":{"type":"string","examples":["674777.96"]},"transfers_24h_usd":{"type":"string","examples":["266969.60"]},"tx_count_24h":{"type":"integer","examples":[731]},"last_observed_at":{"type":["string","null"],"format":"date-time"}}},"SecondaryMarket":{"description":"Secondary market (DEX/AMM) price data. Currently null for all value types. When available, will include price observations from decentralized exchanges.","type":"object","required":["price","source","method","liquidity_usd","volume_24h_usd","observed_at"],"properties":{"price":{"type":"string","description":"Observed secondary market price.","examples":["1.0002"]},"source":{"type":"string","description":"DEX or aggregator identifier.","examples":["uniswap_v3"]},"method":{"type":"string","description":"Price derivation method.","enum":["twap","spot","vwap"],"examples":["twap"]},"liquidity_usd":{"type":"string","description":"Total liquidity in USD across observed pools.","examples":["250000.00"]},"volume_24h_usd":{"type":"string","description":"24h trading volume on the secondary market.","examples":["85000.00"]},"observed_at":{"type":"string","format":"date-time","description":"Timestamp of last observation."},"observations":{"type":"array","description":"Individual pool/pair observations.","items":{"type":"object","required":["pool","price","liquidity_usd"],"properties":{"pool":{"type":"string","description":"Pool or pair identifier.","examples":["SBC/USDC 0.05%"]},"price":{"type":"string","examples":["1.0001"]},"liquidity_usd":{"type":"string","examples":["125000.00"]}}}}}},"BestPrice":{"description":"Synthesized best available price across all sources. Currently derived from primary market; will incorporate secondary market when available.","type":"object","required":["price"],"properties":{"price":{"type":"string","examples":["1.00"]}}},"Price":{"description":"Multi-source price for a value type. Includes the issuer reference price, primary market data from on-chain transactions, a null secondary_market slot (future DEX data), and a synthesized best_price.","type":"object","required":["value_type","currency","reference_price","primary_market","secondary_market","best_price","updated_at"],"properties":{"value_type":{"type":"string","examples":["SBC"]},"currency":{"type":"string","examples":["USD"]},"reference_price":{"$ref":"#/components/schemas/ReferencePrice"},"primary_market":{"$ref":"#/components/schemas/PrimaryMarket"},"secondary_market":{"type":"null","description":"Reserved for future secondary market (DEX) price data."},"best_price":{"$ref":"#/components/schemas/BestPrice"},"updated_at":{"type":"string","format":"date-time"}}},"PriceDetail":{"description":"Multi-source price with per-chain volume breakdown.","allOf":[{"$ref":"#/components/schemas/Price"},{"type":"object","required":["by_transfer_type"],"properties":{"by_transfer_type":{"type":"object","description":"Per-chain 24h volume and transaction count, keyed by chain slug.","additionalProperties":{"type":"object","required":["volume_24h_usd","tx_count_24h"],"properties":{"volume_24h_usd":{"type":"string","examples":["342954.21"]},"tx_count_24h":{"type":"integer","examples":[633]}}},"examples":[{"base":{"volume_24h_usd":"342954.21","tx_count_24h":633},"solana":{"volume_24h_usd":"61.89","tx_count_24h":31}}]}}}]},"PriceChain":{"description":"Multi-source price scoped to a single value type on a single chain. Includes full primary market breakdown for that chain.","type":"object","required":["value_type","transfer_type","currency","reference_price","primary_market","secondary_market","best_price","updated_at"],"properties":{"value_type":{"type":"string","examples":["SBC"]},"transfer_type":{"type":"string","examples":["base"]},"currency":{"type":"string","examples":["USD"]},"reference_price":{"$ref":"#/components/schemas/ReferencePrice"},"primary_market":{"$ref":"#/components/schemas/PrimaryMarket"},"secondary_market":{"type":"null"},"best_price":{"$ref":"#/components/schemas/BestPrice"},"updated_at":{"type":"string","format":"date-time"}}},"PlannedEndpoint":{"description":"Response for endpoints that are planned but not yet implemented.","type":"object","required":["status","endpoint","description"],"properties":{"status":{"type":"string","const":"planned"},"endpoint":{"type":"string"},"description":{"type":"string"},"eta":{"type":"string","examples":["Q3 2026"]},"alternative":{"type":"string","description":"Alternative endpoint to use in the meantime"}}},"TokenList":{"description":"Token list in the Uniswap Token List standard format. Includes chain IDs, contract addresses, and metadata for each token.","type":"object","required":["name","timestamp","version","tokens"],"properties":{"name":{"type":"string","examples":["Brale Token List"]},"timestamp":{"type":"string","format":"date-time"},"version":{"type":"object","properties":{"major":{"type":"integer"},"minor":{"type":"integer"},"patch":{"type":"integer"}}},"tokens":{"type":"array","items":{"type":"object","required":["chainId","address","name","symbol","decimals"],"properties":{"chainId":{"type":"integer"},"address":{"type":"string"},"name":{"type":"string"},"symbol":{"type":"string"},"decimals":{"type":"integer"},"logoURI":{"type":["string","null"]}}}}}},"LlmContext":{"description":"Structured context payload optimized for AI/LLM consumption. Contains a specific slice of platform data (value types or transfer types).","type":"object","required":["schema_version","context_type","description","data"],"properties":{"schema_version":{"type":"string","examples":["1.0"]},"context_type":{"type":"string","examples":["value_types"]},"description":{"type":"string"},"data":{"type":"array","items":{"type":"object"}}}},"LlmFullContext":{"description":"Complete platform context for AI consumption. Includes all value types, transfer types, and platform metadata in a single response.","type":"object","required":["schema_version","context_type","platform","value_types","transfer_types"],"properties":{"schema_version":{"type":"string","examples":["1.0"]},"context_type":{"type":"string","examples":["full_platform"]},"platform":{"type":"object"},"value_types":{"type":"array","items":{"type":"object"}},"transfer_types":{"type":"array","items":{"type":"object"}}}},"AnalyticsSummary":{"description":"Aggregate network statistics including transaction counts, active asset counts, and optional volume data.","type":"object","required":["total_transactions","active_value_types","active_transfer_types"],"properties":{"total_transactions":{"type":"integer"},"active_value_types":{"type":"integer"},"active_transfer_types":{"type":"integer"},"total_volume_usd":{"type":["string","null"]},"last_transaction_at":{"type":["string","null"],"format":"date-time"}}},"CapabilitiesResponse":{"description":"Machine-readable listing of all available API endpoints with human-readable descriptions and authentication info.","type":"object","required":["endpoints"],"properties":{"endpoints":{"type":"array","items":{"type":"object","required":["path","description"],"properties":{"path":{"type":"string"},"description":{"type":"string"}}}},"authentication":{"type":"string"}}},"ErrorCatalog":{"description":"Machine-readable catalog of all API error codes, rate limit policy, MCP error codes, and agent recovery strategies.","type":"object","required":["schema_version","error_codes","rate_limit_policy"],"properties":{"schema_version":{"type":"string","examples":["1.0"]},"description":{"type":"string"},"error_format":{"type":"object"},"error_codes":{"type":"array","items":{"type":"object","required":["code","http_status","description","recoverable","recovery_hint"],"properties":{"code":{"type":"string"},"http_status":{"type":"integer"},"description":{"type":"string"},"recoverable":{"type":"boolean"},"recovery_hint":{"type":"string"},"headers":{"type":"array","items":{"type":"string"}},"example":{"$ref":"#/components/schemas/ApiError"}}}},"rate_limit_policy":{"type":"object","required":["requests_per_window","window_seconds","scope"],"properties":{"requests_per_window":{"type":"integer"},"window_seconds":{"type":"integer"},"scope":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"retry_strategy":{"type":"string"}}},"mcp_error_codes":{"type":"array","items":{"type":"object","required":["code","meaning","description"],"properties":{"code":{"type":"integer"},"meaning":{"type":"string"},"description":{"type":"string"}}}},"discovery":{"type":"object","additionalProperties":{"type":"string"}}}},"ApiError":{"description":"Structured error response with a machine-readable code and human-readable message. All error responses follow this format.","type":"object","required":["error","status"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["NOT_FOUND","VALIDATION_ERROR","RATE_LIMITED","INTERNAL_ERROR"]},"message":{"type":"string"}}},"status":{"type":"integer"}}}},"headers":{"RateLimitHeaders":{"X-RateLimit-Limit":{"description":"Maximum requests allowed per window","schema":{"type":"integer","examples":[120]}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix epoch seconds when the window resets","schema":{"type":"integer"}}}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"NOT_FOUND","message":"Value type 'xyz' not found"},"status":404}}}},"RateLimited":{"description":"Rate limit exceeded","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed per window","schema":{"type":"integer","examples":[120]}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix epoch seconds when the window resets","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"RATE_LIMITED","message":"Rate limit exceeded. Try again shortly."},"status":429}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"},"status":500}}}}}}}