{"openapi":"3.1.0","info":{"title":"Paragraph (BYOK) API","version":"0.1.0","description":"Paragraph (BYOK) lets an AI assistant read your own Paragraph data through the Paragraph API with a key you supply (Paragraph API key (belongs to one publication)). Read-only: 11 tools (get_my_publication, get_subscriber_count, get_publication_by_slug, list_my_posts, list_publication_posts, get_post, list_posts_feed, list_posts_by_tag, search_posts, search_publications, list_drafted_content). The...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-paragraph.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-paragraph/docs"},"termsOfService":"https://connectorbay.com/byok-paragraph/terms"},"servers":[{"url":"https://byok-paragraph.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-paragraph/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_my_publication":{"post":{"operationId":"get_my_publication","summary":"Show the publication the API key belongs to: name, slug, custom domain, summary and plan. Use for \"Which Paragraph publi","description":"Show the publication the API key belongs to: name, slug, custom domain, summary and plan. Use for \"Which Paragraph publication is this key for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_my_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/get_subscriber_count":{"post":{"operationId":"get_subscriber_count","summary":"Get the total number of subscribers of a publication. Use for \"How many subscribers does my Paragraph publication have\".","description":"Get the total number of subscribers of a publication. Use for \"How many subscribers does my Paragraph publication have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"publication_id":{"description":"Publication id (from get_my_publication).","maxLength":200,"title":"Publication Id","type":"string"}},"required":["publication_id"],"title":"get_subscriber_countArguments","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_by_slug":{"post":{"operationId":"get_publication_by_slug","summary":"Get a public publication's details by its slug. Use for \"Show the Paragraph publication with slug 'example'\".","description":"Get a public publication's details by its slug. Use for \"Show the Paragraph publication with slug 'example'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"slug":{"description":"Publication slug, for example 'example'.","maxLength":200,"title":"Slug","type":"string"}},"required":["slug"],"title":"get_publication_by_slugArguments","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_my_posts":{"post":{"operationId":"list_my_posts","summary":"List posts of your publication filtered by status (published, draft, scheduled or archived), newest first, without bodie","description":"List posts of your publication filtered by status (published, draft, scheduled or archived), newest first, without bodies unless asked. Use for \"What are my latest Paragraph drafts\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["published","draft","scheduled","archived"],"type":"string"},{"type":"null"}],"default":"published","description":"Post status: published, draft, scheduled or archived.","title":"Status"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many items to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: pagination.cursor from the previous answer. Leave out for the first page.","title":"Cursor"},"include_content":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include the full post body (markdown, json, HTML); answers get large.","title":"Include Content"}},"title":"list_my_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/list_publication_posts":{"post":{"operationId":"list_publication_posts","summary":"List the published posts of any publication by its id. Use for \"What has this Paragraph publication published\".","description":"List the published posts of any publication by its id. Use for \"What has this Paragraph publication published\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"publication_id":{"description":"Publication id.","maxLength":200,"title":"Publication Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many items to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: pagination.cursor from the previous answer. Leave out for the first page.","title":"Cursor"},"include_content":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include the full post body (markdown, json, HTML); answers get large.","title":"Include Content"}},"required":["publication_id"],"title":"list_publication_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 by id (metadata; body only with include_content). Use for \"Show this Paragraph post\".","description":"Get one post by id (metadata; body only with include_content). Use for \"Show this Paragraph post\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"post_id":{"description":"Post id.","maxLength":200,"title":"Post Id","type":"string"},"include_content":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include the full post body (markdown, json, HTML); answers get large.","title":"Include Content"}},"required":["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/list_posts_feed":{"post":{"operationId":"list_posts_feed","summary":"List the platform-wide curated feed of recent Paragraph posts. Use for \"What is new on Paragraph\".","description":"List the platform-wide curated feed of recent Paragraph posts. Use for \"What is new on Paragraph\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":60,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 60).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: pagination.cursor from the previous answer. Leave out for the first page.","title":"Cursor"},"include_content":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include the full post body (markdown, json, HTML); answers get large.","title":"Include Content"}},"title":"list_posts_feedArguments","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_by_tag":{"post":{"operationId":"list_posts_by_tag","summary":"List published posts that carry one tag, newest first. Use for \"Find Paragraph posts tagged ethereum\".","description":"List published posts that carry one tag, newest first. Use for \"Find Paragraph posts tagged ethereum\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tag":{"description":"Tag name, for example 'ethereum'.","maxLength":200,"title":"Tag","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many items to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: pagination.cursor from the previous answer. Leave out for the first page.","title":"Cursor"},"include_content":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include the full post body (markdown, json, HTML); answers get large.","title":"Include Content"}},"required":["tag"],"title":"list_posts_by_tagArguments","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_posts":{"post":{"operationId":"search_posts","summary":"Search posts across all Paragraph publications by text, optionally inside one publication. Use for \"Search Paragraph pos","description":"Search posts across all Paragraph publications by text, optionally inside one publication. Use for \"Search Paragraph posts about onboarding\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Search text.","maxLength":200,"title":"Q","type":"string"},"blog_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Limit the search to this publication id.","title":"Blog Id"}},"required":["q"],"title":"search_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/search_publications":{"post":{"operationId":"search_publications","summary":"Search Paragraph publications by name, slug or description. Use for \"Find Paragraph newsletters about climate\".","description":"Search Paragraph publications by name, slug or description. Use for \"Find Paragraph newsletters about climate\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Search text.","maxLength":200,"title":"Q","type":"string"}},"required":["q"],"title":"search_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/list_drafted_content":{"post":{"operationId":"list_drafted_content","summary":"List short-form content pieces (X posts, LinkedIn posts, newsletters, X articles) in your library with status and schedu","description":"List short-form content pieces (X posts, LinkedIn posts, newsletters, X articles) in your library with status and schedule flag. Use for \"What social drafts are waiting in my Paragraph library\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"kind":{"anyOf":[{"enum":["tweet","linkedin","newsletter","x_article"],"type":"string"},{"type":"null"}],"default":null,"description":"Content kind: tweet, linkedin, newsletter or x_article.","title":"Kind"},"status":{"anyOf":[{"enum":["all","draft","published","archived"],"type":"string"},{"type":"null"}],"default":"all","description":"Lifecycle: all, draft, published or archived.","title":"Status"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 50).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: pagination.cursor from the previous answer. Leave out for the first page.","title":"Cursor"}},"title":"list_drafted_contentArguments","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}}}}