{"openapi":"3.1.0","info":{"title":"GrowSurf (BYOK) API","version":"0.1.0","description":"GrowSurf (BYOK) lets an AI assistant read your own GrowSurf data through the GrowSurf API with a key you supply (GrowSurf REST API key). Read-only: 11 tools (get_team, list_programs, get_program, list_program_rewards, list_participants, get_participant, list_leaderboard, list_referrals, get_program_analytics, list_commissions, list_payouts). The BYOK key travels with each request, is used for...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-growsurf.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-growsurf/docs"},"termsOfService":"https://connectorbay.com/byok-growsurf/terms"},"servers":[{"url":"https://byok-growsurf.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-growsurf/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_team":{"post":{"operationId":"get_team","summary":"Show the team the API key is bound to: name and verification status. Use for \"Which GrowSurf team does my API key belong","description":"Show the team the API key is bound to: name and verification status. Use for \"Which GrowSurf team does my API key belong to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_teamArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_programs":{"post":{"operationId":"list_programs","summary":"List the team's referral and affiliate programs with type, status, currency and participant, referral, impression and in","description":"List the team's referral and affiliate programs with type, status, currency and participant, referral, impression and invite totals. Use for \"Which GrowSurf programs do I run and how many referrals has each produced\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_programsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_program":{"post":{"operationId":"get_program","summary":"Get one program with its totals and its reward rules. Use for \"Show the status and rewards of GrowSurf program 4pdlhb\".","description":"Get one program with its totals and its reward rules. Use for \"Show the status and rewards of GrowSurf program 4pdlhb\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"program_id":{"description":"GrowSurf program (campaign) id, from list_programs, for example '4pdlhb'.","maxLength":40,"title":"Program Id","type":"string"}},"required":["program_id"],"title":"get_programArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_program_rewards":{"post":{"operationId":"list_program_rewards","summary":"List the reward configurations of a program: type, trigger event, title, limits and conversions required. Use for \"What ","description":"List the reward configurations of a program: type, trigger event, title, limits and conversions required. Use for \"What rewards does GrowSurf program 4pdlhb give out\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"program_id":{"description":"GrowSurf program (campaign) id, from list_programs, for example '4pdlhb'.","maxLength":40,"title":"Program Id","type":"string"}},"required":["program_id"],"title":"list_program_rewardsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_participants":{"post":{"operationId":"list_participants","summary":"List the participants of a program (referrers and affiliates) with referral counts, rank, share link and fraud risk leve","description":"List the participants of a program (referrers and affiliates) with referral counts, rank, share link and fraud risk level. Use for \"Who are the participants of GrowSurf program 4pdlhb\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"program_id":{"description":"GrowSurf program (campaign) id, from list_programs, for example '4pdlhb'.","maxLength":40,"title":"Program Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100, default 10).","title":"Limit"},"next_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: the next_id value of the previous answer.","title":"Next Id"}},"required":["program_id"],"title":"list_participantsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_participant":{"post":{"operationId":"get_participant","summary":"Get one participant by id or email: referral counts, rank, share link, fraud risk level and issued rewards. Use for \"Sho","description":"Get one participant by id or email: referral counts, rank, share link, fraud risk level and issued rewards. Use for \"Show the GrowSurf participant jane@example.com in program 4pdlhb\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"program_id":{"description":"GrowSurf program (campaign) id, from list_programs, for example '4pdlhb'.","maxLength":40,"title":"Program Id","type":"string"},"participant_id_or_email":{"description":"GrowSurf participant id or the participant's email address.","maxLength":200,"title":"Participant Id Or Email","type":"string"}},"required":["program_id","participant_id_or_email"],"title":"get_participantArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_leaderboard":{"post":{"operationId":"list_leaderboard","summary":"List a program's leaderboard ordered by all-time, monthly, impressions, referrals, leads, commissions or revenue. Use fo","description":"List a program's leaderboard ordered by all-time, monthly, impressions, referrals, leads, commissions or revenue. Use for \"Who are the top referrers in GrowSurf program 4pdlhb this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"program_id":{"description":"GrowSurf program (campaign) id, from list_programs, for example '4pdlhb'.","maxLength":40,"title":"Program Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100, default 10).","title":"Limit"},"next_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: the next_id value of the previous answer.","title":"Next Id"},"leaderboard_type":{"anyOf":[{"enum":["ALL_TIME","CURRENT_MONTH","PREV_MONTH","TOTAL_IMPRESSION_COUNT","UNIQUE_IMPRESSION_COUNT","BY_COMMISSIONS","BY_REVENUE","BY_REFERRALS","BY_LEADS"],"type":"string"},{"type":"null"}],"default":"ALL_TIME","description":"Ordering: ALL_TIME (default), CURRENT_MONTH, PREV_MONTH, TOTAL_IMPRESSION_COUNT, UNIQUE_IMPRESSION_COUNT, BY_COMMISSIONS, BY_REVENUE, BY_REFERRALS or BY_LEADS.","title":"Leaderboard Type"}},"required":["program_id"],"title":"list_leaderboardArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_referrals":{"post":{"operationId":"list_referrals","summary":"List the referrals and invites of a program, newest update first, filterable by status or email; page with offset or nex","description":"List the referrals and invites of a program, newest update first, filterable by status or email; page with offset or next_id. Use for \"Which referrals in GrowSurf program 4pdlhb are still waiting for credit\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"program_id":{"description":"GrowSurf program (campaign) id, from list_programs, for example '4pdlhb'.","maxLength":40,"title":"Program Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100, default 10).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip (default 0).","title":"Offset"},"referral_status":{"anyOf":[{"enum":["CREDIT_PENDING","CREDIT_AWARDED","CREDIT_EXPIRED","INVITE_SENT"],"type":"string"},{"type":"null"}],"default":null,"description":"Only referrals in this status: CREDIT_PENDING, CREDIT_AWARDED, CREDIT_EXPIRED or INVITE_SENT.","title":"Referral Status"},"email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the referral with this email address.","title":"Email"},"next_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: the next_id value of the previous answer.","title":"Next Id"}},"required":["program_id"],"title":"list_referralsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_program_analytics":{"post":{"operationId":"get_program_analytics","summary":"Get a program's totals for a time window: participants, referrals, invites, impressions, shares by channel, revenue and ","description":"Get a program's totals for a time window: participants, referrals, invites, impressions, shares by channel, revenue and commissions. Use for \"How did GrowSurf program 4pdlhb perform over the last 90 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"program_id":{"description":"GrowSurf program (campaign) id, from list_programs, for example '4pdlhb'.","maxLength":40,"title":"Program Id","type":"string"},"days":{"anyOf":[{"maximum":1825,"minimum":1,"type":"integer"},{"type":"null"}],"default":365,"description":"Window length in days ending now (1 to 1825, default 365).","title":"Days"},"interval":{"anyOf":[{"enum":["day","week","month","total"],"type":"string"},{"type":"null"}],"default":"total","description":"total (default) for one set of totals, or day, week or month to also get a per-period series.","title":"Interval"}},"required":["program_id"],"title":"get_program_analyticsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_commissions":{"post":{"operationId":"list_commissions","summary":"List affiliate commissions of a program with amount, sale amount, currency, status and dates. Use for \"Which commissions","description":"List affiliate commissions of a program with amount, sale amount, currency, status and dates. Use for \"Which commissions are still pending in GrowSurf program 4pdlhb\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"program_id":{"description":"GrowSurf program (campaign) id, from list_programs, for example '4pdlhb'.","maxLength":40,"title":"Program Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100, default 10).","title":"Limit"},"next_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: the next_id value of the previous answer.","title":"Next Id"},"status":{"anyOf":[{"enum":["PENDING","APPROVED","PAID","REVERSED","DELETED"],"type":"string"},{"type":"null"}],"default":null,"description":"Only commissions in this status: PENDING, APPROVED, PAID, REVERSED or DELETED.","title":"Status"}},"required":["program_id"],"title":"list_commissionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_payouts":{"post":{"operationId":"list_payouts","summary":"List affiliate payouts of a program with amount, currency, status and issue dates. Use for \"Which GrowSurf payouts faile","description":"List affiliate payouts of a program with amount, currency, status and issue dates. Use for \"Which GrowSurf payouts failed in program 4pdlhb\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"program_id":{"description":"GrowSurf program (campaign) id, from list_programs, for example '4pdlhb'.","maxLength":40,"title":"Program Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100, default 10).","title":"Limit"},"next_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: the next_id value of the previous answer.","title":"Next Id"},"status":{"anyOf":[{"enum":["UPCOMING","QUEUED","ISSUED","FAILED","REVERSED"],"type":"string"},{"type":"null"}],"default":null,"description":"Only payouts in this status: UPCOMING, QUEUED, ISSUED, FAILED or REVERSED.","title":"Status"}},"required":["program_id"],"title":"list_payoutsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}