{"openapi":"3.0.3","info":{"title":"AgOS Market API","version":"1.0.0","description":"Independent commodity reference prices with revision history and publication-time provenance. Values are CAD per metric tonne. This controlled-import pilot has no configured live feeds. Use Authorize with an operator-issued read key to try requests; credentials remain in this browser tab only. Start with List series to obtain a valid series ID."},"servers":[{"url":"/","description":"Current Market service (production: https://market.ag-os.pro)"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Series","description":"Find the exact commodity, grade, region and methodology."},{"name":"Prices","description":"Historical observations and freshness-aware spot lookups."},{"name":"Releases","description":"Retrieve the release pinned to a saved valuation."},{"name":"Health","description":"Service liveness and database readiness."}],"paths":{"/v1/coverage":{"get":{"operationId":"getCoverage","tags":["Series"],"summary":"List supported commodities, regions and date ranges","description":"Returns all registered commodities, regions and matching series without pagination. Optional filters apply to every array and the overall date range. Ranges include only non-null published prices in the latest revision of each date; retracted and missing releases are excluded. A null range means no available price data. Ranges are inclusive outer bounds and may contain gaps; they do not imply current spot usability. Unknown filter IDs return empty arrays.","parameters":[{"name":"commodity_id","in":"query","required":false,"description":"Restrict coverage to this commodity.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"region_id","in":"query","required":false,"description":"Restrict coverage to this region.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"If-None-Match","in":"header","schema":{"type":"string"},"description":"ETag from a prior response; returns 304 when unchanged."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Coverage"}}},"headers":{"ETag":{"schema":{"type":"string"},"description":"Revision-sensitive entity tag."},"Cache-Control":{"schema":{"type":"string"},"example":"private, max-age=0, must-revalidate"}}},"304":{"description":"Unchanged; empty response body"},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Bearer read key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown series or release","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; never interpret as a missing price","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/series":{"get":{"operationId":"listSeries","tags":["Series"],"summary":"List series","description":"Filter registered series by commodity and region. An empty list means no matching series are registered.","parameters":[{"name":"commodity_id","in":"query","required":false,"description":"Canonical commodity ID.","schema":{"type":"string","maxLength":128}},{"name":"region_id","in":"query","required":false,"description":"Canonical region ID.","schema":{"type":"string","maxLength":128}},{"name":"limit","in":"query","required":false,"description":"Maximum number of results (calendar days for history).","schema":{"type":"integer","minimum":1,"maximum":366,"default":100}},{"name":"offset","in":"query","required":false,"description":"Number of results or calendar days to skip.","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}},{"name":"If-None-Match","in":"header","schema":{"type":"string"},"description":"ETag from a prior response; returns 304 when unchanged."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Series"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}},"headers":{"ETag":{"schema":{"type":"string"},"description":"Revision-sensitive entity tag."},"Cache-Control":{"schema":{"type":"string"},"example":"private, max-age=0, must-revalidate"}}},"304":{"description":"Unchanged; empty response body"},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Bearer read key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown series or release","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; never interpret as a missing price","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/series/{id}/prices":{"get":{"operationId":"getPrices","tags":["Prices"],"summary":"Read price history","description":"Exact calendar dates, never implicit carry-forward. Missing and closed dates return null values. Ordered ranges are limited to 3,660 days. Pin known_at for reproducible pagination.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Exact versioned series ID returned by GET /v1/series."},{"name":"from","in":"query","required":true,"description":"First calendar date, inclusive.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":true,"description":"Last calendar date, inclusive.","schema":{"type":"string","format":"date"}},{"name":"view","in":"query","required":false,"description":"Corrected history or releases published by a specified instant.","schema":{"type":"string","enum":["latest_revision","as_known_at"],"default":"latest_revision"}},{"name":"known_at","in":"query","required":false,"description":"Only valid with as_known_at. Required for history; defaults to at for spot. Future ceilings are capped at the current time.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of results (calendar days for history).","schema":{"type":"integer","minimum":1,"maximum":366,"default":100}},{"name":"offset","in":"query","required":false,"description":"Number of results or calendar days to skip.","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}},{"name":"If-None-Match","in":"header","schema":{"type":"string"},"description":"ETag from a prior response; returns 304 when unchanged."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data","view","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"view":{"type":"string"},"known_at":{"type":"string","format":"date-time"},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}},"headers":{"ETag":{"schema":{"type":"string"},"description":"Revision-sensitive entity tag."},"Cache-Control":{"schema":{"type":"string"},"example":"private, max-age=0, must-revalidate"}}},"304":{"description":"Unchanged; empty response body"},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Bearer read key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown series or release","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; never interpret as a missing price","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/series/{id}/spot":{"get":{"operationId":"getSpot","tags":["Prices"],"summary":"Get a spot reference","description":"Returns the latest eligible market date by at, respecting the series cutoff. Daily freshness counts scheduled market sessions. Stale results return value=null and last_known separately. latest_revision may include later corrections; as_known_at prevents publication-time look-ahead.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Exact versioned series ID returned by GET /v1/series."},{"name":"at","in":"query","required":false,"description":"Effective-time ceiling. Defaults to now; cannot be in the future.","schema":{"type":"string","format":"date-time"}},{"name":"view","in":"query","required":false,"description":"Corrected history or releases published by a specified instant.","schema":{"type":"string","enum":["latest_revision","as_known_at"],"default":"latest_revision"}},{"name":"known_at","in":"query","required":false,"description":"Only valid with as_known_at. Required for history; defaults to at for spot. Future ceilings are capped at the current time.","schema":{"type":"string","format":"date-time"}},{"name":"If-None-Match","in":"header","schema":{"type":"string"},"description":"ETag from a prior response; returns 304 when unchanged."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Price"},{"type":"object","required":["at","view"],"properties":{"at":{"type":"string","format":"date-time"},"view":{"type":"string"},"known_at":{"type":"string","format":"date-time"},"last_known":{"$ref":"#/components/schemas/Release"}}}]}}},"headers":{"ETag":{"schema":{"type":"string"},"description":"Revision-sensitive entity tag."},"Cache-Control":{"schema":{"type":"string"},"example":"private, max-age=0, must-revalidate"}}},"304":{"description":"Unchanged; empty response body"},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Bearer read key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown series or release","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; never interpret as a missing price","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/releases/{id}":{"get":{"operationId":"getRelease","tags":["Releases"],"summary":"Read a pinned release","description":"Returns the original release and its current published, superseded or retracted state. Freshness is not re-evaluated by this endpoint; use spot for a currently usable price.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"If-None-Match","in":"header","schema":{"type":"string"},"description":"ETag from a prior response; returns 304 when unchanged."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}},"headers":{"ETag":{"schema":{"type":"string"},"description":"Revision-sensitive entity tag."},"Cache-Control":{"schema":{"type":"string"},"example":"private, max-age=0, must-revalidate"}}},"304":{"description":"Unchanged; empty response body"},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Bearer read key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown series or release","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; never interpret as a missing price","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/health/live":{"get":{"operationId":"liveness","tags":["Health"],"summary":"Check liveness","security":[],"responses":{"200":{"description":"Process is responding","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["ok"]}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/health/ready":{"get":{"operationId":"readiness","tags":["Health"],"summary":"Check database readiness","responses":{"200":{"description":"Registry can be queried","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["ready"]}}}}}},"401":{"description":"Bearer read key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; never interpret as a missing price","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Operator-issued Market read key. Enter the key only, without the Bearer prefix. Never use a database credential."}},"schemas":{"DateRange":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}},"nullable":true,"description":"Inclusive outer bounds of available historical prices, or null when none exist. Gaps may exist within the range."},"Coverage":{"type":"object","required":["view","date_range","commodities","regions","series"],"properties":{"view":{"type":"string","enum":["latest_revision"]},"date_range":{"$ref":"#/components/schemas/DateRange"},"commodities":{"type":"array","items":{"type":"object","required":["commodity_id","region_ids","date_range"],"properties":{"commodity_id":{"type":"string"},"region_ids":{"type":"array","items":{"type":"string"}},"date_range":{"$ref":"#/components/schemas/DateRange"}}}},"regions":{"type":"array","items":{"type":"object","required":["region_id","commodity_ids","date_range"],"properties":{"region_id":{"type":"string"},"commodity_ids":{"type":"array","items":{"type":"string"}},"date_range":{"$ref":"#/components/schemas/DateRange"}}}},"series":{"type":"array","items":{"type":"object","required":["series_id","commodity_id","region_id","frequency","date_range"],"properties":{"series_id":{"type":"string"},"commodity_id":{"type":"string"},"region_id":{"type":"string"},"frequency":{"type":"string","enum":["daily","weekly"]},"date_range":{"$ref":"#/components/schemas/DateRange"}}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"issues":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"integer"}]}},"message":{"type":"string"}}}}}},"Pagination":{"type":"object","required":["limit","offset","next_offset"],"properties":{"limit":{"type":"integer","minimum":0},"offset":{"type":"integer","minimum":0},"next_offset":{"type":"integer","minimum":0,"nullable":true}}},"Series":{"type":"object","required":["id","commodity_id","region_id","version","methodology_version","grade","quality","delivery_basis","frequency","timezone","cutoff","locations","holidays","freshness_sessions","freshness_days","ratified_by"],"properties":{"id":{"type":"string"},"commodity_id":{"type":"string"},"region_id":{"type":"string"},"version":{"type":"string"},"methodology_version":{"type":"string"},"grade":{"type":"string"},"quality":{"type":"string"},"delivery_basis":{"type":"string","enum":["delivered","farm_pickup"]},"frequency":{"type":"string","enum":["daily","weekly"]},"timezone":{"type":"string","enum":["America/Regina"]},"cutoff":{"type":"string","example":"17:00"},"locations":{"type":"array","items":{"type":"string"}},"holidays":{"type":"array","items":{"type":"string","format":"date"}},"freshness_sessions":{"type":"integer","minimum":0},"freshness_days":{"type":"integer","minimum":0},"lb_per_bushel":{"type":"string"},"ratified_by":{"type":"string"}}},"Release":{"type":"object","required":["id","series_id","market_date","revision","value","assessment","state","previous_release_id","published_at","buyer_count","location_count","range","sources","exclusions"],"properties":{"id":{"type":"string","format":"uuid"},"series_id":{"type":"string"},"market_date":{"type":"string","format":"date"},"revision":{"type":"integer","minimum":1},"value":{"type":"string","nullable":true,"pattern":"^\\d+\\.\\d{2}$","example":"300.00","description":"CAD per metric tonne, serialized as a decimal string. Null means no usable price."},"assessment":{"type":"string","enum":["assessed","thin","missing"]},"state":{"type":"string","enum":["published","superseded","retracted"]},"previous_release_id":{"type":"string","format":"uuid","nullable":true},"published_at":{"type":"string","format":"date-time"},"buyer_count":{"type":"integer","minimum":0},"location_count":{"type":"integer","minimum":0},"range":{"type":"object","required":["min","max"],"properties":{"min":{"type":"string","nullable":true,"pattern":"^\\d+\\.\\d{2}$","example":"300.00","description":"CAD per metric tonne, serialized as a decimal string. Null means no usable price."},"max":{"type":"string","nullable":true,"pattern":"^\\d+\\.\\d{2}$","example":"300.00","description":"CAD per metric tonne, serialized as a decimal string. Null means no usable price."}},"nullable":true},"sources":{"type":"array","items":{"type":"object","required":["id","attribution"],"properties":{"id":{"type":"string"},"attribution":{"type":"string"}}}},"exclusions":{"type":"object","additionalProperties":{"type":"integer","minimum":0}}}},"Price":{"type":"object","required":["series_id","series_version","methodology_version","commodity_id","region_id","grade","quality","delivery_basis","currency","unit","frequency","release_id","market_date","value","assessment","freshness","age","release"],"properties":{"series_id":{"type":"string"},"series_version":{"type":"string"},"methodology_version":{"type":"string"},"commodity_id":{"type":"string"},"region_id":{"type":"string"},"grade":{"type":"string"},"quality":{"type":"string"},"delivery_basis":{"type":"string"},"currency":{"type":"string","enum":["CAD"]},"unit":{"type":"string","enum":["t"]},"frequency":{"type":"string"},"release_id":{"type":"string","nullable":true,"format":"uuid"},"market_date":{"type":"string","format":"date"},"value":{"type":"string","nullable":true,"pattern":"^\\d+\\.\\d{2}$","example":"300.00","description":"CAD per metric tonne, serialized as a decimal string. Null means no usable price."},"assessment":{"type":"string","enum":["assessed","thin","missing"]},"freshness":{"type":"string","enum":["current","carried","stale"]},"age":{"type":"object","required":["calendar_days","market_sessions"],"properties":{"calendar_days":{"type":"integer","minimum":0},"market_sessions":{"type":"integer","minimum":0}}},"release":{"type":"object","nullable":true,"allOf":[{"$ref":"#/components/schemas/Release"}]}}}}}}