{"openapi":"3.0.3","info":{"title":"Shove (shove.lol) public API","description":"Public read API for Shove, a pay-to-rank leaderboard at shove.lol. Rank is the bid. There is no OAuth and no API key for read endpoints. POST /api/checkout starts a Dodo payment and is the only write most clients need. Claim tokens and manage URLs are private.","version":"1.0.0","contact":{"name":"Shove","email":"mail.umarbashir@gmail.com","url":"https://shove.lol/developers"}},"servers":[{"url":"https://shove.lol","description":"Shove (shove.lol)"}],"tags":[{"name":"Discovery","description":"Find the Shove API and confirm it is up."},{"name":"Board","description":"Live ranks, search, and hall of fame."},{"name":"Helpers","description":"Metadata fetch used by the bid form."},{"name":"Payments","description":"Checkout. Not a partner platform."}],"paths":{"/api":{"get":{"operationId":"getShoveApiIndex","tags":["Discovery"],"summary":"List public Shove API endpoints","description":"Returns the Shove product name, docs URLs, and the public REST surface. Use this when an agent knows the name Shove or shove.lol and needs the API map.","responses":{"200":{"description":"API catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiIndex"}}}}}}},"/api/health":{"get":{"operationId":"getShoveHealth","tags":["Discovery"],"summary":"Shove health check","description":"Liveness probe for Shove. Confirms the process can reach the database. Includes product name and pointers to docs and OpenAPI.","responses":{"200":{"description":"Shove is healthy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"503":{"description":"Structured JSON error with a code, message, and recovery hint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/board":{"get":{"operationId":"getShoveBoard","tags":["Board"],"summary":"Read the live Shove board","description":"Returns the current Shove leaderboard as JSON: public listings with rank, bid, clicks, and cost per click, plus recent activity, site stats, the price to take #1, and the crown-lock price. Omit category for the global board.","parameters":[{"name":"category","in":"query","required":false,"description":"Arena slug. When set, listings are limited to that category.","schema":{"type":"string","enum":["ai","devtools","seo","crypto","health","marketing","business","design","social","other"]}}],"responses":{"200":{"description":"Live board payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardPayload"}}}},"400":{"description":"Structured JSON error with a code, message, and recovery hint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/listings":{"get":{"operationId":"searchShoveListings","tags":["Board"],"summary":"Search public Shove listings","description":"Directory search over public Shove listings. Filter by free-text query and optional arena. Does not increment visitor stats. Ranks are computed on the selected board (global or category).","parameters":[{"name":"q","in":"query","required":false,"description":"Case-insensitive match against title, URL, handle, description, or category.","schema":{"type":"string","maxLength":200}},{"name":"category","in":"query","required":false,"description":"Arena slug.","schema":{"type":"string","enum":["ai","devtools","seo","crypto","health","marketing","business","design","social","other"]}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 50. Maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","required":false,"description":"Number of matching listings to skip.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Matching public listings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingSearch"}}}},"400":{"description":"Structured JSON error with a code, message, and recovery hint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/listings/{id}":{"get":{"operationId":"getShoveListing","tags":["Board"],"summary":"Get one public Shove listing","description":"Returns one public listing by id, including its current global rank. Does not expose claim tokens, emails, or manage URLs.","parameters":[{"name":"id","in":"path","required":true,"description":"Public listing id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Public listing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingEnvelope"}}}},"404":{"description":"Structured JSON error with a code, message, and recovery hint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/fame":{"get":{"operationId":"getShoveFame","tags":["Board"],"summary":"Read the Shove hall of fame","description":"Weekly record of who sat at #1 on Shove. Newest week first. Seasons start Monday 00:00 UTC.","responses":{"200":{"description":"Hall of fame entries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FameList"}}}}}}},"/api/meta":{"get":{"operationId":"getShoveUrlMetadata","tags":["Helpers"],"summary":"Fetch Open Graph metadata for a URL","description":"Fetches title, description, image, and favicon for an http(s) URL. Used by the Shove bid form. Soft-fails to null fields when the remote page cannot be read.","parameters":[{"name":"url","in":"query","required":true,"description":"Absolute http or https URL, or a host that can be prefixed with https://.","schema":{"type":"string"}}],"responses":{"200":{"description":"URL metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UrlMetadata"}}}},"400":{"description":"Structured JSON error with a code, message, and recovery hint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/checkout":{"post":{"operationId":"createShoveCheckout","tags":["Payments"],"summary":"Start a Shove bid checkout","description":"Creates a pending checkout and returns a Dodo Payments URL. Validates the bid against live ranking rules. This starts a real payment. There is no API key; abuse is limited by payment. Do not send claim tokens here.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}}},"responses":{"200":{"description":"Checkout URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}}},"400":{"description":"Structured JSON error with a code, message, and recovery hint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Structured JSON error with a code, message, and recovery hint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/openapi.json":{"get":{"operationId":"getShoveOpenApi","tags":["Discovery"],"summary":"Download the Shove OpenAPI document","description":"This OpenAPI 3.0.3 document. Use it for LLM function calling: every operation has a unique operationId, a description, typed parameters, and response schemas.","responses":{"200":{"description":"OpenAPI 3.0.3 document.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}}},"components":{"schemas":{"ApiError":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","hint"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code.","example":"INVALID_QUERY"},"message":{"type":"string","description":"What went wrong."},"hint":{"type":"string","description":"How an agent or client should recover."}}}}},"PublicListing":{"type":"object","additionalProperties":false,"required":["id","rank","url","handle","title","description","imageUrl","faviconUrl","category","bid","lifetimePaid","clicks","cpc","lockUntil","lastBidAt","createdAt"],"properties":{"id":{"type":"string","description":"Public listing id."},"rank":{"type":"integer","minimum":1,"description":"Current rank. 1 is first place."},"url":{"type":"string","format":"uri","description":"Destination URL."},"handle":{"type":"string","nullable":true,"description":"Social handle when the listing is an @handle."},"title":{"type":"string"},"description":{"type":"string"},"imageUrl":{"type":"string","format":"uri","nullable":true},"faviconUrl":{"type":"string","format":"uri","nullable":true},"category":{"type":"string","enum":["ai","devtools","seo","crypto","health","marketing","business","design","social","other"],"description":"Arena slug."},"bid":{"type":"integer","minimum":1,"description":"Current bid in whole US dollars."},"lifetimePaid":{"type":"integer","minimum":0},"clicks":{"type":"integer","minimum":0,"description":"Public click-through count."},"cpc":{"type":"number","nullable":true,"description":"Bid divided by clicks, or null when clicks are 0."},"lockUntil":{"type":"string","format":"date-time","nullable":true,"description":"Crown lock expiry, if the listing holds #1."},"lastBidAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"Activity":{"type":"object","additionalProperties":false,"required":["id","type","message","amount","rank","createdAt","listingId"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["NEW","BID","CROWN","OUTBID"]},"message":{"type":"string"},"amount":{"type":"integer"},"rank":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"listingId":{"type":"string","nullable":true}}},"BoardStats":{"type":"object","additionalProperties":false,"required":["visitors","revenue","listings","online"],"properties":{"visitors":{"type":"integer"},"revenue":{"type":"integer","description":"Lifetime paid bids in whole US dollars."},"listings":{"type":"integer"},"online":{"type":"integer"}}},"BoardPayload":{"type":"object","additionalProperties":false,"required":["listings","activity","stats","topBid","claimOnePrice","crownPrice","crownHolder"],"properties":{"listings":{"type":"array","items":{"$ref":"#/components/schemas/PublicListing"}},"activity":{"type":"array","items":{"$ref":"#/components/schemas/Activity"}},"stats":{"$ref":"#/components/schemas/BoardStats"},"topBid":{"type":"integer"},"claimOnePrice":{"type":"integer","description":"Whole dollars needed to take current #1."},"crownPrice":{"type":"integer","description":"Whole dollars to crown-lock #1 for three hours."},"crownHolder":{"oneOf":[{"$ref":"#/components/schemas/PublicListing"},{"type":"null"}]}}},"ListingSearch":{"type":"object","additionalProperties":false,"required":["listings","total","offset","limit"],"properties":{"listings":{"type":"array","items":{"$ref":"#/components/schemas/PublicListing"}},"total":{"type":"integer","minimum":0},"offset":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1}}},"ListingEnvelope":{"type":"object","additionalProperties":false,"required":["listing"],"properties":{"listing":{"$ref":"#/components/schemas/PublicListing"}}},"FameEntry":{"type":"object","additionalProperties":false,"required":["id","weekStart","listingId","bid","title","url"],"properties":{"id":{"type":"string"},"weekStart":{"type":"string","format":"date-time"},"listingId":{"type":"string"},"bid":{"type":"integer"},"title":{"type":"string"},"url":{"type":"string","format":"uri"}}},"FameList":{"type":"object","additionalProperties":false,"required":["entries"],"properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/FameEntry"}}}},"UrlMetadata":{"type":"object","additionalProperties":false,"required":["title","description","imageUrl","faviconUrl"],"properties":{"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"imageUrl":{"type":"string","nullable":true},"faviconUrl":{"type":"string","nullable":true}}},"Health":{"type":"object","additionalProperties":false,"required":["ok","product","name","domain","docs","openapi","time"],"properties":{"ok":{"type":"boolean"},"product":{"type":"string","example":"Shove"},"name":{"type":"string","example":"Shove"},"domain":{"type":"string","example":"shove.lol"},"docs":{"type":"string","example":"/developers"},"openapi":{"type":"string","example":"/openapi.json"},"time":{"type":"string","format":"date-time"}}},"ApiIndex":{"type":"object","additionalProperties":false,"required":["product","name","domain","description","docs","openapi","llms","authentication","endpoints"],"properties":{"product":{"type":"string","example":"Shove"},"name":{"type":"string","example":"Shove"},"domain":{"type":"string","example":"shove.lol"},"description":{"type":"string"},"docs":{"type":"string"},"openapi":{"type":"string"},"llms":{"type":"string"},"authentication":{"type":"string"},"endpoints":{"type":"array","items":{"$ref":"#/components/schemas/ApiEndpoint"}}}},"ApiEndpoint":{"type":"object","additionalProperties":false,"required":["method","path","operationId","description"],"properties":{"method":{"type":"string"},"path":{"type":"string"},"operationId":{"type":"string"},"description":{"type":"string"}}},"CheckoutRequest":{"type":"object","additionalProperties":false,"required":["input","bid","category"],"properties":{"input":{"type":"string","description":"Destination URL or @handle."},"bid":{"type":"integer","minimum":1,"maximum":999999,"description":"Target absolute bid in whole US dollars."},"category":{"type":"string","enum":["ai","devtools","seo","crypto","health","marketing","business","design","social","other"]},"email":{"type":"string","format":"email"},"title":{"type":"string"},"description":{"type":"string"},"referrerId":{"type":"string"},"kind":{"type":"string","enum":["NEW","TOPUP","CROWN"]}}},"CheckoutResponse":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Dodo Payments (or demo) checkout URL."}}}}}}