{"openapi":"3.1.0","info":{"title":"TDRates API","summary":"Transportation Data Rates: agent-first freight rate estimates.","description":"Agents: start at /llms.txt.","version":"0.1.0"},"paths":{"/v1/estimate":{"get":{"tags":["estimate"],"summary":"Lane rate estimate","operationId":"estimate_v1_estimate_get","parameters":[{"name":"origin","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":200,"examples":["Salinas, CA"],"title":"Origin"}},{"name":"destination","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":200,"examples":["Chicago, IL"],"title":"Destination"}},{"name":"equipment","in":"query","required":false,"schema":{"type":"string","description":"One of: reefer, dry_van, flatbed, step_deck, power_only, other","default":"reefer","title":"Equipment"},"description":"One of: reefer, dry_van, flatbed, step_deck, power_only, other"},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Estimate as of this date (default: today)","title":"As Of"},"description":"Estimate as of this date (default: today)"},{"name":"miles","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":6000,"minimum":1},{"type":"null"}],"description":"Loaded miles, if known","title":"Miles"},"description":"Loaded miles, if known"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Estimate"}}}},"404":{"description":"No lane, or not enough data to estimate honestly"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/contributions":{"post":{"tags":["contributions"],"summary":"Submit loads (opening soon)","description":"Not open yet. Until CONTRIBUTIONS_OPEN is turned on, this route returns 503. When it is open: a batch of loads (lane, equipment, date, rate, miles only). Five accepted loads grant an API key. See docs/CONTRIBUTIONS.md.","operationId":"contribute_v1_contributions_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContributionResult"}}}},"503":{"description":"Not open yet"},"401":{"description":"Unknown API key"},"403":{"description":"Contributor is blocked"},"422":{"description":"Body has a field that is not allowed, or is malformed"},"429":{"description":"Too many batches"}}}},"/health":{"get":{"tags":["ops"],"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}},"head":{"tags":["ops"],"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/llms.txt":{"get":{"tags":["agents"],"summary":"Llms Txt","operationId":"llms_txt_llms_txt_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}},"head":{"tags":["agents"],"summary":"Llms Txt","operationId":"llms_txt_llms_txt_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/agent-instructions.md":{"get":{"tags":["agents"],"summary":"Agent Instructions","operationId":"agent_instructions_agent_instructions_md_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}},"head":{"tags":["agents"],"summary":"Agent Instructions","operationId":"agent_instructions_agent_instructions_md_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"ContributionResult":{"properties":{"accepted":{"type":"integer","title":"Accepted"},"rejected":{"type":"integer","title":"Rejected"},"access":{"type":"string","enum":["pending","active","blocked"],"title":"Access"},"access_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Access Expires At"},"trust_score":{"type":"number","title":"Trust Score"},"api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key","description":"Shown once, when access is first granted. Store the hash only after that."},"results":{"items":{"$ref":"#/components/schemas/LoadVerdict"},"type":"array","title":"Results"},"fetch_list":{"items":{"$ref":"#/components/schemas/FetchAsk"},"type":"array","title":"Fetch List"}},"type":"object","required":["accepted","rejected","access","trust_score","results","fetch_list"],"title":"ContributionResult"},"CurvePoint":{"properties":{"rate_usd":{"type":"number","title":"Rate Usd"},"density":{"type":"number","title":"Density","description":"Relative probability density at this rate (peak = 1.0)"}},"type":"object","required":["rate_usd","density"],"title":"CurvePoint"},"Estimate":{"properties":{"stub":{"type":"boolean","title":"Stub","description":"True only if this response is a placeholder"},"origin":{"type":"string","title":"Origin","description":"Origin as matched, which may differ from the query"},"destination":{"type":"string","title":"Destination"},"equipment":{"type":"string","title":"Equipment"},"as_of":{"type":"string","format":"date","title":"As Of"},"currency":{"type":"string","const":"USD","title":"Currency","default":"USD"},"low_usd":{"type":"number","title":"Low Usd","description":"Low edge of the likely range"},"likely_usd":{"type":"number","title":"Likely Usd","description":"The likely rate: the recency-weighted median"},"high_usd":{"type":"number","title":"High Usd","description":"High edge of the likely range"},"miles":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Miles"},"rate_per_mile_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rate Per Mile Usd"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","description":"0..1 from sample size, recency and spread"},"record_count":{"type":"integer","title":"Record Count","description":"Verified observations behind this estimate"},"data_from":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Data From","description":"Oldest observation used"},"data_through":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Data Through","description":"Newest observation used"},"sources":{"items":{"type":"string"},"type":"array","title":"Sources","description":"Where the observations came from"},"curve":{"items":{"$ref":"#/components/schemas/CurvePoint"},"type":"array","title":"Curve","description":"Bell curve samples for charting, peak = 1"},"method":{"type":"string","title":"Method","description":"lane, lane_seasonal, or region_fallback"},"notes":{"items":{"type":"string"},"type":"array","title":"Notes","default":[]}},"type":"object","required":["stub","origin","destination","equipment","as_of","low_usd","likely_usd","high_usd","miles","rate_per_mile_usd","confidence","record_count","data_from","data_through","sources","curve","method"],"title":"Estimate","description":"A lane's rate curve. All money is USD for the whole truckload, not per mile."},"FetchAsk":{"properties":{"origin":{"type":"string","title":"Origin"},"destination":{"type":"string","title":"Destination"},"equipment":{"type":"string","title":"Equipment"},"week_of":{"type":"string","format":"date","title":"Week Of"}},"type":"object","required":["origin","destination","equipment","week_of"],"title":"FetchAsk","description":"A lane-week we want a rate for. Checks are not marked."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Health":{"properties":{"status":{"type":"string","enum":["ok","degraded"],"title":"Status"},"version":{"type":"string","title":"Version"},"database":{"type":"string","enum":["ok","unreachable"],"title":"Database"}},"type":"object","required":["status","version","database"],"title":"Health"},"LoadVerdict":{"properties":{"index":{"type":"integer","title":"Index"},"verdict":{"type":"string","enum":["accepted","plausibility_failed","check_failed","pending_check"],"title":"Verdict"},"note":{"type":"string","title":"Note","default":""}},"type":"object","required":["index","verdict"],"title":"LoadVerdict"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}