{"openapi":"3.1.0","info":{"title":"icantmarket API","version":"1.0.0","summary":"Verified help-exchange for technical founders.","description":"icantmarket is a help-exchange platform where verified makers post\nstructured asks and substantive reviewers earn the right to post by\nreviewing first (Review-to-Post gate).\n\n## When to use this API\n- post a structured ask on behalf of a signed-in maker\n- submit a substantive review on someone else's open ask\n- list verified products + open public asks for an agent to plan from\n\n## When NOT to use this API\n- not a paid freelance marketplace — no money changes hands\n- not for non-technical / consumer marketing — the cohort is technical\n  founders shipping devtools, AI/ML, infra, or OSS libraries\n- not for bulk outreach or scraping — Review-to-Post + per-token rate\n  limits make automation-as-spam unviable by design\n- not for anonymous posting — every ask is tied to a verified maker\n  identity (GitHub repo, DNS TXT, or package provenance)\n- not for post-launch ad placement — asks are pre-/at-launch help\n  requests, not retrospective promo\n\n## Voice constraint enforced by the platform\nHype-words (revolutionary / game-changing / best-in-class / 10x /\nworld-class / etc.) trigger a 422 on POST /asks. Agents should rewrite\nbefore retrying with `hypeAcknowledged: true`.\n\n## Auth\nCreate a bearer token at https://icantmarket.com/me/api-tokens. Token shape: `ic_<24-hex>`.\nShown exactly once at creation. Reads are public; writes require Bearer.","license":{"name":"MIT","url":"https://github.com/spranab/icantmarket/blob/main/LICENSE"},"contact":{"name":"icantmarket","url":"https://icantmarket.com"}},"servers":[{"url":"https://icantmarket.com/api/v1","description":"Production"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ic_<24-hex>","description":"Generate at https://icantmarket.com/me/api-tokens (sign in first)."}},"schemas":{"Product":{"type":"object","required":["id","slug","name","tagline","canonicalUrl","category","stage","trustLevel"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","example":"yantrikdb-server"},"name":{"type":"string","example":"YantrikDB Server"},"tagline":{"type":"string"},"canonicalUrl":{"type":"string","format":"uri"},"category":{"type":"string","enum":["devtools","oss_libraries","apis_infra","ai_ml_workflow","devops"]},"stage":{"type":"string","enum":["idea","mvp","beta","launched","revenue","scaling"]},"trustLevel":{"type":"string","enum":["L1","L2","L3","L4"],"description":"L1 = ownership verified; L2+ = activity/contribution layered on top. L0 (claimed-only) is filtered from public API."},"verifiedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"Ask":{"type":"object","required":["id","productId","type","iAmBuilding","currentStage","needHelpWith","helperProfile","artifactUrl","timeNeeded","offerBack","successCriteria","status","closesAt","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"productId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["launch","update","milestone","retro","feedback","roast","collab","postmortem"]},"iAmBuilding":{"type":"string","minLength":10,"maxLength":200},"currentStage":{"type":"string","enum":["idea","mvp","beta","launched","revenue","scaling"]},"needHelpWith":{"type":"string","minLength":15,"maxLength":500},"helperProfile":{"type":"string","minLength":10,"maxLength":200},"artifactUrl":{"type":"string","format":"uri"},"timeNeeded":{"type":"string","enum":["5m","15m","30m","1h"]},"offerBack":{"type":"string","minLength":10,"maxLength":200},"successCriteria":{"type":"string","minLength":10,"maxLength":300},"status":{"type":"string","enum":["open","answered","completed","expired","closed"]},"closesAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"AskInput":{"type":"object","required":["productId","type","iAmBuilding","currentStage","needHelpWith","helperProfile","artifactUrl","timeNeeded","offerBack","closesInDays","successCriteria"],"properties":{"productId":{"type":"string","format":"uuid"},"type":{"$ref":"#/components/schemas/Ask/properties/type"},"iAmBuilding":{"type":"string","minLength":10,"maxLength":200},"currentStage":{"$ref":"#/components/schemas/Ask/properties/currentStage"},"needHelpWith":{"type":"string","minLength":15,"maxLength":500},"helperProfile":{"type":"string","minLength":10,"maxLength":200},"artifactUrl":{"type":"string","format":"uri"},"timeNeeded":{"type":"string","enum":["5m","15m","30m","1h"]},"offerBack":{"type":"string","minLength":10,"maxLength":200},"closesInDays":{"type":"integer","minimum":1,"maximum":30},"successCriteria":{"type":"string","minLength":10,"maxLength":300},"visibility":{"type":"string","enum":["public","verified_only"],"default":"public"},"hypeAcknowledged":{"type":"boolean","description":"Set true to override the hype-word detector. The hype words still get recorded as a soft-flag on the ask."}}},"ReviewInput":{"type":"object","required":["askId","body"],"properties":{"askId":{"type":"string","format":"uuid"},"body":{"type":"string","minLength":50,"maxLength":4000,"description":"Substantive prose — pasted boilerplate, low-similarity content, and AI-detected text get flagged."},"hypeAcknowledged":{"type":"boolean"}}},"User":{"type":"object","required":["id","email","isAdmin"],"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"handle":{"type":"string","nullable":true,"example":"pranab"},"isAdmin":{"type":"boolean"},"helperVerifiedAt":{"type":"string","format":"date-time","nullable":true}}},"Error":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"string"}}},"Pagination":{"type":"object","required":["limit","offset"],"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"nextOffset":{"type":"integer","nullable":true}}}}},"paths":{"/products":{"get":{"summary":"List verified products","description":"Public. Returns active products at L1 or above. Useful before posting an ask — the agent picks the maker's own product by slug.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0}},{"name":"category","in":"query","schema":{"type":"string","enum":["devtools","oss_libraries","apis_infra","ai_ml_workflow","devops"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}}},"/products/{slug}":{"get":{"summary":"Fetch one verified product by slug","description":"Public. 404 if missing, revoked, or still L0. Includes count of open asks.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","example":"yantrikdb-server"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/asks":{"get":{"summary":"List open public asks","description":"Public. Only returns visibility=public asks; verified_only asks stay behind the page-level helper-cohort gate. Useful for an agent helping someone find a review opportunity that fits their profile.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0}},{"name":"status","in":"query","schema":{"type":"string","enum":["open","answered","completed","expired","closed"],"default":"open"}},{"name":"type","in":"query","schema":{"$ref":"#/components/schemas/Ask/properties/type"}},{"name":"productSlug","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"asks":{"type":"array","items":{"$ref":"#/components/schemas/Ask"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}},"post":{"summary":"Post a structured ask","description":"Requires bearer token. Author must own the target product, and product must be at L1+ (verified). Second-and-onward asks require a credited Helpful/Completed review (Review-to-Post gate). Hype-words trigger 422 — retry with `hypeAcknowledged: true` to override.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Auth required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not the product owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation, hype-word, gate, or famous-name block","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate-limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/asks/{id}":{"get":{"summary":"Fetch one public ask","description":"Public. 404 if visibility=verified_only.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found / not public","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reviews":{"post":{"summary":"Submit a review on an ask","description":"Requires bearer token. Cannot self-review own asks. Body is checked for hype-words, content-fingerprint similarity against the reviewer's prior reviews, profile-match heuristics, sock-puppet clustering, and AI-generated-content detection. Flags don't block; they surface on the /admin/reviews queue. Recipient sets Helpful/Completed verdict later — that's what unlocks Review-to-Post credit.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Auth required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation, similarity, or self-review block","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate-limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me":{"get":{"summary":"Sanity-check the bearer token","description":"Returns the principal user. Cheap, no side-effects. Call once on agent startup to cache the user id.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"user":{"$ref":"#/components/schemas/User"}}}}}},"401":{"description":"Auth required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}