{"openapi":"3.1.0","info":{"title":"HeyReach (BYOK) API","version":"0.1.0","description":"HeyReach (BYOK) lets an AI assistant read your own HeyReach data through the HeyReach API with a key you supply (HeyReach API key). Read-only: 9 tools (check_api_key, list_linkedin_accounts, get_linkedin_account, list_campaigns, get_campaign, list_lead_lists, get_lead_list, get_overall_stats, list_webhooks). The BYOK key travels with each request, is used for that one call only and is never...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-heyreach.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-heyreach/docs"},"termsOfService":"https://connectorbay.com/byok-heyreach/terms"},"servers":[{"url":"https://byok-heyreach.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-heyreach/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/check_api_key":{"post":{"operationId":"check_api_key","summary":"Check that the HeyReach API key works. Returns an empty success answer when the key is valid. Use for \"Is my HeyReach AP","description":"Check that the HeyReach API key works. Returns an empty success answer when the key is valid. Use for \"Is my HeyReach API key valid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"check_api_keyArguments","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_linkedin_accounts":{"post":{"operationId":"list_linkedin_accounts","summary":"List the connected LinkedIn sender accounts with name, profile URL, active and valid-session flags, active campaign coun","description":"List the connected LinkedIn sender accounts with name, profile URL, active and valid-session flags, active campaign count and today's action limits. Page size is at most 100. Use for \"Which LinkedIn accounts are connected in HeyReach and are they active\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip (for paging, default 0).","title":"Offset"},"keyword":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":"","description":"Optional text to filter by name (leave empty for all).","title":"Keyword"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records to return (1 to 100, default 25).","title":"Limit"}},"title":"list_linkedin_accountsArguments","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_linkedin_account":{"post":{"operationId":"get_linkedin_account","summary":"Get one connected LinkedIn sender account by ID with its status flags, cooldowns and action limits. Use for \"Show HeyRea","description":"Get one connected LinkedIn sender account by ID with its status flags, cooldowns and action limits. Use for \"Show HeyReach LinkedIn account 1234\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_id":{"description":"Numeric ID of the LinkedIn account (from list_linkedin_accounts).","minimum":1,"title":"Account Id","type":"integer"}},"required":["account_id"],"title":"get_linkedin_accountArguments","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_campaigns":{"post":{"operationId":"list_campaigns","summary":"List outreach campaigns with name, status, creation time, linked lead list, sender account IDs and progress counts (tota","description":"List outreach campaigns with name, status, creation time, linked lead list, sender account IDs and progress counts (total, in progress, pending, finished, failed). Page size is at most 100. Use for \"Which HeyReach campaigns are running and how far along are they\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip (for paging, default 0).","title":"Offset"},"keyword":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":"","description":"Optional text to filter by name (leave empty for all).","title":"Keyword"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records to return (1 to 100, default 25).","title":"Limit"}},"title":"list_campaignsArguments","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_campaign":{"post":{"operationId":"get_campaign","summary":"Get one campaign by ID with status, linked lead list, sender accounts, exclusion settings and progress counts. Use for \"","description":"Get one campaign by ID with status, linked lead list, sender accounts, exclusion settings and progress counts. Use for \"How is HeyReach campaign 321 doing\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"campaign_id":{"description":"Numeric campaign ID (from list_campaigns).","minimum":1,"title":"Campaign Id","type":"integer"}},"required":["campaign_id"],"title":"get_campaignArguments","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_lead_lists":{"post":{"operationId":"list_lead_lists","summary":"List lead and company lists with name, item count, creation time and the campaigns using them. Page size is at most 100.","description":"List lead and company lists with name, item count, creation time and the campaigns using them. Page size is at most 100. Use for \"What lead lists do we have in HeyReach and how big are they\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"list_type":{"description":"List kind: USER_LIST for leads or COMPANY_LIST for companies.","enum":["USER_LIST","COMPANY_LIST"],"title":"List Type","type":"string"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip (for paging, default 0).","title":"Offset"},"keyword":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":"","description":"Optional text to filter by name (leave empty for all).","title":"Keyword"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records to return (1 to 100, default 25).","title":"Limit"}},"required":["list_type"],"title":"list_lead_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/get_lead_list":{"post":{"operationId":"get_lead_list","summary":"Get one lead or company list by ID with its item count, creation time and campaigns. Use for \"How many leads are in HeyR","description":"Get one lead or company list by ID with its item count, creation time and campaigns. Use for \"How many leads are in HeyReach list 55\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"list_id":{"description":"Numeric list ID (from list_lead_lists).","minimum":1,"title":"List Id","type":"integer"}},"required":["list_id"],"title":"get_lead_listArguments","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_overall_stats":{"post":{"operationId":"get_overall_stats","summary":"Get outreach totals for a date range: profile views, post likes, follows, messages sent and replied, connection requests","description":"Get outreach totals for a date range: profile views, post likes, follows, messages sent and replied, connection requests sent and accepted, and the reply and acceptance rates. All senders and campaigns are included. Use for \"What were our HeyReach connection and reply rates in October 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"description":"Start of the range as an ISO 8601 time, for example 2026-10-01T00:00:00.000Z.","maxLength":40,"title":"Start Date","type":"string"},"end_date":{"description":"End of the range as an ISO 8601 time, for example 2026-10-17T23:59:59.999Z.","maxLength":40,"title":"End Date","type":"string"}},"required":["start_date","end_date"],"title":"get_overall_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_webhooks":{"post":{"operationId":"list_webhooks","summary":"List the webhooks configured in HeyReach with name, target URL, event type, campaign IDs and active flag. Custom header ","description":"List the webhooks configured in HeyReach with name, target URL, event type, campaign IDs and active flag. Custom header values are not returned. Use for \"Which HeyReach webhooks are active\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip (for paging, default 0).","title":"Offset"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records to return (1 to 100, default 25).","title":"Limit"},"include_headers":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Leave false: custom header values are never shown in this tool.","title":"Include Headers"}},"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}}}}