{"openapi":"3.1.0","info":{"title":"Affonso (BYOK) API","version":"0.1.0","description":"Affonso (BYOK) lets an AI assistant read your own Affonso data through the Affonso API with a key you supply (Affonso API key (sk_live_...) with read permissions). Read-only: 11 tools (get_program, get_payment_terms, get_tracking_settings, list_affiliate_groups, list_promotion_urls, list_affiliates, get_affiliate_analytics, list_referrals, list_commissions, get_commission, list_payouts). The BYOK...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-affonso.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-affonso/docs"},"termsOfService":"https://connectorbay.com/byok-affonso/terms"},"servers":[{"url":"https://byok-affonso.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-affonso/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_program":{"post":{"operationId":"get_program","summary":"Get your affiliate program: name, slug, status, access mode, default referral parameter and plan tier and limits. Use fo","description":"Get your affiliate program: name, slug, status, access mode, default referral parameter and plan tier and limits. Use for \"What is the status and plan of my Affonso program\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"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/get_payment_terms":{"post":{"operationId":"get_payment_terms","summary":"Get commission and payout terms: commission type and rate, duration, hold days, payout threshold in cents, frequency, me","description":"Get commission and payout terms: commission type and rate, duration, hold days, payout threshold in cents, frequency, methods and cookie lifetime. Use for \"What commission rate and payout terms does my Affonso program use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_payment_termsArguments","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_tracking_settings":{"post":{"operationId":"get_tracking_settings","summary":"Get referral tracking settings: accepted referral parameters, email and name tracking, postbacks and landing-page decora","description":"Get referral tracking settings: accepted referral parameters, email and name tracking, postbacks and landing-page decoration. Use for \"How does my Affonso program track referrals\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_tracking_settingsArguments","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_affiliate_groups":{"post":{"operationId":"list_affiliate_groups","summary":"List affiliate groups; set expand to include their commission incentives or multi-level tiers. Use for \"Which affiliate ","description":"List affiliate groups; set expand to include their commission incentives or multi-level tiers. Use for \"Which affiliate groups and commission incentives do I have in Affonso\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"expand":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated extras: incentives, multi_level_incentives.","title":"Expand"}},"title":"list_affiliate_groupsArguments","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_promotion_urls":{"post":{"operationId":"list_promotion_urls","summary":"List the landing-page destinations affiliates can promote, with audience, status and default flags. Use for \"Which landi","description":"List the landing-page destinations affiliates can promote, with audience, status and default flags. Use for \"Which landing pages can my Affonso affiliates promote\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_promotion_urlsArguments","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_affiliates":{"post":{"operationId":"list_affiliates","summary":"List affiliates with partnership status, group and signup date (names and email addresses are left out). Use for \"How ma","description":"List affiliates with partnership status, group and signup date (names and email addresses are left out). Use for \"How many Affonso affiliates are approved\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"partnership_status":{"anyOf":[{"enum":["pending","approved","rejected"],"type":"string"},{"type":"null"}],"default":null,"description":"Filter: pending, approved or rejected.","title":"Partnership Status"},"group_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only affiliates of this group id.","title":"Group Id"},"created_gte":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only affiliates created on or after this ISO 8601 date.","title":"Created Gte"},"created_lte":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only affiliates created on or before this ISO 8601 date.","title":"Created Lte"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 200, default 50).","title":"Limit"}},"title":"list_affiliatesArguments","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_affiliate_analytics":{"post":{"operationId":"get_affiliate_analytics","summary":"Get one affiliate's performance: clicks, sign-ups, conversions, sales and commissions, a time series and traffic, geogra","description":"Get one affiliate's performance: clicks, sign-ups, conversions, sales and commissions, a time series and traffic, geography and device breakdowns. Use for \"How is Affonso affiliate a1 performing over the last 30 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Affonso affiliate id (the id from list_affiliates).","maxLength":200,"title":"Id","type":"string"},"range":{"anyOf":[{"enum":["24h","7d","30d","3m","12m","alltime"],"type":"string"},{"type":"null"}],"default":"30d","description":"Preset window: 24h, 7d, 30d, 3m, 12m or alltime.","title":"Range"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Custom start date YYYY-MM-DD (use with end_date; overrides range).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Custom end date YYYY-MM-DD.","title":"End Date"}},"required":["id"],"title":"get_affiliate_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_referrals":{"post":{"operationId":"list_referrals","summary":"List referrals (leads, trials and customers, not raw clicks) with status, affiliate and dates, newest first. Cursor pagi","description":"List referrals (leads, trials and customers, not raw clicks) with status, affiliate and dates, newest first. Cursor paging; email addresses are left out. Use for \"Which Affonso referrals became paying customers\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["lead","trialing","customer","active","canceled","rejected"],"type":"string"},{"type":"null"}],"default":null,"description":"Filter by referral status.","title":"Status"},"affiliate_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only referrals of this affiliate id.","title":"Affiliate Id"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"asc or desc (default desc).","title":"Order"},"starting_after":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor: id of the last referral of the previous page.","title":"Starting After"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page (1 to 100, default 10).","title":"Limit"}},"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/list_commissions":{"post":{"operationId":"list_commissions","summary":"List commissions with amounts, currency, approval status, sale status and hold days. Use for \"Which Affonso commissions ","description":"List commissions with amounts, currency, approval status, sale status and hold days. Use for \"Which Affonso commissions are ready for payment\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["pending","pending_manual_approval","ready_for_payment","paid","declined"],"type":"string"},{"type":"null"}],"default":null,"description":"Commission status.","title":"Status"},"sales_status":{"anyOf":[{"enum":["open","complete","trialing","failed","refunded","partial_refunded"],"type":"string"},{"type":"null"}],"default":null,"description":"Sale status.","title":"Sales Status"},"affiliate_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only this affiliate id.","title":"Affiliate Id"},"referral_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only this referral id.","title":"Referral Id"},"created_gte":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Created on or after this ISO 8601 date.","title":"Created Gte"},"created_lte":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Created on or before this ISO 8601 date.","title":"Created Lte"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 200, default 50).","title":"Limit"}},"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/get_commission":{"post":{"operationId":"get_commission","summary":"Get one commission with amounts, statuses and dates. Use for \"Show me Affonso commission c1\".","description":"Get one commission with amounts, statuses and dates. Use for \"Show me Affonso commission c1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Commission id (from list_commissions).","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_commissionArguments","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 payouts with amount, status, payment method and processing date (payment references and affiliate contact details a","description":"List payouts with amount, status, payment method and processing date (payment references and affiliate contact details are left out). Use for \"Which Affonso payouts are still pending\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["pending","processing","completed","failed","cancelled"],"type":"string"},{"type":"null"}],"default":null,"description":"Payout status.","title":"Status"},"affiliate_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only this affiliate id.","title":"Affiliate Id"},"sort":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":"createdAt:desc","description":"Sort as field:direction, for example createdAt:desc (fields createdAt, updatedAt, amount, processedAt).","title":"Sort"},"date_from":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Created on or after this date, YYYY-MM-DD.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Created on or before this date, YYYY-MM-DD.","title":"Date To"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 200, default 50).","title":"Limit"}},"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}}}}