@revfleet/hscli 0.8.12 → 0.9.1

package/docs/INTERNAL-ENDPOINTS.md

@@ -0,0 +1,371 @@
+# HubSpot Internal Endpoints (Full Catalogue)
+
+Every internal (browser-cookie-authenticated) HubSpot endpoint hit across the <client> portal work. Sources: sessions <session-id> (<source portal>→<client> reports/dashboards/workflows), <session-id> + <session-id> + <session-id> (permission sets + property migration), <session-id> + <session-id> (Jun 18 dashboards), <session-id> (Jun 17). Live loop discovery in 15 iterations is in INTERNAL-ENDPOINTS-DISCOVERY.md.
+
+## CSRF Unlock Pattern (Use Everywhere)
+The cookie hubspotapi-csrf + header X-HubSpot-CSRF-hubspotapi unlocks every 401-blocked internal endpoint. This is the key for the adapter layer:
+
+const csrf = document.cookie.split('; ').find(c => c.startsWith('hubspotapi-csrf='))?.split('=')[1];
+const r = await fetch(url, { credentials: 'include', headers: { 'X-HubSpot-CSRF-hubspotapi': csrf } });
+Applies to workflows, permission sets, FLP, brand kits, design manager, payments — everything.
+
+Internal endpoint rules
+
+Live host: https://app.hubspot.com
+Auth: same-origin session cookie (credentials: 'include' from inside a HubSpot tab). Private App tokens are rejected.
+Many endpoints reject simple GETs from the embedded sandbox — execute from the HubSpot tab via the Chrome extension's javascript_tool.
+portalId query param is required on most calls. Source = <sourcePortalId>, live = <portalId>.
+Status: ✅ worked, ⚠️ partial / inconsistent, ❌ 404/401 in this session.
+Dashboards
+Method	Path	Status	Notes
+GET	/api/dashboard/v2/dashboard	✅	List dashboards. ?limit=200&offset=….
+GET	/api/dashboard/v2/dashboard/list	✅	Alt list.
+GET	/api/dashboard/v2/dashboard/search	✅	Search by name/owner.
+GET	/api/dashboard/v2/dashboard/total-count	✅	Quick count.
+GET	/api/dashboard/v2/dashboard/widget-counts	✅	Widget counts per dashboard.
+GET	/api/dashboard/v2/dashboard/all-shareable	✅	Shareable dashboards.
+GET	/api/dashboard/v2/dashboard/{id}	✅	Full dashboard + widgets.
+POST	/api/dashboard/v2/dashboard	✅	Create blank dashboard.
+POST	/api/dashboard/v2/dashboard/clone	✅	Clone (preserves widgets — used to bootstrap empty dashboards).
+POST	/api/dashboard/v2/clone-dashboard	✅	Alt clone path.
+POST	/api/dashboard/v2/dashboard/{id}/clone	✅	Per-dashboard clone.
+POST	/api/dashboard/v2/dashboard/{id}/duplicate	✅	Same as clone.
+PUT	/api/dashboard/v2/dashboard/{id}	⚠️	widgets array silently ignored — use widget endpoints.
+DELETE	/api/dashboard/v2/dashboard/{id}	☠️	Cascade delete: removes every widget report inside.
+GET	/api/dashboard/v2/dashboard/{id}/permission (sg)	✅	Single user permission.
+GET/PUT	/api/dashboard/v2/dashboard/{id}/permissions	✅	Bulk permissions.
+GET	/api/dashboard/v2/dashboard/{id}/permission-config	✅	Permission config (who has access modes).
+GET	/api/dashboard/v2/dashboard/{id}/permission-grants	✅	Explicit grants.
+POST	/api/dashboard/v2/dashboard/{id}/widget/from-report	✅	Attach a single report as widget.
+POST	/api/dashboard/v2/dashboard/{id}/widget/from-reports	⚠️	Bulk attach. No-ops silently on empty dashboards (returns 204) — clone a populated one first.
+POST	/api/dashboard/v2/dashboard/{id}/widget	✅	Generic add widget.
+PUT	/api/dashboard/v2/dashboard/{id}/widgets	⚠️	Bulk update.
+DELETE	/api/dashboard/v2/dashboard/{id}/widget/{wid}	✅	Detach single widget WITHOUT deleting underlying report.
+GET	/api/dashboard/v2/report-list-views	✅	"My reports" / saved-view manager.
+GET	/api/dashboard/v2/report-list-views/pinned	✅	Pinned views.
+GET	/api/dashboard/v2/reports/report-counts	✅	Total report count per view.
+Reports
+Method	Path	Status	Notes
+GET	/api/dashboard/v2/reports	✅	List reports.
+GET	/api/dashboard/v2/reports/list	✅	Alt list.
+GET	/api/dashboard/v2/reports/search	✅	Search reports.
+GET	/api/dashboard/v2/reports/{id}	✅	Report definition + chart config.
+POST	/api/dashboard/v2/reports	✅	Create report.
+PUT	/api/dashboard/v2/reports/{id}	✅	Update report.
+DELETE	/api/dashboard/v2/reports/{id}	✅	Hard delete.
+GET	/api/dashboard/v2/reports/{id}/history	✅	Version history.
+GET	/api/dashboard/v2/reports/{id}/audit	✅	Per-report audit.
+GET	/api/dashboard/v2/reports/permission	✅	Permission probe.
+GET/PUT	/api/dashboard/v2/reports/{id}/permissions	✅	Set perms.
+GET	/api/dashboard/v2/widget / /api/dashboard/v2/widget/{id}	✅	Per-widget access.
+❌	/api/reports-list-app/v1/dashboards	404	Doesn't exist; use /api/dashboard/v2.
+Reporting backend (data resolve)
+Method	Path	Status	Notes
+POST	/api/reporting/v3/dataset/resolve/async	✅	Async dataset resolve for report rendering.
+POST	/api/reporting/v3/journey/{reportId}/resolve/async	✅	Journey reports.
+POST	/api/reporting-migration/v2/reports/migrate	✅	Internal cross-portal report migration.
+POST	/api/reporting-usage-service/v1/ingestion/report	✅	Telemetry only.
+Workflows
+Method	Path	Status	Notes
+GET	/api/automation/v4/flows	✅	List flows. Hard cap limit=100; paginate via after.
+GET	/api/automation/v4/flows/{id}	❌	401 from in-tab JS.
+POST	/api/automation/v4/flows	✅	Create flow.
+PUT/PATCH	/api/automation/v4/flows/{id}	✅	Update.
+DELETE	/api/automation/v4/flows/{id}	✅	Soft delete; recoverable from Deleted view.
+GET	/api/automation/v3/workflows	✅	Legacy v3.
+GET	/api/automation/v3/workflows/{id}	❌	401 in-tab.
+GET	/api/automation/v3/flows	✅	Legacy alias.
+GET	/api/automation/flows/v3/flows/{id}	❌	404.
+GET	/api/workflows-engine/v1/flows/{id}	❌	404.
+GET	/automation-platform/v1/flows/{id}	❌	404.
+Owner discovery workaround: list endpoints omit creator. Add "Created by" column to the workflows UI list and scrape DOM.
+
+Properties
+Method	Path	Status	Notes
+GET	/api/properties/v1/contacts/properties	✅	Oldest v1.
+GET	/api/properties/v2/{object}/properties	✅	Legacy v2 — returns createdUserId reliably even for old properties (v3 sometimes omits it).
+GET	/api/properties/v2/contacts/properties	✅	
+GET	/api/properties/v2/companies/properties	✅	
+GET	/api/properties/v2/deals/properties	✅	
+GET	/properties/v3/object/0-1/properties	✅	v3 surface (typeId-keyed).
+GET	/api/properties/v4/{typeId}	✅	v4 — current internal surface. typeId ∈ 0-1 (contact) / 0-2 (company) / 0-3 (deal) / 0-5 (ticket) / 0-14 (quote) / 0-136 (lead).
+GET	/api/properties/v4/{typeId}/named/{name}	✅	Single property by internal name.
+GET	/api/properties/v4/groups/{typeId}	✅	Property groups.
+GET	/api/properties/v4/groups/{typeId}/properties	✅	Properties within groups.
+GET	/api/properties/v4/recycle/{typeId}	✅	Recycled (soft-deleted) properties.
+GET	/api/properties/v4/properties/combined-count	✅	Counts across all objects.
+GET	/api/properties/v4/properties/{typeId}/custom-limits-and-counts	✅	Custom property quota check.
+GET	/api/property-validation/v1/properties/{objectId}	✅	Validation rules per property.
+GET	/api/property-validation/v1/business-unit-property/{typeId}/property/{name}	✅	BU-scoped validation.
+POST	/api/property-validation/v1/custom-property-validation	✅	Run a validation rule.
+GET	/api/conditional-properties/v2/options/{typeId}/{propertyName}	✅	Conditional option lists (used for cascading picklists).
+GET	/api/property-settings/v1/property-fill-rate/{typeId}/batch/read	✅	Property fill-rate batch read.
+GET	/api/external-options/v3/fetch/...	✅	External-options fetch for dynamic option lists.
+Lists / segments (many overlapping families — none consistent)
+Method	Path	Status	Notes
+GET	/api/lists/v3/lists	✅	New lists API.
+GET	/api/lists/v3/{portal}/lists	✅	Portal-scoped form.
+GET	/api/lists/v3/lists/{id}	✅	Single list.
+GET	/api/lists/v3/{portal}/lists/{id}/segments	✅	Segments inside list.
+POST	/api/lists/v3/lists/search	⚠️	404/405 depending on body shape.
+GET	/api/lists/v2/lists/{id}	✅	Legacy.
+GET	/api/contacts/v1/lists	✅	Oldest contacts-only API.
+GET	/api/contacts/v1/lists/{id}	✅	
+GET	/api/contact-list-management/v1/{portal}/lists/{id}	✅	UI-facing.
+GET	/api/contact-list/v1/lists/{id}	⚠️	Inconsistent.
+GET	/api/contact-lists/v1/{portal}/lists/{id}	⚠️	
+GET	/api/ils-segments/v1/{portal}/segments/{id}	✅	New ILS segment store.
+GET	/api/ils-segments/v1/portals/{portal}/segments/{id}	✅	Alt form.
+GET	/api/ils-segment-store/v1/segments	✅	Bulk store query.
+GET	/api/ils/v1/segments/{id}	⚠️	
+GET	/api/segments-ui/v1/segments/{portal}/{id}	✅	UI-facing.
+GET	/api/segments/v1/segments/{id}	⚠️	
+GET	/api/segments/v3/segments/{id}	⚠️	
+GET	/api/list-segments/v1/{portal}/segments/{id}	⚠️	
+GET	/api/list-segments/v2/{portal}/segments/{id}	⚠️	
+GET	/api/list-segments-public/v1/{portal}/segments/{id}	⚠️	
+GET	/api/lists-search/v1/segments/all/legacy/{portal}	✅	Search all segments.
+❌	/api/contacts-list-app/v1/lists/search	404	
+Practical advice: for list discovery, use the UI under /contacts/{portal}/objectLists/views/all?objectTypeId={0-1|0-2|0-3|0-5} and scrape DOM. APIs are fragmented and inconsistent.
+
+Templates / sales content
+Method	Path	Status	Notes
+GET	/api/templates/v1/templates?portalId={p}&folder={fId}	✅	List templates in folder; returns owner + content.
+POST	/api/templates/v1/templates	✅	Create.
+GET	/api/sales-content/v1/templates	✅	Alt path.
+GET	/api/sales-content/v1/sequences	✅	Sequences via sales-content.
+GET	/api/sales-content-libraries/v2/sales/email-templates	✅	Newer library API.
+Sequences (full body now reachable — corrects prior 404 finding)
+Method	Path	Status	Notes
+POST	/api/salescontentsearch/v2/search?portalId={p}	✅	List endpoint. Body {query:"", limit:100, offset:N}. Returns mixed content; filter contentType === 'SEQUENCE' client-side. Paginate with offset + hasMore.
+GET	/api/sequences/v3/sequences/{sequenceId}	✅	Full sequence body — steps, settings, emailPattern (templateId), taskPattern, sendWindow, unenrollment rules, dependencies. ~3KB per sequence. Requires CSRF.
+GET	/api/sequences/v2/sequences/usage	✅	Usage / quota.
+GET	/api/sequences/v2/enrollments/impacted	✅	Active enrollments.
+GET	/api/sequences/v2/enrollments/health-check	✅	Enrollment health.
+GET	/api/sequences/v3/folders/count	✅	Folder count.
+❌	/api/sequences/v3/sequences (list)	404	List goes via salescontentsearch above.
+See INTERNAL-ENDPOINTS-DISCOVERY.md § Iteration 15 for full sequence response shape + export pipeline.
+
+Playbooks (full body via chirp RPC)
+All playbook surface lives behind com.hubspot.playbooks.rpc.PlaybooksRpc chirp RPCs. URL pattern: POST /api/chirp-frontend-app/v1/gateway/com.hubspot.playbooks.rpc.{ServiceName}/{methodName}?portalId={p} with CSRF header.
+
+Service	Method	Body	Returns
+PlaybooksRpc	listPlaybooks	{}	{playbooks:[…]} with body (Draft.js JSON) + htmlBody (rendered) inline. Single call for full export.
+PlaybooksRpc	getPlaybookCount	{}	{count, limit:5000}
+PlaybooksRpc	getLatestPlaybookVersion	{playbookId}	Latest version body.
+PlaybooksRpc	getPlaybookVersionSummaries	{playbookId}	Version history.
+PlaybookQuestionsRpc	getLatestQuestionsByPlaybook	{playbookId}	All questions with answerType + quickAnswers. Linked from htmlBody via <question qid="…"> tags.
+Chirp response wrapper: {type:"data", data:{…}, correlationId} — real payload is in .data.
+
+See INTERNAL-ENDPOINTS-DISCOVERY.md § Iteration 15 for full playbook shape + export pipeline.
+
+Marketing email (all failed in-tab during this session)
+Path	Status
+/api/marketing-emails/v1/emails	❌ 404
+/api/email-publisher/v1/emails	❌ 404
+/api/cosemail/v1/emails	❌ 404
+/api/email-engine/v3/emails	❌ 404
+/api/email-management/v1/emails	❌ 404
+/api/email-management/v3/email	❌ 404
+/api/email-management/v3/email-stats	❌ 404
+/api/email/v1/emails	❌ 404
+/api/email/v1/emails/list	❌ 404
+/cmscontent-api/v3/email/	❌ 404
+/cmscontent/v3/email/	❌ 404
+Practical: navigate /email/{portal}/manage/state/all?businessUnitId=… and scrape. Marketing email pages are scoped per businessUnitId.
+
+Audit log (very useful for creator discovery)
+Method	Path	Status	Notes
+GET	/api/audit-log/v1/audit-entries?objectType={t}&objectId={id}	✅	Per-object history; objectType ∈ LIST_AGGREGATION, DASHBOARD, REPORT, WORKFLOW.
+GET	/api/audit-log/v1/portal/{portal}	✅	Portal-wide.
+GET	/api/audit-logs/v1/portal/{portal}	✅	Plural alias.
+GET	/api/audit-logs/v1/portal/{portal}/logs	✅	Detail.
+GET	/api/security-audit-log/v1/portal/{portal}	✅	Security-only audit.
+GET	/api/security-logs/v1/portal/{portal}/logs	✅	
+GET	/api/v1/security/audit-logs	✅	Older path.
+GET	/api/settings-ui/v1/audit-logs/{portal}	✅	Settings UI form.
+Source-of-truth fallback when other endpoints lack creator. UI = /settings/{portal}/audits or /account-and-billing/{portal}/account-defaults/audit-logs.
+
+Users, teams, permission sets (this is the permission-set surface)
+Method	Path	Status	Notes
+GET	/api/app-users/v1/users	✅	List portal users.
+GET	/api/app-users/v1/users/{userId}	✅	Single user with role + permission-set assignment.
+POST	/api/app-users/v1/users/partial/batch	✅	Batch read users with partial fields.
+GET	/api/app-users/v1/teams	✅	Teams list.
+GET	/api/app-users/v1/permission-sets	✅	List all permission sets.
+GET	/api/app-users/v1/permission-sets/{id}	✅	Single permission set + capability flags.
+PATCH/PUT	/api/app-users/v1/permission-sets/{id}	✅	Edit permission set (used for migrating capabilities).
+POST	/api/chirp-frontend-app/v1/gateway/com.hubspot.appusers.rpc.PermissionSetAssignmentsRpc/assignUserToPermissionSets	✅	Assign one or more permission sets to users. Body: `{ "assignments": [{ "userId": "...", "permissionSetIds": ["..."] }] }`.
+GET	/api/integrators/v1/{portal}/info/users	✅	Full user list with userId, email, name, deactivated flag — source for ID→name mapping.
+GET	/api/users-and-teams/v1/current-user	✅	Current session user.
+GET	/api/login-verify/user-info	✅	Login state.
+Field-level + report permissions
+Method	Path	Status	Notes
+GET	/api/crm-permissions/v1/field-level-permissions/allowlistings	✅	Global allowlist.
+GET	/api/crm-permissions/v1/field-level-permissions/allowlistings/{typeId}	✅	Per-object allowlist.
+GET	/api/crm-permissions/v1/field-level-permissions/allowlistings/{typeId}/{property}	✅	Per-property allowlist — who can see/edit a custom field.
+POST	/api/crm-permissions/v1/field-level-permissions/allowlistings/access-state/multi-get	✅	Bulk access-state check.
+POST	/api/crm-permissions/v1/field-level-permissions/allowlistings/object	✅	Object-scoped multi-get.
+GET	/api/crm-permissions/v1/field-level-permissions/blocklist/including-global	✅	Blocklist (with globals).
+GET	/api/permissions-skynet/v1/scopes/app/field-level-permissions-bypass/user-ids	✅	Users who bypass FLP.
+GET	/api/reports-permissions/v1/permissions/report/{reportId}	✅	Per-report permissions.
+Chirp gateway (RPC calls)
+POST /api/chirp-frontend-app/v1/gateway/{ServiceName}/{Method} — body is the RPC payload. Services observed across sessions:
+
+com.hubspot.ai.access.controls.rpc.AiAccessControlsChirpService/getAccessControls
+com.hubspot.app.user.audits.service.rpc.* — user audit RPCs (permission-set assignment history)
+com.hubspot.blueprint.customer.object.type.rpc.* — custom object schema RPCs
+com.hubspot.crm.index.views.api.rpc.* — CRM index / sales views
+com.hubspot.custom.enrichment.rpc.client.* — custom enrichment
+com.hubspot.customassistants.rpc.CustomAssistantsService/listCustomAssistants
+com.hubspot.dashboard.rpc.v1.* — dashboard RPCs
+com.hubspot.nav.config.rpc.PersonalisedNavService/getPersonalisedNav
+com.hubspot.nudge.manager.rpc.NudgeManagerRpc/getNudges
+com.hubspot.onboarding.tours.rpc.ToursRpc/getTour
+com.hubspot.presence.rpc.PresenceRpcService/updatePresence
+com.hubspot.product.updates.feedback.rpc.nudge.allowlist.* — nudge allowlists
+Slow variant: POST /api/chirp-frontend-app-slow/v1/gateway/{ServiceName}/{Method} — used for heavy RPCs like com.hubspot.reporting.api.metadata.rpc.ReportingApiMetadataRpc/getPropertyMetadata.
+
+Schemas / object types
+Method	Path	Status	Notes
+GET	/crm/v3/schemas	✅	All object schemas (standard + custom).
+GET	/api/crm-object-schemas/v3/schemas	✅	Internal alias of above.
+GET	/api/object-types/v1/portal/{portal}	✅	Portal object types.
+GET	/api/data-model/v3/object-types	✅	Data-model object types.
+GET	/api/schemas-metadata/v1/portal-metadata	✅	Portal-wide schema metadata.
+GET	/api/schemas-metadata/v1/portal-metadata/type/{type}	✅	Per-type metadata.
+GET	/api/schemas-metadata/v1/portal-metadata/resource/{resource}	✅	Per-resource metadata.
+GET	/api/schemas-metadata/v1/portal-metadata/resources	✅	All resources.
+GET	/api/framework-builder/v1/read/metadata/property/{typeId}/{aspect}	✅	Framework-builder metadata (e.g. crm, gibberishdetectionmetadata, property).
+GET	/api/framework-builder/v1/read/metadata/types/crm	✅	All CRM types.
+CRM (objects, pipelines, properties, associations)
+Method	Path	Status	Notes
+GET/POST	/crm/v3/objects/{type}	✅	List/create — types: contacts, companies, deals, tickets, leads, tasks, calls, emails, meetings, notes.
+GET	/crm/v3/properties/{type}	✅	Standard property list.
+GET	/crm/v3/properties/{type}/groups	✅	Property groups.
+GET	/crm/v3/pipelines/{type}	✅	Pipelines (deals, tickets, leads).
+GET	/crm/v4/associations/{from}/{to}/labels	✅	Association labels — used to copy custom assoc labels across portals.
+GET	/crm/v3/lists/{id}	✅	Single list (see also Lists section).
+Sales views (CRM index)
+Method	Path	Status	Notes
+GET	/api/sales/v4/views/{typeId}	✅	Current sales views API.
+GET	/api/sales/v4/views/{typeId}/all	✅	All views.
+GET	/api/sales/v4/views/{typeId}/all/with-visualization-settings	✅	Includes column/sort config.
+GET	/api/sales/v4/views/{typeId}/list	✅	Saved list views.
+GET	/api/sales/v4/views/{typeId}/pinned/view	✅	Pinned views.
+GET	/api/sales/v4/views/{typeId}/search	✅	Search views.
+GET	/api/sales/v4/views/default-view/{typeId}/with-visualization-settings	✅	Default view with viz.
+GET	/api/sales-views/v3/sales-views/{typeId}	✅	v3 legacy.
+GET	/api/sales-views/v2/sales-views/{typeId}	✅	v2 legacy.
+GET	/api/sales-views/v2/sales-views/{typeId}/list	✅	
+GET	/api/sales-views/v2/sales-views/list/{typeId}/default	✅	Default v2.
+GET	/api/sales-views/v2/crm-search/empty-state-redirect/{typeId}	✅	UI redirect helper.
+GET	/api/sales-views/v2/crm-search/limit-check/{typeId}	✅	Limit check.
+GET	/api/sales-views-api/v1/sales-views/{typeId}	✅	Even older v1.
+GET	/api/views-meta/v1/views/{typeId}	✅	Views metadata.
+GET	/api/views-metadata/v1/{typeId}	✅	Alt form.
+GET	/api/views-store/v1/views	✅	Views store.
+Owners
+Method	Path	Status	Notes
+GET	/api/owners/v2/owners	✅	Owner list.
+GET	/api/owners-aether-search/v1/owners-search	✅	Owner search (typeahead UI).
+GET	/crm/v3/owners	✅	Public surface (same data).
+Branding / business units / multi-brand
+Method	Path	Status	Notes
+GET	/api/business-units/v1/business-units	✅	List BUs.
+GET	/business-units/v1/business-units	✅	Same without /api.
+GET	/api/multi-brand/v1/brands	✅	Multi-brand list.
+GET	/api/branding/v1/brand-kit/business-unit/{buId}	✅	Brand kit per BU.
+GET	/api/branding/v1/brand-voice/by-bu-id/{buId}	✅	Brand voice.
+GET	/api/branding/v1/colors/brand-kit	✅	Brand colors.
+GET	/api/branding/v1/favicons/brand-kit	✅	Favicons.
+GET	/api/branding/v1/font-meta	✅	Font metadata.
+GET	/api/branding/v1/fonts-with-variants	✅	Fonts + variants.
+GET	/api/branding/v1/logos/brand-kit	✅	Logos.
+Reporting discovery / templates
+Method	Path	Status	Notes
+GET	/api/reporting-discovery/v1/report-template	✅	List report templates.
+GET	/api/reporting-discovery/v1/report-template/paged	✅	Paged.
+GET	/api/reporting-discovery/v1/report-template/template-key/{slug}	✅	Templates like sales-analytics.team-activity-timeline, sales-manager-dashboard.activity, sales.team, team-activity.
+GET	/api/reporting-frontend/v1/reports/get-portal-reports	✅	All portal reports list.
+GET	/api/reporting-frontend/v1/reports/...	✅	Frontend metadata.
+Account / private apps
+Method	Path	Status	Notes
+GET	/account-info/v3/details	✅	Portal details (tier, name, etc.).
+GET	/account-info/v3/activity/{portal}	✅	Activity summary.
+GET	/account-info/v3/private-apps	✅	Private apps + their scopes.
+GET	/api/audit-log/v3/audit	✅	v3 audit log.
+GET	/api/audit-logs/v3/logs	✅	v3 logs alias.
+GET	/audit-log/v3/audit	✅	Without /api prefix.
+GET	/api/security-audit-logs/v1/audit-logs	✅	Security audit.
+GET	/api/security-center/v1/account-events	✅	Account events feed.
+GET	/api/security-monitoring/v2/security-monitoring/account/{portal}	✅	Security monitoring.
+GET	/api/crm-usages/v2/usages/	✅	CRM usage telemetry.
+Forms / marketing
+Method	Path	Status	Notes
+GET	/forms/v2/forms	✅	Legacy forms.
+GET	/marketing/v3/forms	✅	Current forms API.
+GET	/marketing/v3/emails	⚠️	Marketing email list (limited from in-tab).
+GET	/conversations/v3/snippets	✅	Snippets via conversations.
+Misc (UI metadata / feature flags / telemetry)
+Path	Use
+/api/cartographer/v1/rhumb	Page-load tracking.
+/api/cartographer/v1/performance	RUM.
+/api/firealarm/v4/alarm/{feature}/{portal}	UI feature flags. Observed: TemplatesUI, segments-ui, settings-ui-audits, settings-ui-users.
+/api/growth-modals/v1/banner/all	All growth banners.
+/api/growth-modals/v1/modals/has-modals	Modal presence check.
+/api/navconfig/v2/alerts	Nav alert badges.
+/api/navconfig/v5/navconfig	Nav config.
+/api/notification/preferences/v1/generic-user-settings	User notif prefs.
+/api/nudge/tracking/v1/nudge-event	Tracking.
+/api/persistent-notifications/v1/notifications	Banner notifs.
+/api/trials/v1/hub-trials/app/active	Hub trial state.
+/api/commenting/v3/comments	UI commenting.
+/api/usage-logging/v1/log/hublytics-multi/no-auth	Telemetry.
+/api/usage-logging/v1/log/session-replay	Telemetry.
+/api/calling-orchestration/v1/settings/user	Calling UI.
+/api/js/store/...	Static JS bundles.
+/calling-cross-tab-embed/shared-worker.js	Calling shared worker.
+UI navigation URLs (deep links — useful for scraping)
+URL pattern	Page
+/reports-dashboard/{portal}/view/{dashId}	Dashboard view.
+/reports-list/{portal}/{reportId}	Single report.
+/reports-list/{portal}/views/all	All reports/dashboards landing.
+/reports-list/{portal}/views/all/list/reports?search={q}	Reports search view.
+/reports-list/{portal}/views/all/list/dashboards?search={q}	Dashboards search (falls back to All Reports unless drilled in via sidebar).
+/reports-list/{portal}/dashboards/views/-4	Dashboards-only landing.
+/workflows/{portal}/view/default	Workflows list.
+/workflows/{portal}/platform/flow/{id}/edit	Workflow editor.
+`/contacts/{portal}/objectLists/views/all?objectTypeId={0-1	0-2
+/contacts/{portal}/objectLists/{id}/filters	List filters.
+/contacts/{portal}/objectLists/{id}/activity/audit	Per-list audit log.
+/templates/{portal}/?folder={folderId}	Templates in a folder.
+/templates/{portal}/edit/{templateId}	Template editor.
+/email/{portal}/manage/state/all?businessUnitId={buId}	Marketing email manager.
+/email/{portal}/details/{emailId}	Email detail.
+/sequences/{portal}/?q={query}	Sequences search.
+/settings/{portal}/audits	Audit log UI.
+/settings/{portal}/security-and-privacy/login-history	Login history.
+/settings/{portal}/security/login-settings	Login security.
+/account-and-billing/{portal}/account-defaults/audit-logs	Account-wide audit logs.
+/notifications/{portal}/banners	Banner notifications.
+/property-settings/{portal}/properties	Property settings UI.
+Gotchas (recap)
+Same-origin only — these endpoints reject calls from the embedded sandbox. Run via mcp__Claude_in_Chrome__javascript_tool inside the HubSpot tab.
+DELETE /api/dashboard/v2/dashboard/{id} cascades to widget reports. See feedback_hubspot_dashboard_delete_cascade.
+POST widget/from-reports no-ops on empty dashboards — clone a populated dashboard first.
+PUT /api/dashboard/v2/dashboard/{id} ignores widgets — use widget endpoints.
+/api/automation/v4/flows caps limit=100 — paginate via after.
+List/segment API surface is fragmented — many overlapping paths, inconsistent behavior. Prefer UI scrape.
+Marketing email + sequences APIs frequently 404 from in-tab — use UI scrape.
+/api/properties/v2/{obj}/properties is more reliable than v3 for createdUserId on old properties.
+Read-only rule on source <sourcePortalId> was lifted (memory: <source-readonly-policy>) — but ALWAYS confirm scope before bulk writes on live <portalId>.
+Session sources
+Session	Date	Topic	New endpoints contributed
+<session-id>	Jun 18-19	<source portal>→<client> reports/dashboards/workflows migration	dashboard v2, reports v2, workflows v4, ils-segments, audit-log v1
+<session-id>	Jun 18	Permission sets + property migration (biggest)	app-users/v1/permission-sets, crm-permissions/v1/field-level-permissions, properties/v4, sales/v4/views, schemas-metadata, branding, framework-builder
+<session-id>	Jun 2	Permission-set work continuation	audit-log v3, security-monitoring, settings-ui-users
+<session-id>	May 27	Permission-set discovery	object-types/v1, crm-object-schemas/v3
+<session-id>, <session-id>	Jun 18	Dashboard <asset prefix> bulk operations	dashboard/v2/dashboard/{id}/widget/from-reports
+<session-id>	Jun 17	Short session	(minor)
+Companion to ENDPOINTS.md which covers the public Private-App API surface.

package/docs/INTERNAL_ENDPOINTS.md

@@ -0,0 +1,243 @@
+# HubSpot Internal Endpoint Catalogue
+
+This is the operator-facing map for allowlisted internal adapters. The full
+captured catalogue is [`INTERNAL-ENDPOINTS.md`](./INTERNAL-ENDPOINTS.md), and
+the live discovery log is
+[`INTERNAL-ENDPOINTS-DISCOVERY.md`](./INTERNAL-ENDPOINTS-DISCOVERY.md).
+
+This catalogue tracks browser-session endpoints that hscli can use only through
+allowlisted migration/setup adapters. It is not a generic internal API
+passthrough. Prefer public HubSpot APIs first; use these surfaces only when
+HubSpot has no public equivalent and the operator has an authenticated HubSpot
+browser session.
+
+Use `hscli internal surfaces` to list the implemented capture surfaces, and
+`hscli internal capture --surface <id>` or `hscli internal capture --all` to
+write read-only JSON captures plus a `capture-manifest.json`.
+Use `hscli internal coverage` when you need a JSON control sheet that ties the
+full Markdown catalogue, discovery log, allowlisted code module, endpoint
+counts, parameterized endpoints, and write-adapter promotion policy together
+without calling HubSpot.
+
+Use `hscli backup plan --include-internal` as the orchestrator for real backup
+work. The plan output includes:
+
+- `internalCapturePlan.oneShotCommand` for a broad allowlisted capture.
+- `internalCapturePlan.surfaceCommands` for safer surface-by-surface capture.
+- `internalCapturePlan.parameterizedExamples` for endpoints that require IDs or
+  explicit read bodies, such as `flowId`, `datasetId`, `reportId`,
+  `permissionSetId`, or `app-users-batch=<json-body-file>`.
+- `commands.internalApi`, which turns the same allowlist into a concrete runbook
+  with stdout redirected into the backup archive.
+
+The preferred operator flow is therefore:
+
+```bash
+hscli --profile source-readonly --json backup plan \
+  --portal-id "$PORTAL_ID" \
+  --include-internal \
+  --out-dir "$OUT_DIR" > "$OUT_DIR/backup-plan.json"
+
+hscli --profile source-readonly --json internal coverage \
+  > "$OUT_DIR/internal-api/internal-coverage.json"
+
+# Review backup-plan.json, then run either the one-shot command or the
+# individual surface commands it contains.
+```
+
+## Implemented Capture Surface Map
+
+The full discovery files are intentionally broader than the executable
+allowlist. The current `hscli internal capture` module turns these read-only or
+read-like surfaces into JSON backup assets:
+
+| Surface id | Captures |
+| --- | --- |
+| `business-units` | Business unit inventory and default BU context |
+| `branding` | Brand kits, multi-brand settings, colors, logos, favicons, fonts, and BU brand voice placeholders |
+| `permission-access` | App users, teams, permission sets, assignment maps, roles, seats, templates, FLP, and access-audit RPCs |
+| `datasets-reporting` | Data Studio datasets, reportable sources, joins, formulas, previews, async resolve calls, and async result polling |
+| `reports-dashboards` | Report definitions, favorites, report audit/history, record-view metadata, report permissions, report template discovery, dashboard layouts, widgets, dashboard grants, and report-list views |
+| `workflows-hybrid` | Workflow inventories, hybrid action graphs, validation, output fields, action catalog, CRM object context, canvas errors, access checks, filter-description previews, and card-position RPCs |
+| `properties-metadata` | Internal property metadata, legacy v1/v2 fallbacks, property groups, grouped-property listings, named property reads, recycled properties, quotas, fill rates, validation, dynamic options, and conditional options |
+| `crm-search` | Read-only CRM search, CRM GraphQL, object preview, and single-object UI payload helpers used by report builders, help desk, quotes, and object indexes |
+| `object-metadata` | Schema metadata, framework-builder metadata, portal-scoped object types, event object types, and object-type batch reads |
+| `conditional-properties` | Conditional property options and read-only rule RPCs |
+| `lists-segments` | List v3, portal-scoped list paths, legacy contacts/list v2 fallbacks, contact-list-management definitions, ILS segment stores, segments UI definitions, and legacy segment-search definitions |
+| `sales-content` | Sales content search, template/sequence fallbacks, sequence bodies/usage/health, sales template bodies/search/usage, libraries, snippets, playbook counts, playbook versions, and playbook question RPC reads |
+| `crm-views-record-layout` | Legacy/v2/v3/v4 CRM views, pinned/list/search views, visualization settings, view metadata, view limit checks, and record-card containers |
+| `marketing-internal` | Subscription channels, subscription visibility rules, privacy/GDPR settings, business-unit display maps, CAN-SPAM settings, cosemail email bodies/settings, CTA placements, and legacy forms batch |
+| `cms-design-manager` | Design Manager templates, content v2 templates, themes, modules, layouts, global groups, built-in module mapping, content pages, site settings, content-copy status, and membership access groups |
+| `social-ads` | Social broadcasts, connected social channels, social trusted-state checks, and read-only ads account/UI metadata RPCs |
+| `governance-audit` | Audit logs, security logs, installed apps, and sync bridge metadata |
+| `commerce-forecast-quotes` | Payment readiness, connected payment account, quote/commerce CRM search, forecast categories, and quote e-signature settings |
+| `conversations-chatflows` | Conversation custom views, workspace/view settings, inbox email/channel accounts, chatflow RPC reads, help desk tickets/preferences, and help desk migration state |
+| `account-security` | Account detail/activity, private apps, security center/monitoring/settings, CRM usage, installed apps, and sync bridge metadata |
+
+Use `--endpoint <id>` when an operator needs to capture one concrete endpoint
+from a surface without touching the rest of the surface. Use
+`--body-file <endpoint=path>` for allowlisted read-only POST endpoints such as
+batch hydration, preview, resolve, search, or Chirp RPC reads:
+
+```bash
+hscli --profile source-readonly --json internal capture \
+  --surface permission-access \
+  --endpoint app-users-batch \
+  --portal-id "$PORTAL_ID" \
+  --cookie-file "$HUBSPOT_COOKIE_FILE" \
+  --body-file app-users-batch=./bodies/app-users-batch.json \
+  --out-dir "$OUT_DIR/internal-api/permission-access"
+```
+
+The capture writes both the response JSON and a redacted
+`<endpoint>.request.json` proof file. The manifest records the request-body
+SHA-256 so the no-write log can be audited without storing browser secrets.
+
+The implemented capture catalogue is backed by
+`src/commands/internal/catalog.ts`. That module is deliberately allowlist-only:
+there is no command for arbitrary internal URLs. Internal POST calls are accepted
+only when HubSpot uses POST for a read-like operation such as search, preview,
+batch hydration, async resolve, or Chirp RPC reads; each one is tagged in code
+with its read-only purpose.
+
+Some endpoints in the full catalogue are known write or migration endpoints
+because they matter for future replay adapters. Those endpoints are documented
+for research and migration design, but they are not included in
+`hscli internal capture` unless they are read-only/read-like. Write adapters must
+be implemented as explicit product commands with policy checks, dry-run,
+`--force`, and audit trails.
+
+## Browser Session Auth Pattern
+
+Most internal endpoints require the HubSpot browser cookies plus the modern
+HubSpot API CSRF header:
+
+```js
+const csrf = document.cookie
+  .split("; ")
+  .find((cookie) => cookie.startsWith("hubspotapi-csrf="))
+  ?.split("=")[1];
+
+fetch(url, {
+  credentials: "include",
+  headers: { "X-HubSpot-CSRF-hubspotapi": csrf },
+});
+```
+
+In hscli this is exposed through `--cookie`, `--cookie-file`, and `--csrf`.
+Cookie files are filtered to allowlisted HubSpot app hosts before any request.
+
+## Admin, Access, And Permission Sets
+
+These endpoints are the supported permission migration/setup surface. They are
+allowlisted because HubSpot does not expose permission sets, role catalogs, seat
+assignments, or field-level permission state through the public bearer-token
+APIs. Role catalog size is portal-dependent; one Enterprise portal exposed 1,124
+atomic roles through this surface.
+
+| Surface | Endpoint | hscli status |
+| --- | --- | --- |
+| Permission sets list | `GET /api/app-users/v1/permission-sets?portalId={portalId}` | `settings permission-sets list`; definitions include `roleNames[]` inline |
+| Permission set get | `GET /api/app-users/v1/permission-sets/{id}?portalId={portalId}` | `settings permission-sets get`; label, `roleNames[]`, and capability flags |
+| Permission set create | `POST /api/app-users/v1/permission-sets?portalId={portalId}` | `settings permission-sets create` |
+| Permission set patch | `PATCH /api/app-users/v1/permission-sets/{id}?portalId={portalId}` | `settings permission-sets update --method PATCH`; rename or role delta |
+| Permission set replace | `PUT /api/app-users/v1/permission-sets/{id}?portalId={portalId}` | `settings permission-sets update --method PUT`; full overwrite |
+| Permission set delete | `DELETE /api/app-users/v1/permission-sets/{id}?portalId={portalId}` | `settings permission-sets delete`; HubSpot rejects assigned sets |
+| Permission set clone | `POST /api/app-users/v1/permission-sets/{id}/clone?portalId={portalId}` | `settings permission-sets clone` |
+| Atomic role catalog | `GET /api/app-users/v1/roles?portalId={portalId}` | `settings permission-sets roles list`; portal role inventory |
+| Single role | `GET /api/app-users/v1/roles/{roleName}?portalId={portalId}` | `settings permission-sets roles get`; description and dependencies |
+| Role categories | `GET /api/app-users/v1/role-categories?portalId={portalId}` | `settings permission-sets role-categories`; UI grouping |
+| Role scopes | `GET /api/app-users/v1/scopes?portalId={portalId}` | `settings permission-sets scopes`; owned/team/all/unassigned buckets |
+| App users list | `GET /api/app-users/v1/users?portalId={portalId}&limit=200&offset={offset}` | `settings permission-sets users list`; paginated user access payloads |
+| App user get | `GET /api/app-users/v1/users/{userId}?portalId={portalId}` | `settings permission-sets users get`; `permissionSetId`, `permissionSetIds`, derived/direct `roleNames[]` |
+| App users batch read | `POST /api/app-users/v1/users/partial/batch?portalId={portalId}` | `settings permission-sets users batch-read` |
+| Permission-set assignment map | `GET /api/app-users/v1/permission-sets/permission-set-user-assignments?portalId={portalId}` | `settings permission-sets assignments list`; portal-wide user-to-permission-set map for access migration and downgrade proof |
+| Permission set assignment | `POST /api/chirp-frontend-app/v1/gateway/com.hubspot.appusers.rpc.PermissionSetAssignmentsRpc/assignUserToPermissionSets?portalId={portalId}` | `settings permission-sets users assign` for one user, or `settings permission-sets users assign-batch --data '{"assignments":[...]}'` for the native RPC payload; body `{ assignments: [{ userId, permissionSetIds }] }` |
+| Seat assignments | `GET /api/app-users/v1/seat-assignments?portalId={portalId}` | `settings permission-sets seat-assignments list` |
+| Seat assignment update | `PATCH /api/app-users/v1/seat-assignments/{userId}?portalId={portalId}` | `settings permission-sets seat-assignments update` |
+| Seat catalog | `GET /api/app-users/v1/seats?portalId={portalId}` | `settings permission-sets seats` |
+| Permission templates | `GET /api/permission-templates/v1/templates?portalId={portalId}` | `settings permission-sets templates list`; HubSpot and custom templates |
+| Permission template get | `GET /api/permission-templates/v1/templates/{id}?portalId={portalId}` | `settings permission-sets templates get` |
+| Permission template create | `POST /api/permission-templates/v1/templates?portalId={portalId}` | `settings permission-sets templates create` |
+
+Complementary Chirp RPCs are capture/audit adapters first. They are useful for
+forensics and approval trails, but they should not become generic passthrough
+commands. hscli exposes only the allowlisted reads below through
+`settings permission-sets audit ... --data <json>`:
+
+- `com.hubspot.app.user.audits.service.rpc.AppUserAuditsRpc/getPermissionSetAssignmentHistory`
+- `com.hubspot.app.user.audits.service.rpc.AppUserAuditsRpc/getRoleChangeHistory`
+- `com.hubspot.app.user.audits.service.rpc.AppUserAuditsRpc/getUserAccessAudit`
+
+## Field-Level Permissions
+
+| Surface | Endpoint |
+| --- | --- |
+| Full allowlist inventory | `GET /api/crm-permissions/v1/field-level-permissions/allowlistings` | `settings flp list` |
+| Object allowlist inventory | `GET /api/crm-permissions/v1/field-level-permissions/allowlistings/{typeId}` | `settings flp object <typeId>` |
+| Single property allowlist | `GET /api/crm-permissions/v1/field-level-permissions/allowlistings/{typeId}/{property}` | `settings flp property <typeId> <propertyName>` |
+| Bulk access state | `POST /api/crm-permissions/v1/field-level-permissions/allowlistings/access-state/multi-get` | `settings flp access-state --data <json>`; read-mode POST |
+| Blocklist including global | `GET /api/crm-permissions/v1/field-level-permissions/blocklist/including-global` | `settings flp blocklist` |
+| FLP bypass users | `GET /api/permissions-skynet/v1/scopes/app/field-level-permissions-bypass/user-ids` | `settings flp bypass-users` |
+
+## Other Confirmed Internal Surfaces
+
+| Domain | Primary surfaces |
+| --- | --- |
+| Account / security | `/account-info/v3/*`, `/api/security-health/*`, `/api/security-settings/*`, installed-app and sync-bridge metadata |
+| Dashboards | `/api/dashboard/v2/dashboard/*`, `/dashboard/v2/dashboards/{dashboardId}` |
+| Reports | `/api/dashboard/v2/reports/*`, `/reporting-migration/v2/reports/migrate` |
+| Reporting data | `/api/reporting/v3/dataset/resolve/async` |
+| Datasets | `/sql-reporting/v1/datasets/*`, `/sql-reporting/v1/extended-reportable-options/*` |
+| Workflows | `/api/automationplatform/v1/hybrid/{flowId}`, validation, output fields, action catalog |
+| Properties | `/api/properties/v4/{typeId}`, `/api/properties/v4/groups/{typeId}`, v2 fallbacks |
+| Lists / segments | Legacy contacts lists, ILS segments, list search, and UI list views |
+| Sales content | `/api/templates/v1`, `/api/sales-content/v1`, `/api/sales-content-libraries/v2` |
+| Sequences | `/api/salescontentsearch/v2/search`, `/api/sequences/v3/sequences/{id}` |
+| Playbooks | Chirp RPC `com.hubspot.playbooks.rpc.PlaybooksRpc` |
+| Audit logs | `/api/audit-log/v1`, `/api/audit-log/v3`, `/api/security-audit-logs/v1` |
+| Object metadata | `/api/data-model/v3`, `/api/framework-builder/v1`, `/api/schemas-metadata/v1` |
+| CRM views | `/api/sales/v4/views/{typeId}`, legacy v2/v3 views, visualization settings |
+| Owners | `/api/owners/v2/owners`, `/owners-aether-search/v1/owners-search` |
+| Branding | `/api/branding/v1/*`, `/api/business-units/v1/*`, `/api/multi-brand/v1/*` |
+| Forms and marketing | `/forms/v2/forms`, `/marketing/v3/forms`, `/api/cosemail/v1/*` |
+| CTAs | Legacy and new CTA builder placement endpoints |
+| CMS | Design manager, content v2 pages/templates, site settings, content-copy status, membership, themes, modules, layouts |
+| Social and ads | `/api/broadcast/v2/*` plus read-only `com.hubspot.ads.rpc.*` Chirp RPCs |
+| CRM search and previews | `/api/crm-search/*`, `/api/graphql/crm`, and `/inbounddb-objects/v1/*` |
+| Conditional properties | `/api/conditional-properties/v2/rules/*` plus unified RPC reads |
+| Record cards | `/api/crm-record-cards/v4/container-views/*` |
+| Conversations / help desk | Custom views and Chirp RPC help desk services |
+| Chatflows | Chirp RPC `com.hubspot.chatflows.rpc.*` |
+| Payments / quotes / forecast | Feature-gated internal setup and eligibility endpoints |
+
+## Chirp Gateway
+
+Chirp RPCs use this shape:
+
+```text
+POST /api/chirp-frontend-app/v1/gateway/{ServiceName}/{Method}
+POST /api/chirp-frontend-app-slow/v1/gateway/{ServiceName}/{Method}
+```
+
+Known useful services include:
+
+- `com.hubspot.playbooks.rpc.PlaybooksRpc.*`
+- `com.hubspot.chatflows.rpc.*`
+- `com.hubspot.helpdesk.migration.rpc.HelpdeskMigrationRpc`
+- `com.hubspot.cv.custom.views.member.rpc.*`
+- `com.hubspot.automation.actions.rpc.RenderableActionDefinitionService`
+
+## Known Gaps And Non-Endpoints
+
+- Marketing email REST candidates such as `/api/marketing-emails/v1`,
+  `/api/email-publisher/v1`, `/api/cosemail/v1` public-style variants,
+  `/api/email-engine/v3`, `/api/email-management/v1`, `/api/email-management/v3`,
+  and `/cmscontent-api/v3/email` returned 404 in tested portals. Use the known
+  browser-session email UI/cosemail capture surfaces instead.
+- `GET /api/automation/v4/flows/{id}` returned 401 in-tab during testing; use
+  `/api/automationplatform/v1/hybrid/{flowId}` for full workflow fidelity.
+- `/api/contacts-list-app/v1/lists/search` returned 404 in tested portals.
+- CMS domain TLS/certificate configuration and HubSpot's own portal-copy job
+  trigger remain UI-controlled. Capture evidence and document them rather than
+  replaying them automatically.