{"openapi":"3.1.0","info":{"title":"Bento (BYOK) API","version":"0.1.0","description":"Bento (BYOK) lets an AI assistant read your own Bento data through the Bento API with a key you supply (Bento publishable key). Read-only: 11 tools (find_subscriber, search_subscribers, list_tags, list_segments, get_segment, list_broadcasts, list_workflows, get_workflow_stats, get_site_stats, get_segment_stats, get_attribution_stats). The BYOK key travels with each request, is used for that one...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-bento.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-bento/docs"},"termsOfService":"https://connectorbay.com/byok-bento/terms"},"servers":[{"url":"https://byok-bento.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-bento/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/find_subscriber":{"post":{"operationId":"find_subscriber","summary":"Find one subscriber by email address (or Bento UUID): tags, custom fields, unsubscribe status and first-touch attributio","description":"Find one subscriber by email address (or Bento UUID): tags, custom fields, unsubscribe status and first-touch attribution. Use for \"Is jane@example.com subscribed in Bento and which tags does she have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_uuid":{"description":"Your Bento site UUID (Settings, API Keys). An identifier, not a secret.","maxLength":60,"title":"Site Uuid","type":"string"},"email":{"description":"Email address to look up.","maxLength":200,"title":"Email","type":"string"},"uuid":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Bento subscriber UUID, used instead of the email when you have it.","title":"Uuid"}},"required":["site_uuid","email"],"title":"find_subscriberArguments","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/search_subscribers":{"post":{"operationId":"search_subscribers","summary":"Search subscribers (up to 100 per page) by tag names or segment. A team admin must enable Allow Export and Search API in","description":"Search subscribers (up to 100 per page) by tag names or segment. A team admin must enable Allow Export and Search API in the site's security settings. Use for \"Which Bento subscribers have the tag 'customer'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_uuid":{"description":"Your Bento site UUID (Settings, API Keys). An identifier, not a secret.","maxLength":60,"title":"Site Uuid","type":"string"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"tags":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Tag names to filter by, as one comma-separated string such as 'customer,lead'.","title":"Tags"},"segment_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscribers in this segment id.","title":"Segment Id"}},"required":["site_uuid"],"title":"search_subscribersArguments","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_tags":{"post":{"operationId":"list_tags","summary":"List the tags defined in the Bento site. Use for \"Which tags exist in my Bento account\".","description":"List the tags defined in the Bento site. Use for \"Which tags exist in my Bento account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_uuid":{"description":"Your Bento site UUID (Settings, API Keys). An identifier, not a secret.","maxLength":60,"title":"Site Uuid","type":"string"}},"required":["site_uuid"],"title":"list_tagsArguments","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 saved segments of the site with id, name and saved query definition. Use for \"Which saved segments do I have in","description":"List the saved segments of the site with id, name and saved query definition. Use for \"Which saved segments do I have in Bento\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_uuid":{"description":"Your Bento site UUID (Settings, API Keys). An identifier, not a secret.","maxLength":60,"title":"Site Uuid","type":"string"}},"required":["site_uuid"],"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 saved segment with its description and query definition. Use for \"Show Bento segment 10\".","description":"Get one saved segment with its description and query definition. Use for \"Show Bento segment 10\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"segment_id":{"description":"Segment id from list_segments.","maxLength":60,"title":"Segment Id","type":"string"},"site_uuid":{"description":"Your Bento site UUID (Settings, API Keys). An identifier, not a secret.","maxLength":60,"title":"Site Uuid","type":"string"}},"required":["segment_id","site_uuid"],"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_broadcasts":{"post":{"operationId":"list_broadcasts","summary":"List the site's email broadcasts (campaigns), sent ones by default, with name and status; page with page. Use for \"Which","description":"List the site's email broadcasts (campaigns), sent ones by default, with name and status; page with page. Use for \"Which broadcasts have I sent in Bento\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_uuid":{"description":"Your Bento site UUID (Settings, API Keys). An identifier, not a secret.","maxLength":60,"title":"Site Uuid","type":"string"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"status":{"anyOf":[{"enum":["sent","draft","sending","scheduled","paused","canceled"],"type":"string"},{"type":"null"}],"default":"sent","description":"Broadcast status: sent (default), draft, sending, scheduled, paused or canceled.","title":"Status"}},"required":["site_uuid"],"title":"list_broadcastsArguments","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_workflows":{"post":{"operationId":"list_workflows","summary":"List the site's automation workflows with their email templates and performance stats. Use for \"Which automations do I h","description":"List the site's automation workflows with their email templates and performance stats. Use for \"Which automations do I have in Bento\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_uuid":{"description":"Your Bento site UUID (Settings, API Keys). An identifier, not a secret.","maxLength":60,"title":"Site Uuid","type":"string"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["site_uuid"],"title":"list_workflowsArguments","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_workflow_stats":{"post":{"operationId":"get_workflow_stats","summary":"Get per-step entry counts and email stats of one workflow over a window (cached about 10 minutes). Use list_workflows fo","description":"Get per-step entry counts and email stats of one workflow over a window (cached about 10 minutes). Use list_workflows for the id. Use for \"How is my Bento welcome workflow performing over 30 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workflow_id":{"description":"Workflow id from list_workflows.","maxLength":60,"title":"Workflow Id","type":"string"},"site_uuid":{"description":"Your Bento site UUID (Settings, API Keys). An identifier, not a secret.","maxLength":60,"title":"Site Uuid","type":"string"},"days":{"anyOf":[{"maximum":366,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Rolling window in days ending now (default 30, maximum 366).","title":"Days"}},"required":["workflow_id","site_uuid"],"title":"get_workflow_statsArguments","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_site_stats":{"post":{"operationId":"get_site_stats","summary":"Get the site's total user, active subscriber and unsubscriber counts. Rate limited to 30 requests per hour. Use for \"How","description":"Get the site's total user, active subscriber and unsubscriber counts. Rate limited to 30 requests per hour. Use for \"How many subscribers does my Bento site have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_uuid":{"description":"Your Bento site UUID (Settings, API Keys). An identifier, not a secret.","maxLength":60,"title":"Site Uuid","type":"string"}},"required":["site_uuid"],"title":"get_site_statsArguments","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_stats":{"post":{"operationId":"get_segment_stats","summary":"Get user, subscriber and unsubscriber counts of one segment. Rate limited to 30 requests per hour. Use for \"How many peo","description":"Get user, subscriber and unsubscriber counts of one segment. Rate limited to 30 requests per hour. Use for \"How many people are in Bento segment 10\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_uuid":{"description":"Your Bento site UUID (Settings, API Keys). An identifier, not a secret.","maxLength":60,"title":"Site Uuid","type":"string"},"segment_id":{"description":"Segment id from list_segments.","maxLength":60,"title":"Segment Id","type":"string"}},"required":["site_uuid","segment_id"],"title":"get_segment_statsArguments","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_attribution_stats":{"post":{"operationId":"get_attribution_stats","summary":"Get signups, customers and revenue (in cents) by attribution dimension (source, campaign, medium, content or ad), with t","description":"Get signups, customers and revenue (in cents) by attribution dimension (source, campaign, medium, content or ad), with totals and a ranked breakdown. Rate limited to 30 requests per hour. Use for \"How many Bento signups came from each source last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_uuid":{"description":"Your Bento site UUID (Settings, API Keys). An identifier, not a secret.","maxLength":60,"title":"Site Uuid","type":"string"},"dimension":{"anyOf":[{"enum":["source","campaign","medium","content","ad"],"type":"string"},{"type":"null"}],"default":"source","description":"Attribution dimension: source (default), campaign, medium, content or ad.","title":"Dimension"},"value":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only this exact dimension value, for example 'youtube'; empty returns the top values.","title":"Value"},"start_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Window start; natural language such as 'last week' or '3 days ago' is accepted.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Window end; defaults to now.","title":"End Date"},"revenue_mode":{"anyOf":[{"enum":["all_revenue","first_revenue","subscriptions"],"type":"string"},{"type":"null"}],"default":"all_revenue","description":"Revenue to include: all_revenue (default), first_revenue or subscriptions.","title":"Revenue Mode"}},"required":["site_uuid"],"title":"get_attribution_statsArguments","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}}}}