{"openapi":"3.1.0","info":{"title":"FoundersPrime API","version":"1.0.0","description":"Public, unauthenticated read API for verified startup deals, credits, and business listings, plus a deal-submission endpoint. All endpoints on this document require no authentication. See /auth.md for member-only capabilities that are out of scope here.","contact":{"name":"FoundersPrime","url":"https://www.foundersprime.com","email":"support@foundersprime.com"},"license":{"name":"Terms of use","url":"https://www.foundersprime.com/terms"}},"servers":[{"url":"https://www.foundersprime.com","description":"Production"}],"tags":[{"name":"Deals","description":"Verified startup credits, SaaS discounts, and program listings."},{"name":"Startups","description":"Business/startup listing aggregation."},{"name":"Submissions","description":"Community deal submissions for editorial review."}],"paths":{"/api/deals":{"get":{"operationId":"listOrSearchDeals","tags":["Deals"],"summary":"List or search verified startup deals","description":"Returns the public deal catalog. Supports category filtering, free-text search, and single-item lookup by slug or id. No authentication required.","parameters":[{"name":"search","in":"query","description":"Free-text search across title, provider, description, and tags.","schema":{"type":"string"}},{"name":"category","in":"query","description":"Filter by category slug, e.g. cloud-credits, saas-discounts, ad-credits.","schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter by lifecycle status.","schema":{"type":"string","enum":["active","expired","coming-soon","limited","all"]}},{"name":"slug","in":"query","description":"Return a single deal by slug instead of a list.","schema":{"type":"string"}},{"name":"id","in":"query","description":"Return a single deal by id instead of a list.","schema":{"type":"string"}},{"name":"featured","in":"query","description":"When \"true\", only featured (paid ad slot) deals.","schema":{"type":"string","enum":["true"]}},{"name":"recommended","in":"query","description":"When \"true\", only editorially recommended deals.","schema":{"type":"string","enum":["true"]}},{"name":"limit","in":"query","description":"Maximum number of results (default: full catalog, capped at 5000).","schema":{"type":"integer","minimum":1}},{"name":"scope","in":"query","description":"Catalog partition: commercial deals vs accelerator/incubator/grant programs.","schema":{"type":"string","enum":["deals","programs","all"],"default":"deals"}}],"responses":{"200":{"description":"A single deal (when `slug`/`id` is given) or a list with aggregate stats.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"deal":{"type":"object","description":"A verified startup deal, credit, or discount listing.","properties":{"id":{"type":"string"},"slug":{"type":"string","description":"URL-safe unique identifier, e.g. `aws-activate`."},"title":{"type":"string"},"provider":{"type":"string","description":"Company or organization offering the deal."},"category":{"type":"string","description":"e.g. cloud-credits, saas-discounts, ad-credits."},"subcategory":{"type":"string"},"description":{"type":"string"},"shortDescription":{"type":"string"},"value":{"type":"string","description":"Human-readable value, e.g. \"$100,000 in credits\"."},"savings":{"type":"string"},"eligibility":{"type":"array","items":{"type":"string"}},"requirements":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","expired","coming-soon","limited"]},"expiryDate":{"type":"string"},"applicationUrl":{"type":"string","format":"uri"},"providerWebsite":{"type":"string","format":"uri"},"logoUrl":{"type":"string","format":"uri"},"featured":{"type":"boolean"},"recommended":{"type":"boolean"},"verified":{"type":"boolean"},"difficulty":{"type":"string","enum":["easy","medium","hard"]},"timeToApply":{"type":"string"},"lastUpdated":{"type":"string"}},"required":["id","slug","title","provider","category","status","applicationUrl"]}},"required":["success","deal"]},{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"deals":{"type":"array","items":{"type":"object","description":"A verified startup deal, credit, or discount listing.","properties":{"id":{"type":"string"},"slug":{"type":"string","description":"URL-safe unique identifier, e.g. `aws-activate`."},"title":{"type":"string"},"provider":{"type":"string","description":"Company or organization offering the deal."},"category":{"type":"string","description":"e.g. cloud-credits, saas-discounts, ad-credits."},"subcategory":{"type":"string"},"description":{"type":"string"},"shortDescription":{"type":"string"},"value":{"type":"string","description":"Human-readable value, e.g. \"$100,000 in credits\"."},"savings":{"type":"string"},"eligibility":{"type":"array","items":{"type":"string"}},"requirements":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","expired","coming-soon","limited"]},"expiryDate":{"type":"string"},"applicationUrl":{"type":"string","format":"uri"},"providerWebsite":{"type":"string","format":"uri"},"logoUrl":{"type":"string","format":"uri"},"featured":{"type":"boolean"},"recommended":{"type":"boolean"},"verified":{"type":"boolean"},"difficulty":{"type":"string","enum":["easy","medium","hard"]},"timeToApply":{"type":"string"},"lastUpdated":{"type":"string"}},"required":["id","slug","title","provider","category","status","applicationUrl"]}},"count":{"type":"integer"},"stats":{"type":"object","properties":{"total":{"type":"integer"},"active":{"type":"integer"},"expired":{"type":"integer"},"featured":{"type":"integer"},"recommended":{"type":"integer"},"scope":{"type":"string","enum":["deals","programs","all"]},"byCategory":{"type":"object","additionalProperties":{"type":"integer"}}}}},"required":["success","deals","count","stats"]}]}}}},"404":{"description":"No deal matches the given slug/id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createDeal","tags":["Deals"],"summary":"Create a deal (admin only)","description":"Creates one deal, or bulk-upserts many via `{ \"deals\": [...] }`. Requires an authenticated admin session cookie — not available to unauthenticated agents.","security":[{"sessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"A partial Deal, or `{ deals: Deal[] }` for bulk import."}}}},"responses":{"200":{"description":"Deal created or bulk import processed.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Deal slug already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not an admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"updateDeal","tags":["Deals"],"summary":"Update a deal (admin only)","description":"Updates an existing deal by `id` or `slug`. Requires an authenticated admin session cookie.","security":[{"sessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"}}}}}},"responses":{"200":{"description":"Deal updated.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Deal ID or slug is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not an admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteDeal","tags":["Deals"],"summary":"Delete deal(s) (admin only)","description":"Deletes one deal by `id`/`slug` query param, or many via a comma-separated `ids` query param. Requires an authenticated admin session cookie.","security":[{"sessionCookie":[]}],"parameters":[{"name":"id","in":"query","schema":{"type":"string"}},{"name":"slug","in":"query","schema":{"type":"string"}},{"name":"ids","in":"query","description":"Comma-separated list of ids for bulk delete.","schema":{"type":"string"}}],"responses":{"200":{"description":"Deal(s) deleted.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Deal ID or slug is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not an admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/startups":{"get":{"operationId":"listStartups","tags":["Startups"],"summary":"List or filter startup/business listings","description":"Returns aggregated startup/business-for-sale listings. No authentication required.","parameters":[{"name":"category","in":"query","schema":{"type":"string"}},{"name":"minRevenue","in":"query","schema":{"type":"integer"}},{"name":"maxRevenue","in":"query","schema":{"type":"integer"}},{"name":"country","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","description":"Free-text search across name, description, and category.","schema":{"type":"string"}},{"name":"source","in":"query","schema":{"type":"string"}},{"name":"featured","in":"query","schema":{"type":"string","enum":["true"]}},{"name":"forSale","in":"query","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"A filtered list of startup listings.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"startups":{"type":"array","items":{"type":"object","description":"A startup/business listing (acquisition marketplace aggregation).","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"revenue":{"type":"number"},"revenueDisplay":{"type":"string"},"askingPrice":{"type":"number"},"askingPriceDisplay":{"type":"string"},"website":{"type":"string","format":"uri"},"country":{"type":"string"},"source":{"type":"string"},"featured":{"type":"boolean"},"forSale":{"type":"boolean"}},"required":["id","slug","name","category"]}},"total":{"type":"integer"}},"required":["success","startups","total"]}}}},"405":{"description":"Only GET is supported on this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/submit-deal":{"post":{"operationId":"submitDeal","tags":["Submissions"],"summary":"Submit a deal for editorial review","description":"Public endpoint for submitting a new deal/credit/discount for the FoundersPrime team to verify and list. Rate limited to 5 submissions per IP per hour. No authentication required.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company_name":{"type":"string","minLength":2,"maxLength":120},"website_url":{"type":"string","format":"uri"},"benefit_description":{"type":"string","minLength":10,"maxLength":2000},"category":{"type":"string","enum":["cloud","saas","marketing","hiring","legal","other"]},"deal_value":{"type":"string","maxLength":100},"redemption_method":{"type":"string","enum":["link","code"],"default":"link"},"redemption_link":{"type":"string","maxLength":300,"description":"A URL when redemption_method is \"link\", or a coupon code."},"is_exclusive":{"type":"boolean"},"submitter_email":{"type":"string","format":"email"},"logo_url":{"type":"string","format":"uri"}},"required":["company_name","website_url","benefit_description","category","deal_value","redemption_link"]}}}},"responses":{"201":{"description":"Submission accepted for review.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"id":{"type":"string"}},"required":["success"]}}}},"400":{"description":"Validation failed — see `error` for the specific field/reason.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Only POST is supported on this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (5 submissions/IP/hour).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Submission system temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["bad_request","validation_error","unauthorized","forbidden","not_found","method_not_allowed","rate_limited","conflict","service_unavailable","internal_error"]},"hint":{"type":"string","description":"Suggested next step to resolve the error."},"timestamp":{"type":"string","format":"date-time"}},"required":["success","error","code","timestamp"]},"Deal":{"type":"object","description":"A verified startup deal, credit, or discount listing.","properties":{"id":{"type":"string"},"slug":{"type":"string","description":"URL-safe unique identifier, e.g. `aws-activate`."},"title":{"type":"string"},"provider":{"type":"string","description":"Company or organization offering the deal."},"category":{"type":"string","description":"e.g. cloud-credits, saas-discounts, ad-credits."},"subcategory":{"type":"string"},"description":{"type":"string"},"shortDescription":{"type":"string"},"value":{"type":"string","description":"Human-readable value, e.g. \"$100,000 in credits\"."},"savings":{"type":"string"},"eligibility":{"type":"array","items":{"type":"string"}},"requirements":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","expired","coming-soon","limited"]},"expiryDate":{"type":"string"},"applicationUrl":{"type":"string","format":"uri"},"providerWebsite":{"type":"string","format":"uri"},"logoUrl":{"type":"string","format":"uri"},"featured":{"type":"boolean"},"recommended":{"type":"boolean"},"verified":{"type":"boolean"},"difficulty":{"type":"string","enum":["easy","medium","hard"]},"timeToApply":{"type":"string"},"lastUpdated":{"type":"string"}},"required":["id","slug","title","provider","category","status","applicationUrl"]},"Startup":{"type":"object","description":"A startup/business listing (acquisition marketplace aggregation).","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"revenue":{"type":"number"},"revenueDisplay":{"type":"string"},"askingPrice":{"type":"number"},"askingPriceDisplay":{"type":"string"},"website":{"type":"string","format":"uri"},"country":{"type":"string"},"source":{"type":"string"},"featured":{"type":"boolean"},"forSale":{"type":"boolean"}},"required":["id","slug","name","category"]}},"securitySchemes":{"sessionCookie":{"type":"apiKey","in":"cookie","name":"sb-access-token","description":"Supabase browser session cookie set after human login. Not obtainable by unauthenticated agents — see /auth.md."}}}}