{"openapi":"3.1.0","info":{"title":"beehiiv Config (BYOK) API","version":"0.1.0","description":"beehiiv Config (BYOK) lets an AI assistant read your own beehiiv Config data through the beehiiv Config API with a key you supply (API key). Read-only: 10 tools (get_workspace, list_custom_fields, list_tiers, list_newsletter_lists, list_condition_sets, list_webhooks, list_post_templates, list_authors, get_referral_program, get_engagement_totals). The BYOK key travels with each request, is used...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-beehiiv-config.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-beehiiv-config/docs"},"termsOfService":"https://connectorbay.com/byok-beehiiv-config/terms"},"servers":[{"url":"https://byok-beehiiv-config.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-beehiiv-config/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_workspace":{"post":{"operationId":"get_workspace","summary":"Show the beehiiv workspace the key belongs to: workspace id and name. Use for \"Which beehiiv workspace is my API key for","description":"Show the beehiiv workspace the key belongs to: workspace id and name. Use for \"Which beehiiv workspace is my API key for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_workspaceArguments","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_custom_fields":{"post":{"operationId":"list_custom_fields","summary":"List a publication's custom field definitions: id, display name, kind (string, integer, boolean, date, datetime, list, d","description":"List a publication's custom field definitions: id, display name, kind (string, integer, boolean, date, datetime, list, double), creation time and list options. No subscriber values. Use for \"What custom subscriber fields exist on my beehiiv publication\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"publication_id":{"description":"Prefixed publication ID, for example 'pub_00000000-0000-0000-0000-000000000000' (from the beehiiv connector's list_publications).","maxLength":200,"title":"Publication Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100). beehiiv's default is 10.","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["publication_id"],"title":"list_custom_fieldsArguments","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_tiers":{"post":{"operationId":"list_tiers","summary":"List a publication's subscription tiers with id, name, status (active or archived) and description. Prices and subscribe","description":"List a publication's subscription tiers with id, name, status (active or archived) and description. Prices and subscriber counts are not requested. Use for \"Which subscription tiers does my beehiiv publication have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"publication_id":{"description":"Prefixed publication ID, for example 'pub_00000000-0000-0000-0000-000000000000' (from the beehiiv connector's list_publications).","maxLength":200,"title":"Publication Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100). beehiiv's default is 10.","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc (default) or desc.","title":"Direction"}},"required":["publication_id"],"title":"list_tiersArguments","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_newsletter_lists":{"post":{"operationId":"list_newsletter_lists","summary":"List newsletter lists (topic-based mailing lists) with name, slug, status, auto-subscribe flag, preference center visibi","description":"List newsletter lists (topic-based mailing lists) with name, slug, status, auto-subscribe flag, preference center visibility and subscriber count. Use for \"Which newsletter lists exist on my beehiiv publication and how many subscribers do they have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"publication_id":{"description":"Prefixed publication ID, for example 'pub_00000000-0000-0000-0000-000000000000' (from the beehiiv connector's list_publications).","maxLength":200,"title":"Publication Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100). beehiiv's default is 10.","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc (default) or desc.","title":"Direction"}},"required":["publication_id"],"title":"list_newsletter_listsArguments","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_condition_sets":{"post":{"operationId":"list_condition_sets","summary":"List dynamic-content condition sets (audience rules) with id, name, status and purpose. Use for \"Which dynamic content c","description":"List dynamic-content condition sets (audience rules) with id, name, status and purpose. Use for \"Which dynamic content condition sets are defined in beehiiv\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"publication_id":{"description":"Prefixed publication ID, for example 'pub_00000000-0000-0000-0000-000000000000' (from the beehiiv connector's list_publications).","maxLength":200,"title":"Publication Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100). beehiiv's default is 10.","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor from next_cursor of the previous answer; leave empty for the first page.","title":"Cursor"},"purpose":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only condition sets with this purpose (for example dynamic_content).","title":"Purpose"}},"required":["publication_id"],"title":"list_condition_setsArguments","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_webhooks":{"post":{"operationId":"list_webhooks","summary":"List a publication's webhook endpoints with subscribed event types, description and dates. Target URLs are not returned.","description":"List a publication's webhook endpoints with subscribed event types, description and dates. Target URLs are not returned. Use for \"Which beehiiv webhooks are configured and what events do they receive\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"publication_id":{"description":"Prefixed publication ID, for example 'pub_00000000-0000-0000-0000-000000000000' (from the beehiiv connector's list_publications).","maxLength":200,"title":"Publication Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100). beehiiv's default is 10.","title":"Limit"}},"required":["publication_id"],"title":"list_webhooksArguments","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_post_templates":{"post":{"operationId":"list_post_templates","summary":"List a publication's post templates with id, name, description and dates. Use for \"Which post templates does my beehiiv ","description":"List a publication's post templates with id, name, description and dates. Use for \"Which post templates does my beehiiv publication have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"publication_id":{"description":"Prefixed publication ID, for example 'pub_00000000-0000-0000-0000-000000000000' (from the beehiiv connector's list_publications).","maxLength":200,"title":"Publication Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100). beehiiv's default is 10.","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"order_by":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Field to order by (default created).","title":"Order By"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Order direction: asc (default) or desc.","title":"Order"}},"required":["publication_id"],"title":"list_post_templatesArguments","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_authors":{"post":{"operationId":"list_authors","summary":"List a publication's authors (team users and guest authors) with id, type and name. Bios and social links are not return","description":"List a publication's authors (team users and guest authors) with id, type and name. Bios and social links are not returned. Use for \"Who are the authors of my beehiiv publication\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"publication_id":{"description":"Prefixed publication ID, for example 'pub_00000000-0000-0000-0000-000000000000' (from the beehiiv connector's list_publications).","maxLength":200,"title":"Publication Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100). beehiiv's default is 10.","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only authors whose full or first name matches (case-insensitive).","title":"Name"}},"required":["publication_id"],"title":"list_authorsArguments","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_referral_program":{"post":{"operationId":"get_referral_program","summary":"Get the referral program setup: reward name, type (physical, promo_code, digital, premium_gift), referral count needed a","description":"Get the referral program setup: reward name, type (physical, promo_code, digital, premium_gift), referral count needed and auto-fulfill flag. Use for \"What rewards does my beehiiv referral program offer\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"publication_id":{"description":"Prefixed publication ID, for example 'pub_00000000-0000-0000-0000-000000000000' (from the beehiiv connector's list_publications).","maxLength":200,"title":"Publication Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100). beehiiv's default is 10.","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["publication_id"],"title":"get_referral_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_engagement_totals":{"post":{"operationId":"get_engagement_totals","summary":"Get aggregate email engagement per day, week or month: total and unique opens, total and unique clicks and verified clic","description":"Get aggregate email engagement per day, week or month: total and unique opens, total and unique clicks and verified clicks. Use for \"How many email opens and clicks did my beehiiv publication get over the last 7 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"publication_id":{"description":"Prefixed publication ID, for example 'pub_00000000-0000-0000-0000-000000000000' (from the beehiiv connector's list_publications).","maxLength":200,"title":"Publication Id","type":"string"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"First day, YYYY-MM-DD (default: yesterday).","title":"Start Date"},"number_of_days":{"anyOf":[{"maximum":31,"minimum":1,"type":"integer"},{"type":"null"}],"default":7,"description":"How many days to cover from start_date (1 to 31).","title":"Number Of Days"},"granularity":{"anyOf":[{"enum":["day","week","month"],"type":"string"},{"type":"null"}],"default":null,"description":"Bucket size: day (default), week or month.","title":"Granularity"},"email_type":{"anyOf":[{"enum":["all","post","message"],"type":"string"},{"type":"null"}],"default":null,"description":"Only post emails or message emails: all, post or message.","title":"Email Type"}},"required":["publication_id"],"title":"get_engagement_totalsArguments","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}}}}