{"openapi":"3.1.0","info":{"title":"Spiral Knights Market Open Data API","version":"1.0.0","description":"Public, read-only access to the Spiral Knights energy market and auction house data collected by spiralknights.market.","license":{"name":"CC BY 4.0","url":"https://creativecommons.org/licenses/by/4.0/"},"contact":{"email":"spiralknightsenergy@gmail.com"},"x-attribution":"Creative Commons Attribution 4.0 International (CC BY 4.0). Suggested attribution: \"Spiral Knights market data from spiralknights.market\".","x-notice":"Spiral Knights and all related names, art and trademarks are the property of Grey Havens, LLC. This API is not official and is not affiliated with, endorsed by, sponsored by or otherwise connected to Grey Havens, LLC."},"servers":[{"url":"https://api.spiralknights.market"}],"tags":[{"name":"Energy"},{"name":"Auction"},{"name":"Meta"}],"paths":{"/v1/energy/latest":{"get":{"operationId":"energyLatest","tags":["Energy"],"summary":"Latest energy prices","description":"The most recent observation of the energy market: the top sell and buy offers, each with its price in crowns per 100 energy and the amount posted at that price.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","description":"","properties":{"observed_at":{"type":"string","format":"date-time","description":"When the sample was taken."},"sell":{"type":["object","null"],"description":"Top sell offer; null if none was posted.","properties":{"price":{"type":"number","description":"Crowns per 100 energy."},"amount":{"type":"integer","description":"Amount posted at that price."}}},"buy":{"type":["object","null"],"description":"Top buy offer; null if none was posted.","properties":{"price":{"type":"number","description":"Crowns per 100 energy."},"amount":{"type":"integer","description":"Amount posted at that price."}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-cache-seconds":15,"x-example":{}}},"/v1/energy/series":{"get":{"operationId":"energySeries","tags":["Energy"],"summary":"Energy price history","description":"Price history in fixed buckets. Each bucket carries, per side, the mean (weighted by posted amount), the lowest and highest price seen, and `n`, the total weight behind the mean. Empty buckets are omitted. A request may span at most 1000 buckets: pick a coarser interval for a longer window.","parameters":[{"name":"interval","in":"query","required":false,"description":"Bucket size.","schema":{"type":"string","enum":["1m","10m","1h","1d"],"default":"1h"}},{"name":"from","in":"query","required":false,"description":"Start of the window (inclusive). ISO 8601 or epoch seconds. Default: 500 buckets before `to`.","schema":{"type":"string","minLength":1,"maxLength":40}},{"name":"to","in":"query","required":false,"description":"End of the window (exclusive). Default: now.","schema":{"type":"string","minLength":1,"maxLength":40}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","description":"","properties":{"interval":{"type":"string","description":"Bucket size, as requested."},"from":{"type":"string","format":"date-time","description":"Start of the window, snapped to a bucket boundary."},"to":{"type":"string","format":"date-time","description":"End of the window (exclusive)."},"points":{"type":"array","description":"One entry per non-empty bucket, oldest first.","items":{"type":"object","description":"","properties":{"t":{"type":"string","format":"date-time","description":"Bucket start."},"sell":{"type":["object","null"],"description":"Sell offers in the bucket; null if none were seen.","properties":{"mean":{"type":"number","description":"Mean price, weighted by posted amount."},"min":{"type":"number","description":"Lowest price seen."},"max":{"type":"number","description":"Highest price seen."},"n":{"type":"integer","description":"Total weight behind the mean."}}},"buy":{"type":["object","null"],"description":"Buy offers in the bucket; null if none were seen.","properties":{"mean":{"type":"number","description":"Mean price, weighted by posted amount."},"min":{"type":"number","description":"Lowest price seen."},"max":{"type":"number","description":"Highest price seen."},"n":{"type":"integer","description":"Total weight behind the mean."}}}}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-cache-seconds":30,"x-example":{"interval":"1h"}}},"/v1/auction/categories":{"get":{"operationId":"auctionCategories","tags":["Auction"],"summary":"Auction categories","description":"The auction house categories with their live listing counts.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","description":"","properties":{"categories":{"type":"array","description":"Categories that have live listings.","items":{"type":"object","description":"","properties":{"category":{"type":"string","description":"Category code."},"listings":{"type":"integer","description":"Live listings in it."}}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-cache-seconds":60,"x-example":{}}},"/v1/auction/listings":{"get":{"operationId":"auctionListings","tags":["Auction"],"summary":"Live listings","description":"Auctions that are live right now. `buy_price` is null when a listing has no buy-now price. `time_left` is the game's own coarse bucket (VERY_SHORT, SHORT, MEDIUM, LONG, VERY_LONG); `estimated_end_at` is a prediction and bids can extend it.","parameters":[{"name":"category","in":"query","required":false,"description":"One category, as returned by `/v1/auction/categories`.","schema":{"type":"string","maxLength":32}},{"name":"slug","in":"query","required":false,"description":"One item, by slug.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"variant","in":"query","required":false,"description":"Exact variant name, e.g. a colour theme.","schema":{"type":"string","maxLength":64}},{"name":"uv","in":"query","required":false,"description":"Unique variant filter: `Type|Strength` pairs joined by `;` (strength optional). A row matches when it has every listed UV at that strength or stronger. Strengths: Low, Medium, High, Very High.","schema":{"type":"string","maxLength":512}},{"name":"sort","in":"query","required":false,"description":"`ending`: soonest to end first. `newest`: most recently listed first.","schema":{"type":"string","enum":["ending","newest"],"default":"ending"}},{"name":"limit","in":"query","required":false,"description":"Rows per page, up to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"`next_cursor` from the previous page.","schema":{"type":"string","maxLength":256}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","description":"","properties":{"total":{"type":"integer","description":"Listings matching the filters."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; null at the end."},"listings":{"type":"array","description":"One page of live listings.","items":{"type":"object","description":"","properties":{"auction_id":{"type":"integer","description":"The game's auction id."},"slug":{"type":"string","description":"Item slug."},"variant":{"type":["string","null"],"description":"Variant name, e.g. a colour theme."},"uvs":{"type":"array","description":"Unique variants on the item.","items":{"type":"object","description":"","properties":{"type":{"type":"string","description":"UV type, e.g. Charge Time Reduction."},"strength":{"type":["string","null"],"description":"Low, Medium, High or Very High."}}}},"accessories":{"type":"array","description":"Accessories attached to the item.","items":{"type":"object","description":"","properties":{"slug":{"type":["string","null"],"description":"The accessory's item slug."},"variant":{"type":["string","null"],"description":"Its variant."},"slot":{"type":["string","null"],"description":"Where it attaches."}}}},"count":{"type":["integer","null"],"description":"Stack size."},"buy_price":{"type":["integer","null"],"description":"Buy-now price for the stack; null if none."},"bid_price":{"type":["integer","null"],"description":"Current or starting bid for the stack."},"bid_status":{"type":["string","null"],"description":"BID or NO_BID."},"time_left":{"type":["string","null"],"description":"VERY_SHORT, SHORT, MEDIUM, LONG or VERY_LONG."},"estimated_end_at":{"type":["string","null"],"format":"date-time","description":"Predicted end; bids can extend it."},"first_seen_at":{"type":["string","null"],"format":"date-time","description":"When the collector first saw it."}}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-cache-seconds":60,"x-example":{"category":"SWORD","limit":5}}},"/v1/auction/listings/{auction_id}":{"get":{"operationId":"auctionListing","tags":["Auction"],"summary":"One auction","description":"One auction by id. `status` is `live` with a `listing`, or `sold` with a `sale` once it has completed. Auctions that ended without a sale are not kept.","parameters":[{"name":"auction_id","in":"path","required":true,"description":"The game's auction id.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","description":"","properties":{"status":{"type":"string","description":"live or sold."},"listing":{"type":"object","description":"Present when status is live.","properties":{"auction_id":{"type":"integer","description":"The game's auction id."},"slug":{"type":"string","description":"Item slug."},"variant":{"type":["string","null"],"description":"Variant name, e.g. a colour theme."},"uvs":{"type":"array","description":"Unique variants on the item.","items":{"type":"object","description":"","properties":{"type":{"type":"string","description":"UV type, e.g. Charge Time Reduction."},"strength":{"type":["string","null"],"description":"Low, Medium, High or Very High."}}}},"accessories":{"type":"array","description":"Accessories attached to the item.","items":{"type":"object","description":"","properties":{"slug":{"type":["string","null"],"description":"The accessory's item slug."},"variant":{"type":["string","null"],"description":"Its variant."},"slot":{"type":["string","null"],"description":"Where it attaches."}}}},"count":{"type":["integer","null"],"description":"Stack size."},"buy_price":{"type":["integer","null"],"description":"Buy-now price for the stack; null if none."},"bid_price":{"type":["integer","null"],"description":"Current or starting bid for the stack."},"bid_status":{"type":["string","null"],"description":"BID or NO_BID."},"time_left":{"type":["string","null"],"description":"VERY_SHORT, SHORT, MEDIUM, LONG or VERY_LONG."},"estimated_end_at":{"type":["string","null"],"format":"date-time","description":"Predicted end; bids can extend it."},"first_seen_at":{"type":["string","null"],"format":"date-time","description":"When the collector first saw it."}}},"sale":{"type":"object","description":"Present when status is sold.","properties":{"auction_id":{"type":"integer","description":"The game's auction id; negative for a sale added by a contributor."},"slug":{"type":"string","description":"Item slug."},"variant":{"type":["string","null"],"description":"Variant name."},"outcome":{"type":["string","null"],"description":"bought_now or sold_bid (inferred)."},"price":{"type":["integer","null"],"description":"Stack price: the correction if present, else the recorded price."},"recorded_price":{"type":["integer","null"],"description":"Stack price as the collector recorded it."},"corrected_by":{"type":["string","null"],"description":"Public key of the contributor who corrected or added the sale."},"source":{"type":"string","description":"collector or contributor."},"count":{"type":["integer","null"],"description":"Stack size."},"uvs":{"type":"array","description":"Unique variants on the item.","items":{"type":"object","description":"","properties":{"type":{"type":"string","description":"UV type, e.g. Charge Time Reduction."},"strength":{"type":["string","null"],"description":"Low, Medium, High or Very High."}}}},"accessories":{"type":"array","description":"Accessories attached to the item.","items":{"type":"object","description":"","properties":{"slug":{"type":["string","null"],"description":"The accessory's item slug."},"variant":{"type":["string","null"],"description":"Its variant."},"slot":{"type":["string","null"],"description":"Where it attaches."}}}},"sold_at":{"type":["string","null"],"format":"date-time","description":"When the sale completed."}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-cache-seconds":60,"x-example":{"auction_id":null}}},"/v1/auction/items":{"get":{"operationId":"auctionItems","tags":["Auction"],"summary":"Item search","description":"Find catalog items by name. Every other endpoint identifies items by `slug` alone; this is where a slug's display name, category and variants come from.","parameters":[{"name":"q","in":"query","required":true,"description":"Search text, at least 2 characters.","schema":{"type":"string","minLength":2,"maxLength":64}},{"name":"limit","in":"query","required":false,"description":"Rows per page, up to 25.","schema":{"type":"integer","minimum":1,"maximum":25,"default":10}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","description":"","properties":{"items":{"type":"array","description":"Best matches first.","items":{"type":"object","description":"","properties":{"slug":{"type":"string","description":"Item slug."},"name":{"type":"string","description":"Item name."},"category":{"type":["string","null"],"description":"Auction category."},"variants":{"type":"array","description":"Every catalogued variant of the item.","items":{"type":"string","description":""}}}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-cache-seconds":3600,"x-example":{"q":"brandish"}}},"/v1/auction/items/lookup":{"get":{"operationId":"auctionItemLookup","tags":["Auction"],"summary":"Item lookup","description":"The display name, category and variants of up to 25 items at once, by slug. Items come back in the order asked; slugs the catalog does not know are listed in `unknown`.","parameters":[{"name":"slug","in":"query","required":true,"description":"An item slug. Repeat the parameter for each item, up to 25.","schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1,"maxItems":25}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","description":"","properties":{"items":{"type":"array","description":"The items found, in the order asked.","items":{"type":"object","description":"","properties":{"slug":{"type":"string","description":"Item slug."},"name":{"type":"string","description":"Item name."},"category":{"type":["string","null"],"description":"Auction category."},"variants":{"type":"array","description":"Every catalogued variant of the item.","items":{"type":"string","description":""}}}}},"unknown":{"type":"array","description":"Slugs the catalog does not know.","items":{"type":"string","description":""}}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-cache-seconds":3600,"x-example":{"slug":["Brandish","Dapper_Combo","Monster_Pocket"]}}},"/v1/auction/items/{slug}":{"get":{"operationId":"auctionItem","tags":["Auction"],"summary":"Item summary","description":"One item: its name, category, catalogued variants, how many listings are live, how many sales are recorded and when it last sold.","parameters":[{"name":"slug","in":"path","required":true,"description":"Item slug.","schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","description":"","properties":{"slug":{"type":"string","description":"Item slug."},"name":{"type":"string","description":"Item name."},"category":{"type":["string","null"],"description":"Auction category."},"variants":{"type":"array","description":"Every catalogued variant of the item.","items":{"type":"string","description":""}},"live_listings":{"type":"integer","description":"Listings live right now."},"sales":{"type":"integer","description":"Recorded sales."},"last_sold_at":{"type":["string","null"],"format":"date-time","description":"Most recent sale."}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-cache-seconds":300,"x-example":{"slug":"Brandish"}}},"/v1/auction/items/{slug}/sales":{"get":{"operationId":"auctionItemSales","tags":["Auction"],"summary":"Item sale history","description":"Completed sales of one item, newest first. `price` is the price of the whole stack: the contributor's correction when there is one, otherwise the recorded price, which is always kept in `recorded_price`. `corrected_by` is the public key of the contributor who corrected or added the sale. `source` is `collector` for observed sales and `contributor` for sales added by hand. Outcomes are inferred from what the collector saw before a listing disappeared, so some are wrong.","parameters":[{"name":"slug","in":"path","required":true,"description":"Item slug.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"variant","in":"query","required":false,"description":"Exact variant name.","schema":{"type":"string","maxLength":64}},{"name":"uv","in":"query","required":false,"description":"Unique variant filter: `Type|Strength` pairs joined by `;` (strength optional). A row matches when it has every listed UV at that strength or stronger. Strengths: Low, Medium, High, Very High.","schema":{"type":"string","maxLength":512}},{"name":"from","in":"query","required":false,"description":"Sold at or after this time. ISO 8601 or epoch seconds.","schema":{"type":"string","minLength":1,"maxLength":40}},{"name":"to","in":"query","required":false,"description":"Sold before this time.","schema":{"type":"string","minLength":1,"maxLength":40}},{"name":"limit","in":"query","required":false,"description":"Rows per page, up to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"`next_cursor` from the previous page.","schema":{"type":"string","maxLength":256}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","description":"","properties":{"slug":{"type":"string","description":"Item slug."},"total":{"type":"integer","description":"Sales matching the filters."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; null at the end."},"sales":{"type":"array","description":"One page of sales, newest first.","items":{"type":"object","description":"","properties":{"auction_id":{"type":"integer","description":"The game's auction id; negative for a sale added by a contributor."},"variant":{"type":["string","null"],"description":"Variant name."},"outcome":{"type":["string","null"],"description":"bought_now or sold_bid (inferred)."},"price":{"type":["integer","null"],"description":"Stack price: the correction if present, else the recorded price."},"recorded_price":{"type":["integer","null"],"description":"Stack price as the collector recorded it."},"corrected_by":{"type":["string","null"],"description":"Public key of the contributor who corrected or added the sale."},"source":{"type":"string","description":"collector or contributor."},"count":{"type":["integer","null"],"description":"Stack size."},"uvs":{"type":"array","description":"Unique variants on the item.","items":{"type":"object","description":"","properties":{"type":{"type":"string","description":"UV type, e.g. Charge Time Reduction."},"strength":{"type":["string","null"],"description":"Low, Medium, High or Very High."}}}},"accessories":{"type":"array","description":"Accessories attached to the item.","items":{"type":"object","description":"","properties":{"slug":{"type":["string","null"],"description":"The accessory's item slug."},"variant":{"type":["string","null"],"description":"Its variant."},"slot":{"type":["string","null"],"description":"Where it attaches."}}}},"sold_at":{"type":["string","null"],"format":"date-time","description":"When the sale completed."}}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-cache-seconds":300,"x-example":{"slug":"Brandish","limit":5}}},"/v1/auction/items/{slug}/prices":{"get":{"operationId":"auctionItemPrices","tags":["Auction"],"summary":"Item price history","description":"Per-unit sale price in daily or weekly buckets, one series per variant. Only clean sales count: sales with UVs or attached accessories are left out because both raise the price above the item's own. Empty buckets are omitted.","parameters":[{"name":"slug","in":"path","required":true,"description":"Item slug.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"interval","in":"query","required":false,"description":"Bucket size. Weeks start on Monday (UTC).","schema":{"type":"string","enum":["1d","1w"],"default":"1d"}},{"name":"from","in":"query","required":false,"description":"Start of the window (inclusive). Default: 90 days before `to`.","schema":{"type":"string","minLength":1,"maxLength":40}},{"name":"to","in":"query","required":false,"description":"End of the window (exclusive). Default: now.","schema":{"type":"string","minLength":1,"maxLength":40}},{"name":"variant","in":"query","required":false,"description":"Only this variant.","schema":{"type":"string","maxLength":64}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","description":"","properties":{"slug":{"type":"string","description":"Item slug."},"interval":{"type":"string","description":"Bucket size, as requested."},"from":{"type":"string","format":"date-time","description":"Start of the window."},"to":{"type":"string","format":"date-time","description":"End of the window (exclusive)."},"series":{"type":"array","description":"One series per variant.","items":{"type":"object","description":"","properties":{"variant":{"type":["string","null"],"description":"Variant name; null for an item without variants."},"points":{"type":"array","description":"One entry per non-empty bucket, oldest first.","items":{"type":"object","description":"","properties":{"t":{"type":"string","format":"date-time","description":"Bucket start."},"mean":{"type":"number","description":"Mean unit price."},"median":{"type":"number","description":"Median unit price."},"low":{"type":"number","description":"Lowest unit price."},"high":{"type":"number","description":"Highest unit price."},"n":{"type":"integer","description":"Sales in the bucket."}}}}}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-cache-seconds":300,"x-example":{"slug":"Brandish","interval":"1d"}}},"/v1/status":{"get":{"operationId":"status","tags":["Meta"],"summary":"Data freshness","description":"When each dataset last changed. Check `age_seconds` before trusting live values: a stalled collector leaves the last rows in place.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","description":"","properties":{"now":{"type":"string","format":"date-time","description":"Server time."},"energy":{"type":"object","description":"Energy dataset.","properties":{"available":{"type":"boolean","description":"False when the dataset cannot be read; the other fields are then absent."},"last_sample_at":{"type":["string","null"],"format":"date-time","description":"Most recent sample."},"age_seconds":{"type":["integer","null"],"description":"Seconds since that sample."}}},"auction":{"type":"object","description":"Auction dataset.","properties":{"available":{"type":"boolean","description":"False when the dataset cannot be read; the other fields are then absent."},"live_listings":{"type":"integer","description":"Listings live right now."},"last_listing_update_at":{"type":["string","null"],"format":"date-time","description":"Most recent listing update."},"sales":{"type":"integer","description":"Recorded sales."},"last_sale_at":{"type":["string","null"],"format":"date-time","description":"Most recent sale."},"age_seconds":{"type":["integer","null"],"description":"Seconds since the last listing update."}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-cache-seconds":15,"x-example":{}}}},"components":{"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"x-rate-limit":{"max":120,"window":"1 minute","scope":"per IP"}}