{"openapi":"3.1.0","info":{"title":"GrainBud AI Read-Only Portfolio API","version":"1.0.0","summary":"Read-only personal investment portfolio snapshot API.","description":"GrainBud exposes read-only AI endpoints for confirmed portfolio facts, known-instrument search, latest stored reference quotes, exposures, data quality, source lineage, and neutral diagnostics."},"servers":[{"url":"https://grainbud.poorlow.com"}],"security":[],"paths":{"/api/ai/portfolio/snapshot":{"get":{"operationId":"getPortfolioSnapshot","summary":"Get current portfolio snapshot","description":"Return confirmed portfolio facts and reference market data for AI analysis. External quotes and FX conversions are estimates and do not override confirmed snapshot values.","security":[],"responses":{"200":{"description":"Portfolio snapshot payload.","content":{"application/json":{"schema":{"type":"object","required":["generated_at","access_control","snapshot"],"properties":{"generated_at":{"type":"string","format":"date-time"},"access_control":{"type":"object","properties":{"mode":{"type":"string"},"required_scope":{"type":"string","const":"portfolio:snapshot:read"},"granted_scopes":{"type":"array","items":{"type":"string"}},"rate_limit":{"type":"object"}}},"snapshot":{"$ref":"#/components/schemas/PortfolioSnapshot"}}}}}},"401":{"description":"Missing, invalid, or insufficient token."},"429":{"description":"Rate limited."},"503":{"description":"Token store unavailable."}}}},"/api/ai/positions":{"get":{"operationId":"queryPositions","summary":"Query current confirmed positions","description":"Filter current GrainBud positions by symbol, account, asset class, market, theme, or exposure tag. Weights use confirmed total assets unless explicitly named account_weight_pct.","security":[],"parameters":[{"name":"symbol","in":"query","schema":{"type":"string"},"description":"Display symbol, canonical public code, provider identifier, or benchmark identifier."},{"name":"account","in":"query","schema":{"type":"string"}},{"name":"asset_class","in":"query","schema":{"type":"string"}},{"name":"market","in":"query","schema":{"type":"string"}},{"name":"theme","in":"query","schema":{"type":"string"}},{"name":"exposure_tag","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"Filtered positions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PositionsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/DataUnavailable"}}}},"/api/ai/instruments/search":{"get":{"operationId":"searchKnownInstruments","summary":"Search known GrainBud instruments","description":"Search instruments already present in GrainBud holdings by code, mapped public code, provider identifier, or name.","security":[],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Known instrument search result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstrumentSearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/DataUnavailable"}}}},"/api/ai/quotes/latest":{"get":{"operationId":"getLatestReferenceQuote","summary":"Get latest stored reference quote for a known instrument","description":"Return the latest stored reference quote for a GrainBud known instrument. This is not a broker trading feed or arbitrary full-market quote API.","security":[],"parameters":[{"name":"symbol","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Display symbol, canonical public code, provider identifier, or benchmark identifier."}],"responses":{"200":{"description":"Latest reference quote with holding overlay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LatestQuoteResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/DataUnavailable"}}}},"/api/ai/funds/intraday-estimates":{"get":{"operationId":"getFundIntradayReferenceEstimate","summary":"Get intraday reference estimate for a synced fund profile","description":"Return neutral intraday estimate fields for a GrainBud synced 6-digit open-end fund profile. The estimate is not official confirmed NAV and cannot be used as a trading instruction.","security":[],"parameters":[{"name":"code","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{6}$"},"description":"Six-digit public fund code synced in GrainBud fund profiles."}],"responses":{"200":{"description":"Fund intraday reference estimate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FundIntradayEstimateResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/ai/exposures":{"get":{"operationId":"getExposures","summary":"Get theme and classification exposures","security":[],"parameters":[{"name":"tag","in":"query","schema":{"type":"string"},"description":"Optional exact tag filter, such as gold or technology."}],"responses":{"200":{"description":"Theme and classification exposure rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExposuresResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/DataUnavailable"}}}},"/api/ai/data-quality":{"get":{"operationId":"getDataQuality","summary":"Get data quality and refresh recommendations","security":[],"responses":{"200":{"description":"Freshness, valuation, refresh recommendations and data-quality or exposure diagnostics.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataQualityResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/ai/manifest":{"get":{"operationId":"getAiApiManifest","summary":"Get API discovery manifest","responses":{"200":{"description":"Machine-readable discovery document."}}}},"/api/ai/openapi":{"get":{"operationId":"getAiApiOpenApi","summary":"Get OpenAPI contract","responses":{"200":{"description":"OpenAPI 3.1 contract."}}}},"/api/ai/instructions":{"get":{"operationId":"getAiApiInstructions","summary":"Get Markdown instructions for AI tools","responses":{"200":{"description":"Markdown-style plain text instructions. Served as text/plain for broad AI web reader compatibility.","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/skill.md":{"get":{"operationId":"getSkillMarkdown","summary":"Get hosted Markdown skill instructions","responses":{"200":{"description":"Canonical Markdown-style skill instructions. Served as text/plain for broad AI web reader compatibility.","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/agent.md":{"get":{"operationId":"getAgentMarkdown","summary":"Get single-link AI portfolio brief","description":"Return an AI-readable Markdown brief containing the current portfolio summary, holdings table, caveats, and links to machine-readable endpoints.","security":[],"responses":{"200":{"description":"Markdown-style agent brief. Served as text/plain for broad AI web reader compatibility.","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/llms.txt":{"get":{"operationId":"getLlmsTxt","summary":"Get AI crawler index","responses":{"200":{"description":"Plain text Markdown-style AI index.","content":{"text/plain":{"schema":{"type":"string"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Recommended. Send Authorization: Bearer <token>."},"xApiToken":{"type":"apiKey","in":"header","name":"x-api-token","description":"Alternative token header."}},"responses":{"BadRequest":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing, invalid, or insufficient token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Requested known instrument was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"DataUnavailable":{"description":"Portfolio data is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"ErrorResponse":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}},"AccessControl":{"type":"object","required":["mode","required_scope","granted_scopes","rate_limit"],"properties":{"mode":{"type":"string"},"required_scope":{"type":"string","const":"portfolio:snapshot:read"},"granted_scopes":{"type":"array","items":{"type":"string"}},"rate_limit":{"type":"object"}}},"PositionIdentifier":{"type":"object","required":["provider","symbol","kind","role"],"properties":{"provider":{"type":"string"},"symbol":{"type":"string"},"kind":{"type":"string"},"name":{"type":["string","null"]},"priority":{"type":"number"},"note":{"type":["string","null"]},"role":{"type":"string","enum":["quote_symbol","underlying_public_code","benchmark"]}}},"PositionClassification":{"type":"object","required":["instrument_type","underlying_asset","theme_tags","exposure_tags","vehicle_type","trading_venue","classification_source"],"properties":{"instrument_type":{"type":"string"},"underlying_asset":{"type":"string"},"theme_tags":{"type":"array","items":{"type":"string"}},"exposure_tags":{"type":"array","items":{"type":"string"}},"vehicle_type":{"type":"string","enum":["single_stock","exchange_traded_etf","linked_fund","open_ended_fund","bank_accumulated_gold","cash","unknown"],"description":"Product wrapper used for AI-facing interpretation. Exchange-traded ETF means listed ETF; linked_fund means platform or OTC feeder/linked fund."},"trading_venue":{"type":"string","enum":["exchange","fund_platform","bank","cash","unknown"],"description":"Where this position is normally held or transacted from the captured account perspective."},"classification_source":{"type":"string","const":"curated_rule"}}},"PriceSource":{"type":"object","required":["kind","display_basis","price","currency","is_stale"],"properties":{"kind":{"type":"string"},"label":{"type":"string"},"display_basis":{"type":"string"},"price":{"type":["number","null"]},"currency":{"type":["string","null"]},"updated_at":{"type":["string","null"],"format":"date-time"},"quote_age_days":{"type":["number","null"]},"is_stale":{"type":"boolean"},"provider":{"type":["string","null"]},"provider_symbol":{"type":["string","null"]},"provider_name":{"type":["string","null"]},"source_type":{"type":["string","null"]},"quality":{"type":["string","null"]},"note":{"type":["string","null"]}}},"Position":{"type":"object","required":["id","symbol","name","market","asset_class","classification","quantity","quantity_status","currency","confirmed_market_value","reference_value","reference_value_currency","reference_value_source","reference_weight_pct","quote_reference_only","trading_feed","can_generate_trade_instruction","external_estimate_usable","account_weight_pct","portfolio_total_assets_weight_pct","portfolio_market_value_weight_pct","price_source"],"properties":{"id":{"type":"string"},"account":{"type":"string"},"symbol":{"type":"string"},"display_symbol":{"type":"string"},"canonical_symbol":{"type":["string","null"]},"symbol_kind":{"type":"string"},"public_code_status":{"type":"string"},"benchmark_identifier":{"type":["string","null"]},"identifiers":{"type":"array","items":{"$ref":"#/components/schemas/PositionIdentifier"}},"name":{"type":"string"},"market":{"type":"string"},"asset_class":{"type":"string"},"classification":{"$ref":"#/components/schemas/PositionClassification"},"quantity":{"type":"number"},"quantity_status":{"type":"string"},"currency":{"type":"string"},"cost_basis":{"type":"number"},"confirmed_price":{"type":["number","null"]},"quote_price":{"type":["number","null"]},"quote_currency":{"type":["string","null"]},"quote_reference_only":{"type":"boolean","const":true},"trading_feed":{"type":"boolean","const":false},"can_generate_trade_instruction":{"type":"boolean","const":false},"confirmed_market_value":{"type":"number"},"reference_value":{"type":"number"},"reference_value_currency":{"type":"string","const":"CNY"},"reference_value_source":{"type":"string","enum":["external_estimate","confirmed_snapshot_fallback"]},"reference_value_delta":{"type":["number","null"]},"reference_value_delta_pct":{"type":["number","null"]},"reference_weight_pct":{"type":"number"},"reference_valuation_note":{"type":"string"},"external_quote_value":{"type":["number","null"]},"external_estimated_value":{"type":["number","null"]},"external_estimate_usable":{"type":"boolean"},"unrealized_pnl":{"type":"number"},"day_pnl":{"type":["number","null"]},"pnl_pct":{"type":["number","null"]},"account_weight_pct":{"type":"number"},"portfolio_total_assets_weight_pct":{"type":"number"},"portfolio_market_value_weight_pct":{"type":"number"},"updated_at":{"type":["string","null"],"format":"date-time"},"price_source":{"$ref":"#/components/schemas/PriceSource"},"source_lineage":{"type":"object"}}},"PortfolioSnapshot":{"type":"object","required":["base_currency","data_status","summary","totals","accounts","positions","top_positions","exposure","concentration","diagnostics","data_freshness","valuation_explanation","refresh_recommendations","pre_advice_disclosures","planning_context_required","reference_asset_allocation"],"properties":{"base_currency":{"type":"string"},"data_status":{"type":"string"},"data_status_text":{"type":"string"},"summary":{"type":"object"},"totals":{"type":"object"},"accounts":{"type":"array","items":{"type":"object"}},"positions":{"type":"array","items":{"$ref":"#/components/schemas/Position"}},"top_positions":{"type":"array","items":{"$ref":"#/components/schemas/Position"}},"exposure":{"type":"object"},"concentration":{"type":"object"},"diagnostics":{"type":"object"},"data_freshness":{"type":"object"},"valuation_explanation":{"type":"object"},"refresh_recommendations":{"type":"object"},"pre_advice_disclosures":{"type":"object"},"planning_context_required":{"type":"object"},"reference_asset_allocation":{"type":"array","items":{"type":"object"}},"interpretation_guide":{"type":"object"}}},"PositionsResponse":{"type":"object","required":["generated_at","data_status","count","positions"],"properties":{"generated_at":{"type":"string","format":"date-time"},"data_status":{"type":"string"},"filters":{"type":"object"},"count":{"type":"integer"},"total_matched":{"type":"integer"},"positions":{"type":"array","items":{"$ref":"#/components/schemas/Position"}}}},"InstrumentSearchResponse":{"type":"object","required":["generated_at","query","count","instruments"],"properties":{"generated_at":{"type":"string","format":"date-time"},"data_status":{"type":"string"},"query":{"type":"string"},"count":{"type":"integer"},"instruments":{"type":"array","items":{"type":"object"}}}},"LatestQuoteResponse":{"type":"object","required":["generated_at","quote_type","quote"],"properties":{"generated_at":{"type":"string","format":"date-time"},"data_status":{"type":"string"},"quote_type":{"type":"string","const":"latest_reference_quote"},"quote":{"type":"object","required":["requested_symbol","matched_symbol","name","quote","confirmed_snapshot_overlay","caveats"],"properties":{"requested_symbol":{"type":"string"},"matched_symbol":{"type":"string"},"name":{"type":"string"},"market":{"type":"string"},"asset_class":{"type":"string"},"classification":{"$ref":"#/components/schemas/PositionClassification"},"quote":{"type":"object","required":["available","price","currency","reference_only","trading_feed","can_generate_trade_instruction"],"properties":{"available":{"type":"boolean"},"price":{"type":["number","null"]},"currency":{"type":["string","null"]},"reference_only":{"type":"boolean","const":true},"trading_feed":{"type":"boolean","const":false},"can_generate_trade_instruction":{"type":"boolean","const":false},"decision_support_usage":{"type":"string"},"as_of":{"type":["string","null"]},"age_days":{"type":["number","null"]},"is_stale":{"type":"boolean"},"provider":{"type":["string","null"]},"provider_name":{"type":["string","null"]},"quality":{"type":["string","null"]},"source_type":{"type":["string","null"]},"display_basis":{"type":["string","null"]}}},"confirmed_snapshot_overlay":{"type":"object"},"caveats":{"type":"array","items":{"type":"string"}}}}}},"FundIntradayEstimateResponse":{"type":"object","required":["generated_at","estimate_type","estimate"],"properties":{"generated_at":{"type":"string","format":"date-time"},"estimate_type":{"type":"string","const":"fund_intraday_reference_estimate"},"estimate":{"type":"object","required":["schema_version","fund_code","status","method","source","estimated_nav","estimated_change_pct","reference_only","trading_feed","can_generate_trade_instruction","caveats"],"properties":{"schema_version":{"type":"string","const":"grainbud.fund-intraday-estimate.v1"},"generated_at":{"type":"string","format":"date-time"},"fund_code":{"type":"string"},"fund_name":{"type":["string","null"]},"status":{"type":"string","enum":["available","unavailable"]},"method":{"type":"string","const":"direct_provider_estimate"},"source":{"type":"object"},"latest_official_nav":{"type":["number","null"]},"latest_official_nav_date":{"type":["string","null"]},"estimated_nav":{"type":["number","null"]},"estimated_change_pct":{"type":["number","null"]},"estimated_at":{"type":["string","null"],"format":"date-time"},"source_lag_minutes":{"type":["number","null"]},"confidence":{"type":"string","enum":["medium","low","unavailable"]},"confidence_reasons":{"type":"array","items":{"type":"string"}},"reference_only":{"type":"boolean","const":true},"trading_feed":{"type":"boolean","const":false},"can_generate_trade_instruction":{"type":"boolean","const":false},"profile_context":{"type":"object"},"holdings_replay":{"type":"object"},"data_quality":{"type":"object"},"caveats":{"type":"array","items":{"type":"string"}}}}}},"ExposuresResponse":{"type":"object","required":["generated_at","base_currency","count","exposures"],"properties":{"generated_at":{"type":"string","format":"date-time"},"data_status":{"type":"string"},"base_currency":{"type":"string"},"tag":{"type":["string","null"]},"count":{"type":"integer"},"exposures":{"type":"array","items":{"type":"object"}}}},"DataQualityResponse":{"type":"object","required":["generated_at","data_status","data_freshness","valuation_summary","refresh_recommendations","pre_advice_disclosures","planning_context_required","diagnostics"],"properties":{"generated_at":{"type":"string","format":"date-time"},"data_status":{"type":"string"},"data_freshness":{"type":"object"},"valuation_summary":{"type":"object"},"refresh_recommendations":{"type":"object"},"pre_advice_disclosures":{"type":"object"},"planning_context_required":{"type":"object"},"diagnostics":{"type":"object"}}}}}}