{"openapi":"3.1.0","info":{"title":"Get GoodSort NBN API","version":"v1","description":"Read-only current Australian NBN comparison data from the same validated GoodSort publication/query layer used by MCP and the website. Agent Contract v1 uncertainty, normalized provenance, cost completeness and D082 general-market scope are preserved."},"servers":[{"url":"https://getgoodsort.com"}],"paths":{"/api/v1/nbn/catalog":{"get":{"operationId":"discoverNbnMarket","summary":"Discover the current GoodSort NBN market surface","responses":{"200":{"description":"Tracked providers/tiers with published, confirmed-absent and explicit unknown/source-gated/withheld coverage state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDiscovery"}}}},"429":{"description":"Rate limit exceeded. Retry-After and X-RateLimit-* headers are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"503":{"description":"Current GoodSort publication data is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}}}},"/api/v1/nbn/plans":{"get":{"operationId":"queryCurrentNbnPlans","summary":"Query current published NBN plans","description":"Results are ranked only among currently publishable GoodSort plans. Unknown provider selectors remain explicit in query.unknownProviderSelectors and are never converted into confirmed market absence; coverage reports the incomplete market surface.","parameters":[{"name":"provider","in":"query","required":false,"description":"Provider name. Repeat or comma-separate for multiple providers. Matching is case-insensitive.","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},{"name":"tier","in":"query","required":false,"description":"Tracked NBN download tier. Repeat or comma-separate for multiple tiers.","schema":{"type":"array","items":{"type":"integer","enum":[25,50,100,250,500,750,1000,2000]}},"style":"form","explode":true},{"name":"min_tier","in":"query","required":false,"description":"Minimum tracked NBN tier.","schema":{"type":"integer","minimum":1}},{"name":"max_intro_price","in":"query","required":false,"description":"Maximum introductory monthly price in AUD.","schema":{"type":"number","minimum":0}},{"name":"max_ongoing_price","in":"query","required":false,"description":"Maximum ongoing monthly price in AUD.","schema":{"type":"number","minimum":0}},{"name":"max_first_year_cost","in":"query","required":false,"description":"Maximum GoodSort-calculated first 12 month cost in AUD.","schema":{"type":"number","minimum":0}},{"name":"min_download_mbps","in":"query","required":false,"description":"Minimum recorded typical download Mbps.","schema":{"type":"number","minimum":0}},{"name":"min_upload_mbps","in":"query","required":false,"description":"Minimum recorded typical/nominal upload Mbps.","schema":{"type":"number","minimum":0}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["first_year_cost_asc","ongoing_price_asc","intro_price_asc","download_speed_desc","upload_speed_desc","provider_asc"],"default":"first_year_cost_asc"}},{"name":"limit","in":"query","required":false,"description":"Maximum returned published plans.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Agent Contract v1 current-plan result. Empty plans[] is a valid result; statuses, coverage and query explain uncertainty. first-year cost completeness is explicit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSearchResult"}}}},"400":{"description":"Invalid query. Response uses a stable error.code and details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"Rate limit exceeded. Retry-After and X-RateLimit-* headers are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"503":{"description":"Current GoodSort publication data is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}}}},"/api/v1/nbn/compare":{"get":{"operationId":"compareNbnPlans","summary":"Compare current NBN plans with deterministic GoodSort reasons","description":"Read-only general-market comparison using the same eligibility predicates as GoodSort Alerts. The endpoint does not store subscriber inputs or infer address eligibility.","parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["same_tier","faster","cheapest_first_year","cheapest_ongoing"],"default":"same_tier"}},{"name":"current_tier","in":"query","required":false,"description":"Current tracked NBN tier for same-tier or faster comparisons.","schema":{"type":"integer","enum":[25,50,100,250,500,750,1000,2000]}},{"name":"current_monthly_price","in":"query","required":false,"description":"Current monthly price in AUD for same-tier or faster comparisons.","schema":{"type":"number","minimum":0}},{"name":"threshold","in":"query","required":false,"description":"Default 10. Same-tier accepts any or 10/20/30/40/50; faster accepts 10/20/30/40/50. Dollar-prefixed amounts are also accepted. Invalid thresholds return an unevaluable comparison with INVALID_THRESHOLD.","schema":{"type":"string"}},{"name":"current_plan_id","in":"query","required":false,"description":"Optional public plan ID to exclude from same-tier candidates; ignored by faster and cheapest modes.","schema":{"type":"string"}},{"name":"tier","in":"query","required":false,"description":"Optional tier filter for cheapest comparisons.","schema":{"type":"integer","enum":[25,50,100,250,500,750,1000,2000]}},{"name":"limit","in":"query","required":false,"description":"Maximum deterministic candidates.","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Deterministic candidate calculations and reason codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentComparison"}}}},"400":{"description":"Invalid query. Response uses a stable error.code and details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"Rate limit exceeded. Retry-After and X-RateLimit-* headers are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"503":{"description":"Current GoodSort publication data is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}}}},"/api/v1/openapi.json":{"get":{"operationId":"getOpenApi","summary":"Get this OpenAPI document","responses":{"200":{"description":"OpenAPI 3.1 document."}}}}},"components":{"schemas":{"AgentSearchResult":{"type":"object","properties":{"contractVersion":{"const":"goodsort.agent.v1"},"resultScope":{"const":"currently_publishable_goodsort_plans"},"coverage":{"type":"object","properties":{"unit":{"const":"provider_tier_combination"},"combinationsSearched":{"type":"integer"},"publishedCombinations":{"type":"integer"},"confirmedAbsentCombinations":{"type":"integer"},"unknownOrWithheldCombinations":{"type":"integer"}},"required":["unit","combinationsSearched","publishedCombinations","confirmedAbsentCombinations","unknownOrWithheldCombinations"],"additionalProperties":false},"marketScope":{"type":"object","properties":{"country":{"const":"AU"},"product":{"const":"nbn"},"comparisonScope":{"const":"general_market"},"premisesEligibility":{"const":"not_determined"},"note":{"type":"string"}},"required":["country","product","comparisonScope","premisesEligibility","note"],"additionalProperties":false},"units":{"type":"object","properties":{"currency":{"const":"AUD"},"monthlyPrice":{"const":"AUD/month"},"speed":{"const":"Mbps"},"duration":{"const":"months"}},"required":["currency","monthlyPrice","speed","duration"],"additionalProperties":false},"dataset":{"type":"object","properties":{"dataDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"generatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"snapshotMode":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["dataDate","generatedAt","snapshotMode"],"additionalProperties":false},"plans":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"providerId":{"type":"string"},"planId":{"type":"string"},"offerIdentityId":{"anyOf":[{"type":"string"},{"type":"null"}]},"provider":{"type":"string"},"plan":{"type":"string"},"tier":{"type":"number"},"status":{"type":"string"},"intro":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Introductory monthly service price in AUD; null is unknown, never zero."},"introMonths":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Introductory period in months; zero means no introductory period."},"ongoing":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Ongoing monthly service price in AUD after the introductory period."},"first12":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Canonical first 12 months cost in AUD; inspect costCompleteness before calling this a total."},"first24":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Canonical first 24 months cost in AUD when available."},"setup":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Known one-off setup fee in AUD. Null means unconfirmed, not free."},"nominalUpload":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Nominal upload service tier in Mbps, not a measured speed."},"typicalDown":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Provider-published typical download Mbps; not premises eligibility or a guaranteed speed."},"typicalUp":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Provider-published typical upload Mbps; distinct from nominalUpload."},"contract":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Recorded contract terms; not confirmed means unknown."},"dataAllowance":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Recorded data allowance; unknown does not mean unlimited."},"selectedVariantKey":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Selected same-download offer variant when supplied."},"citationUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public GoodSort plan-history citation; not a private archive object URL."},"sourceUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastConfirmedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"machineState":{"type":"object","properties":{"offerKnowledge":{"enum":["confirmed_offered","confirmed_absent","unknown"]},"publicationEligibility":{"enum":["published","withheld","not_applicable"]},"freshness":{"enum":["current","stale","retained","unknown"]},"collection":{"enum":["observed","retained_observation","confirmed_absence","source_gated","fetch_failed","observed_withheld","not_confirmed","not_collected","provider_withdrawn","unknown"]},"premisesEligibility":{"const":"not_determined"}},"required":["offerKnowledge","publicationEligibility","freshness","collection","premisesEligibility"],"additionalProperties":false},"costCompleteness":{"type":"object","properties":{"firstYearCostStatus":{"enum":["includes_known_setup_fee","monthly_charges_only","not_available"]},"includedComponents":{"type":"array","items":{"enum":["monthly_service_charges","setup_fee"]}},"unknownComponents":{"type":"array","items":{"enum":["setup_fee"]}}},"required":["firstYearCostStatus","includedComponents","unknownComponents"],"additionalProperties":false},"provenance":{"type":"object","properties":{"evidenceCategory":{"enum":["current_provider_evidence","archived_provider_evidence","retained_provider_observation","confirmed_absence_evidence","withheld_observation","source_gated","source_error","not_confirmed","unknown"]},"summary":{"type":"string"},"providerSourceUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"goodsortProviderUrl":{"type":"string"},"checkedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"confirmedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["evidenceCategory","summary","providerSourceUrl","goodsortProviderUrl","checkedAt","confirmedAt"],"additionalProperties":false}},"required":["id","providerId","planId","offerIdentityId","provider","plan","tier","status","machineState","costCompleteness","provenance"],"additionalProperties":true}},"statuses":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"providerId":{"type":"string"},"tier":{"type":"number"},"status":{"type":"string"},"machineState":{"type":"object","properties":{"offerKnowledge":{"enum":["confirmed_offered","confirmed_absent","unknown"]},"publicationEligibility":{"enum":["published","withheld","not_applicable"]},"freshness":{"enum":["current","stale","retained","unknown"]},"collection":{"enum":["observed","retained_observation","confirmed_absence","source_gated","fetch_failed","observed_withheld","not_confirmed","not_collected","provider_withdrawn","unknown"]},"premisesEligibility":{"const":"not_determined"}},"required":["offerKnowledge","publicationEligibility","freshness","collection","premisesEligibility"],"additionalProperties":false},"provenance":{"type":"object","properties":{"evidenceCategory":{"enum":["current_provider_evidence","archived_provider_evidence","retained_provider_observation","confirmed_absence_evidence","withheld_observation","source_gated","source_error","not_confirmed","unknown"]},"summary":{"type":"string"},"providerSourceUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"goodsortProviderUrl":{"type":"string"},"checkedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"confirmedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["evidenceCategory","summary","providerSourceUrl","goodsortProviderUrl","checkedAt","confirmedAt"],"additionalProperties":false}},"required":["provider","providerId","tier","status","machineState","provenance"],"additionalProperties":true}},"dataDate":{"type":"string"},"query":{"type":"object","properties":{"providers":{"type":"array","items":{"type":"string"}},"tiers":{"type":"array","items":{"type":"integer"}},"unknownProviderSelectors":{"type":"array","items":{"type":"string"}},"minTier":{"anyOf":[{"type":"integer"},{"type":"null"}]},"maxIntroPrice":{"anyOf":[{"type":"number"},{"type":"null"}]},"maxOngoingPrice":{"anyOf":[{"type":"number"},{"type":"null"}]},"maxFirstYearCost":{"anyOf":[{"type":"number"},{"type":"null"}]},"minDownloadMbps":{"anyOf":[{"type":"number"},{"type":"null"}]},"minUploadMbps":{"anyOf":[{"type":"number"},{"type":"null"}]},"sort":{"enum":["first_year_cost_asc","ongoing_price_asc","intro_price_asc","download_speed_desc","upload_speed_desc","provider_asc"]},"limit":{"type":"integer"},"totalMatchingPlans":{"type":"integer"},"returnedPlans":{"type":"integer"}},"required":["providers","tiers","unknownProviderSelectors","minTier","maxIntroPrice","maxOngoingPrice","maxFirstYearCost","minDownloadMbps","minUploadMbps","sort","limit","totalMatchingPlans","returnedPlans"],"additionalProperties":false}},"required":["contractVersion","resultScope","coverage","marketScope","units","dataset","plans","statuses","dataDate","query"],"additionalProperties":true},"AgentDiscovery":{"type":"object","properties":{"contractVersion":{"const":"goodsort.agent.v1"},"marketScope":{"type":"object","properties":{"country":{"const":"AU"},"product":{"const":"nbn"},"comparisonScope":{"const":"general_market"},"premisesEligibility":{"const":"not_determined"},"note":{"type":"string"}},"required":["country","product","comparisonScope","premisesEligibility","note"],"additionalProperties":false},"units":{"type":"object","properties":{"currency":{"const":"AUD"},"monthlyPrice":{"const":"AUD/month"},"speed":{"const":"Mbps"},"duration":{"const":"months"}},"required":["currency","monthlyPrice","speed","duration"],"additionalProperties":false},"dataset":{"type":"object","properties":{"dataDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"generatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"snapshotMode":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["dataDate","generatedAt","snapshotMode"],"additionalProperties":false},"dataDate":{"type":"string"},"supportedTiers":{"type":"array","items":{"type":"integer"}},"providers":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"providerId":{"anyOf":[{"type":"string"},{"type":"null"}]},"publishedTiers":{"type":"array","items":{"type":"integer"}},"confirmedAbsentTiers":{"type":"array","items":{"type":"integer"}},"gaps":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"integer"},"status":{"type":"string"},"publicStatus":{"type":"string"},"publicReason":{"type":"string"},"machineState":{"type":"object","properties":{"offerKnowledge":{"enum":["confirmed_offered","confirmed_absent","unknown"]},"publicationEligibility":{"enum":["published","withheld","not_applicable"]},"freshness":{"enum":["current","stale","retained","unknown"]},"collection":{"enum":["observed","retained_observation","confirmed_absence","source_gated","fetch_failed","observed_withheld","not_confirmed","not_collected","provider_withdrawn","unknown"]},"premisesEligibility":{"const":"not_determined"}},"required":["offerKnowledge","publicationEligibility","freshness","collection","premisesEligibility"],"additionalProperties":false},"provenance":{"anyOf":[{"type":"object","properties":{"evidenceCategory":{"enum":["current_provider_evidence","archived_provider_evidence","retained_provider_observation","confirmed_absence_evidence","withheld_observation","source_gated","source_error","not_confirmed","unknown"]},"summary":{"type":"string"},"providerSourceUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"goodsortProviderUrl":{"type":"string"},"checkedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"confirmedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["evidenceCategory","summary","providerSourceUrl","goodsortProviderUrl","checkedAt","confirmedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["tier","status","publicStatus","publicReason","machineState","provenance"],"additionalProperties":false}}},"required":["provider","providerId","publishedTiers","confirmedAbsentTiers","gaps"],"additionalProperties":false}},"totals":{"type":"object","properties":{"unit":{"const":"provider_tier_combination"},"combinations":{"type":"integer"},"published":{"type":"integer"},"publishedCombinations":{"type":"integer"},"publishedPlanCount":{"type":"integer"},"confirmedAbsent":{"type":"integer"},"confirmedAbsentCombinations":{"type":"integer"},"unknown":{"type":"integer"},"unknownOrWithheldCombinations":{"type":"integer"}},"required":["unit","combinations","published","publishedCombinations","publishedPlanCount","confirmedAbsent","confirmedAbsentCombinations","unknown","unknownOrWithheldCombinations"],"additionalProperties":false}},"required":["contractVersion","marketScope","units","dataset","dataDate","supportedTiers","providers","totals"],"additionalProperties":false},"AgentComparison":{"type":"object","properties":{"contractVersion":{"const":"goodsort.agent.v1"},"marketScope":{"type":"object","properties":{"country":{"const":"AU"},"product":{"const":"nbn"},"comparisonScope":{"const":"general_market"},"premisesEligibility":{"const":"not_determined"},"note":{"type":"string"}},"required":["country","product","comparisonScope","premisesEligibility","note"],"additionalProperties":false},"units":{"type":"object","properties":{"currency":{"const":"AUD"},"monthlyPrice":{"const":"AUD/month"},"speed":{"const":"Mbps"},"duration":{"const":"months"}},"required":["currency","monthlyPrice","speed","duration"],"additionalProperties":false},"comparison":{"type":"object","properties":{"type":{"enum":["better_same_tier","faster_plan","cheapest_first_year","cheapest_ongoing"],"description":"Existing result names differ from same_tier/faster request names."},"evaluable":{"type":"boolean","description":"False means required baseline or threshold context is invalid, not that no offer exists."},"eligible":{"type":"boolean","description":"At least one eligible candidate; not a premises-availability determination."},"reasonCode":{"enum":["ELIGIBLE","DISABLED","BASELINE_PRICE_UNKNOWN","CURRENT_TIER_UNKNOWN","INVALID_THRESHOLD","NO_QUALIFYING_SAME_TIER_OPTION","NO_QUALIFYING_FASTER_OPTION","NO_QUALIFYING_CURRENT_OPTION"]},"baselineMonthly":{"type":"number","description":"Caller-supplied comparison baseline in AUD/month; not subscriber storage."},"threshold":{"anyOf":[{"type":"number"},{"const":"any"}]},"candidates":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"provider":{"type":"string"},"tier":{"type":"number","description":"Nominal download tier in Mbps."},"offerIdentityId":{"anyOf":[{"type":"string"},{"type":"null"}]},"planIdentityId":{"anyOf":[{"type":"string"},{"type":"null"}]},"selectedVariantKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"intro":{"type":"number","description":"Introductory AUD/month."},"introMonths":{"type":"number","description":"Introductory duration in months."},"ongoing":{"type":"number","description":"Ongoing AUD/month."},"firstYearCost":{"type":"number","description":"Canonical first12 cost in AUD; no new price arithmetic or fee inference."},"firstYearMonthly":{"type":"number","description":"Canonical first12 divided by 12, rounded to cents; not an advertised monthly price."},"savingMonthly":{"type":"number","description":"Baseline minus firstYearMonthly in AUD/month."},"ongoingSavingMonthly":{"type":"number","description":"Baseline minus ongoing in AUD/month; may be negative."},"premiumMonthly":{"type":"number","description":"FirstYearMonthly minus baseline in AUD/month; negative means cheaper."},"ongoingPremiumMonthly":{"type":"number","description":"Ongoing minus baseline in AUD/month."},"reasonCode":{"enum":["SAME_TIER_SAVING_QUALIFIES","FASTER_SAME_OR_CHEAPER","FASTER_WITHIN_PREMIUM"]}},"required":["id","provider","tier","intro","introMonths","ongoing","firstYearCost","firstYearMonthly"],"additionalProperties":false}},"diagnostics":{"type":"array","items":{"type":"object","properties":{"provider":{"anyOf":[{"type":"string"},{"type":"null"}]},"tier":{"anyOf":[{"type":"number"},{"type":"null"}]},"reasonCode":{"enum":["PLAN_STALE","PLAN_WITHHELD","PLAN_ABSENT","PLAN_SOURCE_GATED","PLAN_UNKNOWN","PLAN_COST_UNKNOWN"]}},"required":["provider","tier","reasonCode"],"additionalProperties":false}},"fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Deterministic comparison fingerprint, not a subscriber or tracking identifier."}},"required":["type","evaluable","eligible","reasonCode","candidates"],"additionalProperties":false}},"required":["contractVersion","marketScope","units","comparison"],"additionalProperties":false},"AgentError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"enum":["INVALID_QUERY","METHOD_NOT_ALLOWED","NOT_FOUND","RATE_LIMITED","DATA_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}