{"openapi":"3.1.0","info":{"title":"HubSpot CRM Lists (BYOK) API","version":"0.1.0","description":"HubSpot CRM Lists (BYOK) lets an AI assistant read your own HubSpot CRM Lists data through the HubSpot CRM Lists API with a key you supply (HubSpot private app access token (scope: crm.lists.read)). Read-only: 5 tools (search_lists, get_list, get_list_by_name, list_list_folders, get_list_size_history). The BYOK key travels with each request, is used for that one call only and is never stored,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-hubspot-crm-lists.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-hubspot-crm-lists/docs"},"termsOfService":"https://connectorbay.com/byok-hubspot-crm-lists/terms"},"servers":[{"url":"https://byok-hubspot-crm-lists.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-hubspot-crm-lists/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/search_lists":{"post":{"operationId":"search_lists","summary":"Search the account's lists (segments) by name text and optionally object type, with list id, type, processing status and","description":"Search the account's lists (segments) by name text and optionally object type, with list id, type, processing status and dates. No members are returned. Use for \"Which HubSpot lists have 'newsletter' in the name\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Text to look for in list names. Use an empty string to list all.","maxLength":200,"title":"Query","type":"string"},"object_type_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Object type id: 0-1 for contacts, 0-2 for companies, 0-3 for deals, or a custom object type id such as 2-1001. Leave out for all object types.","title":"Object Type Id"},"count":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many lists to return (1 to 500).","title":"Count"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of lists to skip, for paging. Start at 0.","title":"Offset"}},"required":["query"],"title":"search_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_list":{"post":{"operationId":"get_list","summary":"Get one list (segment) by id: name, object type, processing type and status, size, version, creator and dates. Filters a","description":"Get one list (segment) by id: name, object type, processing type and status, size, version, creator and dates. Filters are not included. Use for \"How big is HubSpot list 42 and when was it updated\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"list_id":{"description":"Id of the list (a numeric string such as '42').","maxLength":200,"title":"List Id","type":"string"}},"required":["list_id"],"title":"get_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_list_by_name":{"post":{"operationId":"get_list_by_name","summary":"Look up a list (segment) by object type and exact name: id, type, processing status, size and dates. Use for \"Find the H","description":"Look up a list (segment) by object type and exact name: id, type, processing status, size and dates. Use for \"Find the HubSpot contact list called 'Newsletter subscribers'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"object_type_id":{"description":"Object type id: 0-1 for contacts, 0-2 for companies, 0-3 for deals, or a custom object type id such as 2-1001.","maxLength":200,"title":"Object Type Id","type":"string"},"list_name":{"description":"Exact list name, for example 'Newsletter subscribers'.","maxLength":200,"title":"List Name","type":"string"}},"required":["object_type_id","list_name"],"title":"get_list_by_nameArguments","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_list_folders":{"post":{"operationId":"list_list_folders","summary":"List a folder of the lists tree: its name, child folders and the lists it holds (ids and names). Folder 0 is the root. U","description":"List a folder of the lists tree: its name, child folders and the lists it holds (ids and names). Folder 0 is the root. Use for \"How are our HubSpot lists organised into folders\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"folder_id":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":"0","description":"Id of the folder to open; 0 is the top level.","title":"Folder Id"}},"title":"list_list_foldersArguments","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_list_size_history":{"post":{"operationId":"get_list_size_history","summary":"Get how many members a list had over time within a date range, as size and timestamp points. Counts only. Use for \"How h","description":"Get how many members a list had over time within a date range, as size and timestamp points. Counts only. Use for \"How has the size of HubSpot list 42 changed this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"list_id":{"description":"Id of the list (a numeric string such as '42').","maxLength":200,"title":"List Id","type":"string"},"start_date":{"description":"Start of the range as an ISO 8601 time, for example 2026-10-01T00:00:00Z.","maxLength":200,"title":"Start Date","type":"string"},"end_date":{"description":"End of the range as an ISO 8601 time, for example 2026-10-19T00:00:00Z.","maxLength":200,"title":"End Date","type":"string"}},"required":["list_id","start_date","end_date"],"title":"get_list_size_historyArguments","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}}}}