{"openapi":"3.1.0","info":{"title":"Find A Referral Code API","version":"1.0.0","summary":"Machine-readable surfaces for the Find A Referral Code referral directory.","description":"Find A Referral Code (https://www.findareferralcode.com) lists working referral codes and invite links. Brand HTML pages are the primary source of truth. This OpenAPI document describes discoverable HTTP endpoints for agents and the website. There is no bulk referral-code export partner API.","contact":{"name":"Find A Referral Code","url":"https://www.findareferralcode.com/Contact"},"license":{"name":"Proprietary","url":"https://www.findareferralcode.com/Privacy"}},"servers":[{"url":"https://www.findareferralcode.com","description":"Production"}],"tags":[{"name":"Discovery","description":"Agent and developer discovery documents."},{"name":"Content","description":"Markdown representations of core trust and home pages."},{"name":"Referral pages","description":"Product endpoints used by brand referral pages."},{"name":"Account","description":"Authenticated member endpoints (Clerk session required)."}],"paths":{"/openapi.json":{"get":{"operationId":"getOpenApiSpec","tags":["Discovery"],"summary":"OpenAPI specification","description":"Returns this OpenAPI 3.1 document as JSON so agents can discover endpoints, schemas, and error shapes for function calling.","responses":{"200":{"description":"OpenAPI 3.1 document.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/markdown/{slug}":{"get":{"operationId":"getMarkdownPage","tags":["Content"],"summary":"Fetch a Markdown page body","description":"Returns the Markdown twin for a supported path. Equivalent to sending Accept: text/markdown on the HTML URL. Supported slugs include empty (home), about, contact, privacy, developers, editorial-policy, and llms.txt.","parameters":[{"name":"slug","in":"path","required":false,"description":"Path segments after /api/markdown/. Omit for the homepage. Example: about, privacy, developers.","schema":{"type":"string","examples":["about","privacy","developers","llms.txt"]}}],"responses":{"200":{"description":"Markdown document body.","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Unknown Markdown path.","content":{"text/plain":{"schema":{"type":"string","examples":["Not found"]}}}}}}},"/api/getReferralPageDetails":{"post":{"operationId":"getReferralPageDetails","tags":["Referral pages"],"summary":"Load referral page details by pathname","description":"Returns merchant referral fields for a brand pathname (for example \"capcut\"). Used by the site; agents should prefer the public HTML brand page for citations.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetReferralPageDetailsRequest"}}}},"responses":{"200":{"description":"Referral page details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralPageDetails"}}}},"400":{"description":"Missing page field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"No referral page for that pathname.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/referral-page/view":{"post":{"operationId":"recordReferralPageView","tags":["Referral pages"],"summary":"Increment referral page view count","description":"Records a page view for a brand pathname. Rate limited per IP and pathname.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralPathnameRequest"}}}},"responses":{"200":{"description":"View recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralViewResponse"}}}},"400":{"description":"Invalid JSON or pathname.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Unknown pathname.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/referral-page/vote":{"post":{"operationId":"voteReferralPage","tags":["Referral pages"],"summary":"Upvote or downvote a referral listing","description":"Records whether a main referral worked for the visitor. Rate limited per IP.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralVoteRequest"}}}},"responses":{"200":{"description":"Vote recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralVoteResponse"}}}},"400":{"description":"Invalid body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Unknown pathname.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/notifications":{"get":{"operationId":"listReferralClickNotifications","tags":["Account"],"summary":"List referral click notifications","description":"Returns unread and recent referral-click notifications for the signed-in member. Requires a Clerk session cookie.","responses":{"200":{"description":"Notification list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationsListResponse"}}}},"401":{"description":"Not signed in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/notifications/read":{"post":{"operationId":"markReferralClickNotificationsRead","tags":["Account"],"summary":"Mark notifications as read","description":"Marks the signed-in member referral-click notifications as read. Requires a Clerk session cookie.","responses":{"200":{"description":"Notifications marked read.","content":{"application/json":{"schema":{"type":"object","required":["ok","marked"],"properties":{"ok":{"type":"boolean"},"marked":{"type":"integer","minimum":0}}}}}},"401":{"description":"Not signed in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/log-error":{"post":{"operationId":"logClientError","tags":["Referral pages"],"summary":"Log a client-side error","description":"Accepts a short client error payload for server-side logging. Not a public analytics API.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogErrorRequest"}}}},"responses":{"200":{"description":"Logged.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"}}}}}},"400":{"description":"Invalid JSON body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"schemas":{"ApiError":{"type":"object","required":["error","code","message","hint"],"description":"Structured error body. The string `error` mirrors `message` for older clients.","properties":{"error":{"type":"string","description":"Human-readable error (same as message)."},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["BAD_REQUEST","UNAUTHORIZED","NOT_FOUND","RATE_LIMITED","METHOD_NOT_ALLOWED","INTERNAL_ERROR"]},"message":{"type":"string","description":"Human-readable error message."},"hint":{"type":"string","description":"Suggested next step for an agent or developer."}}},"GetReferralPageDetailsRequest":{"type":"object","required":["page"],"properties":{"page":{"type":"string","description":"Brand pathname without leading slash, e.g. capcut.","examples":["capcut","heygen"]}}},"ReferralPageDetails":{"type":"object","additionalProperties":true,"description":"Merchant referral fields. Shape varies by listing; treat HTML brand pages as canonical for citations.","properties":{"name":{"type":"string"},"pathname":{"type":"string"},"link":{"type":"string"},"code":{"type":"string"}}},"ReferralPathnameRequest":{"type":"object","required":["pathname"],"properties":{"pathname":{"type":"string","description":"Brand pathname, with or without leading slash.","examples":["capcut","/capcut"]}}},"ReferralViewResponse":{"type":"object","required":["ok","pageViews"],"properties":{"ok":{"type":"boolean"},"pageViews":{"type":"integer","minimum":0}}},"ReferralVoteRequest":{"type":"object","required":["pathname","vote"],"properties":{"pathname":{"type":"string","description":"Brand pathname.","examples":["capcut"]},"vote":{"type":"string","enum":["up","down"],"description":"Whether the referral worked."}}},"ReferralVoteResponse":{"type":"object","required":["ok","upvotes","downvotes"],"properties":{"ok":{"type":"boolean"},"upvotes":{"type":"integer","minimum":0},"downvotes":{"type":"integer","minimum":0}}},"NotificationsListResponse":{"type":"object","required":["notifications","unreadCount"],"properties":{"notifications":{"type":"array","items":{"type":"object","additionalProperties":true}},"unreadCount":{"type":"integer","minimum":0}}},"LogErrorRequest":{"type":"object","properties":{"message":{"type":"string"},"stack":{"type":"string"},"context":{"type":"string"}}}}}}