{"openapi":"3.1.0","info":{"title":"Ambassador (BYOK) API","version":"0.1.0","description":"Ambassador (BYOK) lets an AI assistant read your own Ambassador data through the Ambassador API with a key you supply (Ambassador API key (token)). Read-only: 7 tools (list_ambassadors, list_segments, get_segment, list_orders, get_order, list_referral_attributions, list_rewards). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-ambassador.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-ambassador/docs"},"termsOfService":"https://connectorbay.com/byok-ambassador/terms"},"servers":[{"url":"https://byok-ambassador.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-ambassador/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_ambassadors":{"post":{"operationId":"list_ambassadors","summary":"List the ambassadors (referring contacts) of the company with balances, referral counts and creation date, optionally fi","description":"List the ambassadors (referring contacts) of the company with balances, referral counts and creation date, optionally filtered by segment, activity, balance or date. Use for \"Which of my Ambassador ambassadors have at least 5 referrals\".","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 of results, starting at 1; each page holds at most 100 records.","title":"Page"},"min_referrals":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only ambassadors with at least this many unique referrals.","title":"Min Referrals"},"min_money":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Only ambassadors whose money balance is at least this amount.","title":"Min Money"},"min_points":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only ambassadors whose point balance is at least this amount.","title":"Min Points"},"is_active":{"anyOf":[{"enum":["1","0"],"type":"string"},{"type":"null"}],"default":null,"description":"1 for active ambassadors only, 0 for deactivated only; leave empty for all.","title":"Is Active"},"group":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Segment id (shown in the URL of the segment page) to restrict to.","title":"Group"},"created_at__gte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only ambassadors created on or after this date (YYYY-MM-DD).","title":"Created At  Gte"},"created_at__lte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only ambassadors created on or before this date (YYYY-MM-DD).","title":"Created At  Lte"},"email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the ambassador with this email address.","title":"Email"}},"title":"list_ambassadorsArguments","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_segments":{"post":{"operationId":"list_segments","summary":"List the segments (groups) of ambassadors defined in the account with their id, name, description and ambassador count. ","description":"List the segments (groups) of ambassadors defined in the account with their id, name, description and ambassador count. Use for \"What ambassador segments do I have in Ambassador\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_segmentsArguments","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_segment":{"post":{"operationId":"get_segment","summary":"Get one segment's details and up to 100 of its ambassadors (email addresses), one page at a time. Use for \"Who is in my ","description":"Get one segment's details and up to 100 of its ambassadors (email addresses), one page at a time. Use for \"Who is in my Ambassador segment 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"group_id":{"description":"Segment id as listed on the segments page.","title":"Group Id","type":"integer"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number of ambassadors, starting at 1.","title":"Page"}},"required":["group_id"],"title":"get_segmentArguments","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_orders":{"post":{"operationId":"list_orders","summary":"List recorded orders with revenue, status, campaign and the referring advocate, filtered by customer, advocate, campaign","description":"List recorded orders with revenue, status, campaign and the referring advocate, filtered by customer, advocate, campaign or status (companies on the Ambassador 3.0 programme only). Use for \"What orders were referred by advocate jane@example.com in Ambassador\".","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 of results, starting at 1; each page holds at most 100 records.","title":"Page"},"customer_email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Exact, case-insensitive email of the purchaser.","title":"Customer Email"},"advocate_email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Exact, case-insensitive email of the referring advocate.","title":"Advocate Email"},"campaign_uid":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only orders of this campaign id.","title":"Campaign Uid"},"order_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Substring of your own order reference to search for.","title":"Order Id"},"external_status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders with this status.","title":"External Status"}},"title":"list_ordersArguments","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_order":{"post":{"operationId":"get_order","summary":"Get one order with its currency, line items, customer and advocate; at least one of order_id or order_pk is required. Us","description":"Get one order with its currency, line items, customer and advocate; at least one of order_id or order_pk is required. Use for \"Show Ambassador order 23 with its line items\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"order_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Substring of your own order reference (case-insensitive).","title":"Order Id"},"order_pk":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Substring of the Ambassador order id (case-insensitive).","title":"Order Pk"}},"title":"get_orderArguments","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_referral_attributions":{"post":{"operationId":"list_referral_attributions","summary":"List referral attributions (which advocate referred which customer in which campaign) with active flag and creation time","description":"List referral attributions (which advocate referred which customer in which campaign) with active flag and creation time. Use for \"Which customers did advocate jane@example.com refer in Ambassador\".","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 of results, starting at 1; each page holds at most 100 records.","title":"Page"},"campaign_uid":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only attributions in this campaign id.","title":"Campaign Uid"},"advocate_email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Exact, case-insensitive email of the advocate.","title":"Advocate Email"},"customer_email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Exact, case-insensitive email of the referred customer.","title":"Customer Email"},"advocate_uid":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"External identifier of the advocate.","title":"Advocate Uid"},"customer_uid":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"External identifier of the customer.","title":"Customer Uid"},"is_active":{"anyOf":[{"maximum":1,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"1 for active attributions only, 0 for inactive only.","title":"Is Active"}},"title":"list_referral_attributionsArguments","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_rewards":{"post":{"operationId":"list_rewards","summary":"List rewards earned by ambassadors with status, order, owner and advocate emails and fulfilment time, filtered by status","description":"List rewards earned by ambassadors with status, order, owner and advocate emails and fulfilment time, filtered by status, campaign or date. Use for \"Which Ambassador rewards are still approved but not fulfilled\".","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 of results, starting at 1; each page holds at most 100 records.","title":"Page"},"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only rewards with this status, for example approved or fulfilled.","title":"Status"},"campaign_uid":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only rewards of this campaign id.","title":"Campaign Uid"},"contact_email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Exact, case-insensitive email of the reward owner.","title":"Contact Email"},"created_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only rewards created after this date.","title":"Created After"},"created_before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only rewards created before this date.","title":"Created Before"},"fulfilled_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only rewards fulfilled after this date.","title":"Fulfilled After"}},"title":"list_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}}}}