{"openapi":"3.1.0","info":{"title":"Tapfiliate (BYOK) API","version":"0.1.0","description":"Tapfiliate (BYOK) lets an AI assistant read your own Tapfiliate data through the Tapfiliate API with a key you supply (API key (profile settings)). Read-only: 12 tools (list_programs, list_affiliates, get_affiliate, list_program_affiliates, list_conversions, get_conversion, list_commissions, list_customers, list_clicks, list_balances, list_payments, list_affiliate_groups). The BYOK key travels...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-tapfiliate.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-tapfiliate/docs"},"termsOfService":"https://connectorbay.com/byok-tapfiliate/terms"},"servers":[{"url":"https://byok-tapfiliate.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-tapfiliate/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/list_programs":{"post":{"operationId":"list_programs","summary":"List affiliate programs with currency, cookie time, default landing page, recurring flag and status. Use for \"What affil","description":"List affiliate programs with currency, cookie time, default landing page, recurring flag and status. Use for \"What affiliate programs do I run in Tapfiliate\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; each page holds 25 items.","title":"Page"}},"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/list_affiliates":{"post":{"operationId":"list_affiliates","summary":"List affiliates (25 per page) optionally filtered by email, referral code, parent affiliate or affiliate group. Use for ","description":"List affiliates (25 per page) optionally filtered by email, referral code, parent affiliate or affiliate group. Use for \"Who are my Tapfiliate affiliates\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the affiliate with this email address.","title":"Email"},"referral_code":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the affiliate with this referral code (the ref= value of their link).","title":"Referral Code"},"parent_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only children of this parent affiliate id.","title":"Parent Id"},"affiliate_group_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only affiliates of this group id.","title":"Affiliate Group Id"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; each page holds 25 items.","title":"Page"}},"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":{"post":{"operationId":"get_affiliate","summary":"Get one affiliate by id: name, email, company, parent, group and sign-up dates. Use for \"Show Tapfiliate affiliate janej","description":"Get one affiliate by id: name, email, company, parent, group and sign-up dates. Use for \"Show Tapfiliate affiliate janejameson\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"affiliate_id":{"description":"Affiliate id, a text id such as 'janejameson'.","maxLength":200,"title":"Affiliate Id","type":"string"}},"required":["affiliate_id"],"title":"get_affiliateArguments","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_affiliates":{"post":{"operationId":"list_program_affiliates","summary":"List the affiliates of one program with approval flag, referral link and coupon. Use for \"Which affiliates joined progra","description":"List the affiliates of one program with approval flag, referral link and coupon. Use for \"Which affiliates joined program johns-affiliate-program in Tapfiliate\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"program_id":{"description":"Program id from list_programs.","maxLength":200,"title":"Program Id","type":"string"},"email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the affiliate with this email address.","title":"Email"},"affiliate_group_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only affiliates of this group id.","title":"Affiliate Group Id"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; each page holds 25 items.","title":"Page"}},"required":["program_id"],"title":"list_program_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/list_conversions":{"post":{"operationId":"list_conversions","summary":"List conversions (sales or actions that earn commissions, 25 per page) with amount, program, affiliate, customer and com","description":"List conversions (sales or actions that earn commissions, 25 per page) with amount, program, affiliate, customer and commissions, optionally by program, affiliate, external id, pending flag or dates. Use for \"What conversions did my Tapfiliate affiliates bring in this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"program_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this program id (a text id such as 'johns-affiliate-program' from list_programs).","title":"Program Id"},"affiliate_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this affiliate id (a text id such as 'janejameson' from list_affiliates).","title":"Affiliate Id"},"external_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the conversion with this order id from your own system.","title":"External Id"},"pending":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to show only conversions that still have pending commissions.","title":"Pending"},"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"First day to include, a UTC day formatted YYYY-MM-DD.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Last day to include, a UTC day formatted YYYY-MM-DD.","title":"Date To"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; each page holds 25 items.","title":"Page"}},"title":"list_conversionsArguments","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_conversion":{"post":{"operationId":"get_conversion","summary":"Get one conversion with its commissions, click, program, affiliate and customer. Use for \"Show Tapfiliate conversion 1\".","description":"Get one conversion with its commissions, click, program, affiliate and customer. Use for \"Show Tapfiliate conversion 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"conversion_id":{"description":"Numeric conversion id from list_conversions.","title":"Conversion Id","type":"integer"}},"required":["conversion_id"],"title":"get_conversionArguments","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 amount, currency, kind, approval state and conversion id, optionally by affiliate, approval status","description":"List commissions with amount, currency, kind, approval state and conversion id, optionally by affiliate, approval status or paid flag. Use for \"Which Tapfiliate commissions are pending approval\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"affiliate_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this affiliate id (a text id such as 'janejameson' from list_affiliates).","title":"Affiliate Id"},"status":{"anyOf":[{"enum":["approved","disapproved","pending"],"type":"string"},{"type":"null"}],"default":null,"description":"Only commissions with this approval status.","title":"Status"},"paid":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for commissions already paid out, false for unpaid ones.","title":"Paid"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; each page holds 25 items.","title":"Page"}},"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_customers":{"post":{"operationId":"list_customers","summary":"List referred customers with status, program, affiliate and the click that led to them. Use for \"Which customers did aff","description":"List referred customers with status, program, affiliate and the click that led to them. Use for \"Which customers did affiliate janejameson bring in on Tapfiliate\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"program_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this program id (a text id such as 'johns-affiliate-program' from list_programs).","title":"Program Id"},"affiliate_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this affiliate id (a text id such as 'janejameson' from list_affiliates).","title":"Affiliate Id"},"customer_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the customer with this id from your own system.","title":"Customer Id"},"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"First day to include, a UTC day formatted YYYY-MM-DD.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Last day to include, a UTC day formatted YYYY-MM-DD.","title":"Date To"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; each page holds 25 items.","title":"Page"}},"title":"list_customersArguments","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_clicks":{"post":{"operationId":"list_clicks","summary":"List clicks on affiliate links with time, device details, referrer, landing page and country. This endpoint is limited t","description":"List clicks on affiliate links with time, device details, referrer, landing page and country. This endpoint is limited to 100 calls per minute. Use for \"How many clicks did affiliate janejameson get on Tapfiliate last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"program_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this program id (a text id such as 'johns-affiliate-program' from list_programs).","title":"Program Id"},"affiliate_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this affiliate id (a text id such as 'janejameson' from list_affiliates).","title":"Affiliate Id"},"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"First day to include, a UTC day formatted YYYY-MM-DD.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Last day to include, a UTC day formatted YYYY-MM-DD.","title":"Date To"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; each page holds 25 items.","title":"Page"}},"title":"list_clicksArguments","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_balances":{"post":{"operationId":"list_balances","summary":"List every affiliate's non-zero unpaid balance by currency (not paginated; limited to 10 calls per minute). Use for \"How","description":"List every affiliate's non-zero unpaid balance by currency (not paginated; limited to 10 calls per minute). Use for \"How much do I owe my Tapfiliate affiliates right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_balancesArguments","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_payments":{"post":{"operationId":"list_payments","summary":"List payments already made to affiliates with date, amount and currency. Use for \"What affiliate payments have I made th","description":"List payments already made to affiliates with date, amount and currency. Use for \"What affiliate payments have I made through Tapfiliate\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; each page holds 25 items.","title":"Page"}},"title":"list_paymentsArguments","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 with the number of affiliates in each. Use for \"What affiliate groups exist in Tapfiliate\".","description":"List affiliate groups with the number of affiliates in each. Use for \"What affiliate groups exist in Tapfiliate\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; each page holds 25 items.","title":"Page"}},"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}}}}