{"openapi":"3.1.0","info":{"title":"Flipn Public API","version":"1.0.0","description":"Read-only access to active listings on Flipn, India's AI-assisted resale marketplace. Prices are in INR. Every listing has a public page at https://flipn.in/listing/{id} that deep-links into the Android/iOS apps. A remote MCP server with the same capabilities is available at https://api.flipn.in/mcp (streamable HTTP).","contact":{"url":"https://flipn.in/contact"},"termsOfService":"https://flipn.in/terms"},"servers":[{"url":"https://api.flipn.in"}],"paths":{"/v1/listings/search":{"get":{"operationId":"searchListings","summary":"Search or browse active listings","description":"Two modes. Keyword mode: pass `q` for relevance search across all of India (optional `city` narrows results; `page`/`pageSize` pagination). Browse mode: omit `q` and pass `city` for that city's feed (`sort` + `cursor` pagination). At least one of `q` or `city` is required.","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"city","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"},"description":"Category slug from /v1/categories"},{"name":"condition","in":"query","schema":{"type":"string","enum":["new","like_new","excellent","good","fair","for_parts"]}},{"name":"minPrice","in":"query","schema":{"type":"number"},"description":"INR"},{"name":"maxPrice","in":"query","schema":{"type":"number"},"description":"INR"},{"name":"sort","in":"query","schema":{"type":"string","enum":["recency","price_asc","price_desc"]},"description":"Browse mode only"},{"name":"page","in":"query","schema":{"type":"integer","minimum":0},"description":"Keyword mode only"},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Browse mode only; from `nextCursor`"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","description":"A listing search-result card.","properties":{"id":{"type":"string"},"url":{"type":"string","description":"Public listing page on flipn.in; deep-links into the Flipn apps."},"title":{"type":"string"},"price":{"type":"number","description":"Price in INR (rupees)"},"originalPrice":{"type":"number"},"currency":{"type":"string"},"condition":{"type":"string","enum":["new","like_new","excellent","good","fair","for_parts"]},"negotiable":{"type":"boolean"},"status":{"type":"string","enum":["active","reserved","sold"]},"category":{"type":"string","description":"Leaf category slug"},"image":{"type":"string"},"location":{"type":"object","properties":{"city":{"type":"string"},"area":{"type":"string"}},"required":["city"]},"seller":{"type":"object","properties":{"name":{"type":"string"},"verified":{"type":"boolean"}},"required":["name","verified"]},"quantityAvailable":{"type":"integer"},"isNewGoods":{"type":"boolean"},"rating":{"type":"object","properties":{"count":{"type":"integer"},"avg":{"type":"number"}},"required":["count","avg"]},"attributes":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"required":["key","value"]}},"publishedAt":{"type":"string","format":"date-time"}},"required":["id","url","title","price","currency","condition","negotiable","status","category","location","seller"]}},"page":{"type":"integer"},"pageSize":{"type":"integer"},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string"}},"required":["results","pageSize","hasMore"]}}}},"400":{"description":"Missing/invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/listings/{listingId}":{"get":{"operationId":"getListing","summary":"Get one listing","parameters":[{"name":"listingId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Listing details","content":{"application/json":{"schema":{"type":"object","description":"Full public details of one listing.","allOf":[{"type":"object","description":"A listing search-result card.","properties":{"id":{"type":"string"},"url":{"type":"string","description":"Public listing page on flipn.in; deep-links into the Flipn apps."},"title":{"type":"string"},"price":{"type":"number","description":"Price in INR (rupees)"},"originalPrice":{"type":"number"},"currency":{"type":"string"},"condition":{"type":"string","enum":["new","like_new","excellent","good","fair","for_parts"]},"negotiable":{"type":"boolean"},"status":{"type":"string","enum":["active","reserved","sold"]},"category":{"type":"string","description":"Leaf category slug"},"image":{"type":"string"},"location":{"type":"object","properties":{"city":{"type":"string"},"area":{"type":"string"}},"required":["city"]},"seller":{"type":"object","properties":{"name":{"type":"string"},"verified":{"type":"boolean"}},"required":["name","verified"]},"quantityAvailable":{"type":"integer"},"isNewGoods":{"type":"boolean"},"rating":{"type":"object","properties":{"count":{"type":"integer"},"avg":{"type":"number"}},"required":["count","avg"]},"attributes":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"required":["key","value"]}},"publishedAt":{"type":"string","format":"date-time"}},"required":["id","url","title","price","currency","condition","negotiable","status","category","location","seller"]}],"properties":{"description":{"type":"string"},"images":{"type":"array","items":{"type":"string"}},"quantityTotal":{"type":"integer"},"soldAt":{"type":"string","format":"date-time"}}}}}},"404":{"description":"Not publicly available","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/listings/{listingId}/similar":{"get":{"operationId":"getSimilarListings","summary":"Find similar listings","description":"Active listings in the same top-level category and the same city as the given listing, newest first, excluding the listing itself.","parameters":[{"name":"listingId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":20}}],"responses":{"200":{"description":"Similar listings","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","description":"A listing search-result card.","properties":{"id":{"type":"string"},"url":{"type":"string","description":"Public listing page on flipn.in; deep-links into the Flipn apps."},"title":{"type":"string"},"price":{"type":"number","description":"Price in INR (rupees)"},"originalPrice":{"type":"number"},"currency":{"type":"string"},"condition":{"type":"string","enum":["new","like_new","excellent","good","fair","for_parts"]},"negotiable":{"type":"boolean"},"status":{"type":"string","enum":["active","reserved","sold"]},"category":{"type":"string","description":"Leaf category slug"},"image":{"type":"string"},"location":{"type":"object","properties":{"city":{"type":"string"},"area":{"type":"string"}},"required":["city"]},"seller":{"type":"object","properties":{"name":{"type":"string"},"verified":{"type":"boolean"}},"required":["name","verified"]},"quantityAvailable":{"type":"integer"},"isNewGoods":{"type":"boolean"},"rating":{"type":"object","properties":{"count":{"type":"integer"},"avg":{"type":"number"}},"required":["count","avg"]},"attributes":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"required":["key","value"]}},"publishedAt":{"type":"string","format":"date-time"}},"required":["id","url","title","price","currency","condition","negotiable","status","category","location","seller"]}}},"required":["results"]}}}},"404":{"description":"Source listing not publicly available","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/categories":{"get":{"operationId":"listCategories","summary":"List the category tree","responses":{"200":{"description":"Flat category list; build the tree via parentSlug","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"emoji":{"type":"string"},"depth":{"type":"integer"},"isLeaf":{"type":"boolean"},"parentSlug":{"type":"string"}},"required":["slug","name","depth","isLeaf"]}}},"required":["categories"]}}}}}}},"/v1/locations":{"get":{"operationId":"listLocations","summary":"List cities with active listings","responses":{"200":{"description":"Cities ordered by live supply","content":{"application/json":{"schema":{"type":"object","properties":{"locations":{"type":"array","items":{"type":"object","properties":{"city":{"type":"string"},"listingCount":{"type":"integer"}},"required":["city","listingCount"]}}},"required":["locations"]}}}}}}}}}