{"openapi":"3.1.0","info":{"title":"HubSpot (BYOK) API","version":"0.1.0","description":"HubSpot (BYOK) lets an AI assistant read your own HubSpot data through the HubSpot API with a key you supply (private app access token (give the app read scopes only, such as crm.objects.contacts.read)). Read-only: 9 tools (list_contacts, get_contact, search_contacts, list_companies, get_company, search_companies, list_deals, get_deal, search_deals). The BYOK key travels with each request, is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-hubspot.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-hubspot/docs"},"termsOfService":"https://connectorbay.com/byok-hubspot/terms"},"servers":[{"url":"https://byok-hubspot.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-hubspot/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_contacts":{"post":{"operationId":"list_contacts","summary":"List CRM contacts (default properties: email, first and last name, created and last modified date) with a cursor for pag","description":"List CRM contacts (default properties: email, first and last name, created and last modified date) with a cursor for paging; ask for more properties by name. Use for \"Show my latest HubSpot contacts\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many records to return (1 to 100).","title":"Limit"},"after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: paging.next.after from the previous answer. Leave out for the first page.","title":"After"},"properties":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated property names to return in addition to the defaults, for example 'phone,company,lifecyclestage'. Leave out for the default set.","title":"Properties"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to list archived records instead of active ones.","title":"Archived"}},"title":"list_contactsArguments","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_contact":{"post":{"operationId":"get_contact","summary":"Get one CRM contact by record id, or by email address when id_property is set to email, with the properties requested. U","description":"Get one CRM contact by record id, or by email address when id_property is set to email, with the properties requested. Use for \"Look up the HubSpot contact jane@example.com\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"contact_id":{"description":"The contact's record id, or its email address when id_property is 'email'.","maxLength":254,"title":"Contact Id","type":"string"},"id_property":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Name of a unique property that contact_id refers to, for example 'email'. Leave out to use the record id.","title":"Id Property"},"properties":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated property names to return in addition to the defaults, for example 'phone,company,lifecyclestage'. Leave out for the default set.","title":"Properties"}},"required":["contact_id"],"title":"get_contactArguments","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_contacts":{"post":{"operationId":"search_contacts","summary":"Search CRM contacts by text across default searchable properties such as name, email and phone, 200 results per page at ","description":"Search CRM contacts by text across default searchable properties such as name, email and phone, 200 results per page at most (the search returns at most 10000 results in total). Use for \"Find HubSpot contacts named Jane\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Text to search for in the object's default searchable properties, up to 3000 characters. Text such as 'jane@example.com' or 'Jane Doe'.","maxLength":3000,"title":"Query","type":"string"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 200).","title":"Limit"},"after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: paging.next.after from the previous answer. Leave out for the first page.","title":"After"}},"required":["query"],"title":"search_contactsArguments","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_companies":{"post":{"operationId":"list_companies","summary":"List CRM companies with a cursor for paging; ask for properties such as name, domain, industry and number of employees b","description":"List CRM companies with a cursor for paging; ask for properties such as name, domain, industry and number of employees by name. Use for \"Show my HubSpot companies\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many records to return (1 to 100).","title":"Limit"},"after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: paging.next.after from the previous answer. Leave out for the first page.","title":"After"},"properties":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated property names to return in addition to the defaults, for example 'name,domain,industry,numberofemployees'. Leave out for the default set.","title":"Properties"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to list archived records instead of active ones.","title":"Archived"}},"title":"list_companiesArguments","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_company":{"post":{"operationId":"get_company","summary":"Get one CRM company by record id with the properties requested. Use for \"Show the details of one HubSpot company\".","description":"Get one CRM company by record id with the properties requested. Use for \"Show the details of one HubSpot company\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"The company's record id, for example '5251' (the id field returned by list_companies).","maxLength":200,"title":"Company Id","type":"string"},"properties":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated property names to return in addition to the defaults, for example 'name,domain,industry,city'. Leave out for the default set.","title":"Properties"}},"required":["company_id"],"title":"get_companyArguments","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_companies":{"post":{"operationId":"search_companies","summary":"Search CRM companies by text across default searchable properties such as name, domain, website and phone, 200 results p","description":"Search CRM companies by text across default searchable properties such as name, domain, website and phone, 200 results per page at most. Use for \"Find the HubSpot company acme.example\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Text to search for in the object's default searchable properties, up to 3000 characters. Text such as 'acme.example' or 'Acme'.","maxLength":3000,"title":"Query","type":"string"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 200).","title":"Limit"},"after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: paging.next.after from the previous answer. Leave out for the first page.","title":"After"}},"required":["query"],"title":"search_companiesArguments","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_deals":{"post":{"operationId":"list_deals","summary":"List CRM deals with a cursor for paging; ask for properties such as dealname, amount, dealstage, pipeline, closedate and","description":"List CRM deals with a cursor for paging; ask for properties such as dealname, amount, dealstage, pipeline, closedate and hubspot_owner_id by name (stage and pipeline appear as internal ids). Use for \"Show my HubSpot deals with amount and stage\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many records to return (1 to 100).","title":"Limit"},"after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: paging.next.after from the previous answer. Leave out for the first page.","title":"After"},"properties":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated property names to return in addition to the defaults, for example 'dealname,amount,dealstage,pipeline,closedate'. Leave out for the default set.","title":"Properties"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to list archived records instead of active ones.","title":"Archived"}},"title":"list_dealsArguments","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_deal":{"post":{"operationId":"get_deal","summary":"Get one CRM deal by record id with the properties requested (stage and pipeline appear as internal ids). Use for \"Show t","description":"Get one CRM deal by record id with the properties requested (stage and pipeline appear as internal ids). Use for \"Show the details of one HubSpot deal\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"deal_id":{"description":"The deal's record id, for example '5251' (the id field returned by list_deals).","maxLength":200,"title":"Deal Id","type":"string"},"properties":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated property names to return in addition to the defaults, for example 'dealname,amount,dealstage,pipeline,closedate'. Leave out for the default set.","title":"Properties"}},"required":["deal_id"],"title":"get_dealArguments","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_deals":{"post":{"operationId":"search_deals","summary":"Search CRM deals by text across default searchable properties such as deal name, pipeline, stage and description, 200 re","description":"Search CRM deals by text across default searchable properties such as deal name, pipeline, stage and description, 200 results per page at most. Use for \"Find HubSpot deals about renewal\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Text to search for in the object's default searchable properties, up to 3000 characters. Text such as 'renewal'.","maxLength":3000,"title":"Query","type":"string"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 200).","title":"Limit"},"after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: paging.next.after from the previous answer. Leave out for the first page.","title":"After"}},"required":["query"],"title":"search_dealsArguments","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}}}}