{"openapi":"3.1.0","info":{"title":"beehiiv (BYOK) API","version":"0.1.0","description":"beehiiv (BYOK) lets an AI assistant read your own beehiiv data through the beehiiv API with a key you supply (API key). Read-only: 8 tools (list_publications, get_publication, list_posts, get_post, get_posts_aggregate_stats, list_subscriptions, list_segments, list_automations). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-beehiiv.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-beehiiv/docs"},"termsOfService":"https://connectorbay.com/byok-beehiiv/terms"},"servers":[{"url":"https://byok-beehiiv.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-beehiiv/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_publications":{"post":{"operationId":"list_publications","summary":"List the publications the key can access with ID, name, organization and creation time, optionally with subscriber count","description":"List the publications the key can access with ID, name, organization and creation time, optionally with subscriber counts and open and click rates. Use for \"Which beehiiv publications can my key see\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"expand":{"anyOf":[{"const":"stats","type":"string"},{"type":"null"}],"default":null,"description":"Set to stats to add subscriber counts, average open and click rates and total sent.","title":"Expand"},"order_by":{"anyOf":[{"enum":["created","name"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by created or name.","title":"Order By"},"direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc or desc.","title":"Direction"},"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"}},"title":"list_publicationsArguments","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_publication":{"post":{"operationId":"get_publication","summary":"Get one publication with name, organization and creation time, optionally with subscriber counts and average open and cl","description":"Get one publication with name, organization and creation time, optionally with subscriber counts and average open and click rates. Use for \"How many active subscribers 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 list_publications).","maxLength":200,"title":"Publication Id","type":"string"},"expand":{"anyOf":[{"const":"stats","type":"string"},{"type":"null"}],"default":"stats","description":"Set to stats to add subscriber counts, average open and click rates and total sent.","title":"Expand"}},"required":["publication_id"],"title":"get_publicationArguments","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_posts":{"post":{"operationId":"list_posts","summary":"List a publication's posts with title, status, audience, platform, authors, dates, web URL and, optionally, email and we","description":"List a publication's posts with title, status, audience, platform, authors, dates, web URL and, optionally, email and web statistics. Times are Unix seconds. Never sends or publishes. Use for \"How did my latest beehiiv posts perform\".","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 list_publications).","maxLength":200,"title":"Publication Id","type":"string"},"status":{"anyOf":[{"enum":["draft","confirmed","archived","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Post status: draft, confirmed (scheduled or sent), archived or all.","title":"Status"},"audience":{"anyOf":[{"enum":["free","premium","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Audience: free, premium or all.","title":"Audience"},"platform":{"anyOf":[{"enum":["web","email","both","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Where it is published: web, email, both or all.","title":"Platform"},"expand":{"anyOf":[{"const":"stats","type":"string"},{"type":"null"}],"default":"stats","description":"Set to stats to add email and web statistics to each post.","title":"Expand"},"order_by":{"anyOf":[{"enum":["created","publish_date","displayed_date"],"type":"string"},{"type":"null"}],"default":"publish_date","description":"Order by created, publish_date or displayed_date (beehiiv sorts ascending unless direction is desc).","title":"Order By"},"direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort direction: asc or desc.","title":"Direction"},"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_postsArguments","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_post":{"post":{"operationId":"get_post","summary":"Get one post with title, subject line, status, audience, dates, web URL and, optionally, its email and web statistics (t","description":"Get one post with title, subject line, status, audience, dates, web URL and, optionally, its email and web statistics (the body is not returned). Use for \"Show the statistics of one beehiiv post\".","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 list_publications).","maxLength":200,"title":"Publication Id","type":"string"},"post_id":{"description":"Prefixed post ID, for example 'post_00000000-0000-0000-0000-000000000000' (from list_posts).","maxLength":200,"title":"Post Id","type":"string"},"expand":{"anyOf":[{"const":"stats","type":"string"},{"type":"null"}],"default":"stats","description":"Set to stats to add email and web statistics.","title":"Expand"}},"required":["publication_id","post_id"],"title":"get_postArguments","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_posts_aggregate_stats":{"post":{"operationId":"get_posts_aggregate_stats","summary":"Get combined email and web statistics (recipients, opens, clicks, unsubscribes, views) across all posts of a publication","description":"Get combined email and web statistics (recipients, opens, clicks, unsubscribes, views) across all posts of a publication, filtered by status, audience or platform. Use for \"What are the total opens and clicks across my beehiiv posts\".","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 list_publications).","maxLength":200,"title":"Publication Id","type":"string"},"status":{"anyOf":[{"enum":["draft","confirmed","archived","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Post status: draft, confirmed, archived or all.","title":"Status"},"audience":{"anyOf":[{"enum":["free","premium","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Audience: free, premium or all.","title":"Audience"},"platform":{"anyOf":[{"enum":["web","email","both","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Where it is published: web, email, both or all.","title":"Platform"}},"required":["publication_id"],"title":"get_posts_aggregate_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/list_subscriptions":{"post":{"operationId":"list_subscriptions","summary":"List a publication's subscribers with email, status, tier, creation time (Unix seconds), acquisition channel and UTM sou","description":"List a publication's subscribers with email, status, tier, creation time (Unix seconds), acquisition channel and UTM source. Filter by email, status or tier; page with a cursor. Use for \"Who are my newest active beehiiv subscribers\".","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 list_publications).","maxLength":200,"title":"Publication Id","type":"string"},"status":{"anyOf":[{"enum":["validating","invalid","pending","active","inactive","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Subscription status: validating, invalid, pending, active, inactive or all.","title":"Status"},"tier":{"anyOf":[{"enum":["free","premium","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Tier: free, premium or all.","title":"Tier"},"email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Exact email address to look up (case-insensitive).","title":"Email"},"direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort direction by creation time: asc or desc.","title":"Direction"},"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":500,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: pass next_cursor from the previous answer (leave empty for the first page).","title":"Cursor"}},"required":["publication_id"],"title":"list_subscriptionsArguments","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 a publication's segments with type, calculation status, active flag, subscriber total and last calculation time, op","description":"List a publication's segments with type, calculation status, active flag, subscriber total and last calculation time, optionally with engagement statistics. Use for \"What segments do I have 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 list_publications).","maxLength":200,"title":"Publication Id","type":"string"},"type":{"anyOf":[{"enum":["dynamic","static","manual","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Segment type: dynamic, static, manual or all.","title":"Type"},"status":{"anyOf":[{"enum":["pending","processing","completed","failed","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Calculation status: pending, processing, completed, failed or all.","title":"Status"},"order_by":{"anyOf":[{"enum":["created","last_calculated"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by created or last_calculated.","title":"Order By"},"direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc or desc.","title":"Direction"},"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_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/list_automations":{"post":{"operationId":"list_automations","summary":"List a publication's automations with name, status, trigger events and description, optionally with journey and email st","description":"List a publication's automations with name, status, trigger events and description, optionally with journey and email statistics. Use for \"Which automations are live in 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 list_publications).","maxLength":200,"title":"Publication Id","type":"string"},"expand":{"anyOf":[{"const":"stats","type":"string"},{"type":"null"}],"default":null,"description":"Set to stats to add journey counts and email statistics.","title":"Expand"},"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_automationsArguments","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}}}}