> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/sfp-server/api-reference/insights-reports.md). # Insights Reports ## POST /sfp/api/insights/reports/refresh > Trigger the Hatchet collect-org-insight workflow on demand for a target org. Idempotent: returns the in-flight runId with status=already-running if a prior run is still active. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"52.11.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"RefreshInsightsReportDto":{"type":"object","properties":{"targetOrg":{"type":"string","description":"Salesforce target org username"},"includeManaged":{"type":"boolean","description":"Include managed-package metadata in the report","default":false},"includePopulation":{"type":"boolean","description":"Run field-population analysis (slow on large orgs)","default":true}},"required":["targetOrg"]}}},"paths":{"/sfp/api/insights/reports/refresh":{"post":{"operationId":"InsightsReportsController_refresh","summary":"Trigger the Hatchet collect-org-insight workflow on demand for a target org. Idempotent: returns the in-flight runId with status=already-running if a prior run is still active.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshInsightsReportDto"}}}},"responses":{"202":{"description":"Workflow run accepted or already in flight."},"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Insights Reports"]}}}} ``` ## GET /sfp/api/insights/reports/active > Return the in-flight collect-org-insight run for a target org, if one is currently dispatched/running. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"52.11.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/insights/reports/active":{"get":{"operationId":"InsightsReportsController_active","summary":"Return the in-flight collect-org-insight run for a target org, if one is currently dispatched/running.","parameters":[{"name":"targetOrg","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Insights Reports"]}}}} ``` ## GET /sfp/api/insights/reports/runs > Recent collect-org-insight executions for a target org (any status), newest first. Backed by sfp\_task\_executions. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"52.11.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/insights/reports/runs":{"get":{"operationId":"InsightsReportsController_runs","summary":"Recent collect-org-insight executions for a target org (any status), newest first. Backed by sfp_task_executions.","parameters":[{"name":"targetOrg","required":true,"in":"query","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Insights Reports"]}}}} ``` ## POST /sfp/api/insights/reports/upload > Upload an HTML insights report to object storage (keyed by target org). ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"52.11.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"UploadInsightsReportDto":{"type":"object","properties":{"targetOrg":{"type":"string","description":"Salesforce target org username (acts as the storage key namespace)"},"capturedAt":{"type":"string","description":"ISO 8601 capture timestamp"},"html":{"type":"string","description":"Rendered HTML report (UTF-8 string)"},"combinedJson":{"type":"object","description":"Combined OrgInsightResult JSON (the full result the CLI/Hatchet job produced)."},"sections":{"description":"Per-section JSON outputs. Each entry stores at sections/.json under the same run folder.","type":"array","items":{"$ref":"#/components/schemas/UploadInsightsReportSectionDto"}}},"required":["targetOrg","capturedAt"]},"UploadInsightsReportSectionDto":{"type":"object","properties":{"id":{"type":"string","description":"Section identifier (e.g. glance, apex)"},"json":{"type":"object","description":"Section payload (the renderer-agnostic data for that insight)"}},"required":["id","json"]}}},"paths":{"/sfp/api/insights/reports/upload":{"post":{"operationId":"InsightsReportsController_upload","summary":"Upload an HTML insights report to object storage (keyed by target org).","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadInsightsReportDto"}}}},"responses":{"201":{"description":"Stored. Returns the storage key."},"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Insights Reports"]}}}} ``` ## GET /sfp/api/insights/reports/available-orgs > List registered orgs with an available HTML insights report, newest first. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"52.11.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/insights/reports/available-orgs":{"get":{"operationId":"InsightsReportsController_availableOrgs","summary":"List registered orgs with an available HTML insights report, newest first.","parameters":[],"responses":{"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Insights Reports"]}}}} ``` ## GET /sfp/api/insights/reports > List uploaded insights runs for a target org (newest first). ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"52.11.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/insights/reports":{"get":{"operationId":"InsightsReportsController_list","summary":"List uploaded insights runs for a target org (newest first).","parameters":[{"name":"targetOrg","required":true,"in":"query","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Insights Reports"]}}}} ``` ## GET /sfp/api/insights/reports/latest > Return the most recent insights run for a target org, including the artifact keys (report.html, report.json, sections/\.json). ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"52.11.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/insights/reports/latest":{"get":{"operationId":"InsightsReportsController_latest","summary":"Return the most recent insights run for a target org, including the artifact keys (report.html, report.json, sections/.json).","parameters":[{"name":"targetOrg","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Insights Reports"]}}}} ``` ## GET /sfp/api/insights/reports/latest/content > Stream a specific artifact from the most recent run. ?artifact=report.html | report.json | sections/\.json ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"52.11.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/insights/reports/latest/content":{"get":{"operationId":"InsightsReportsController_latestContent","summary":"Stream a specific artifact from the most recent run. ?artifact=report.html | report.json | sections/.json","parameters":[{"name":"targetOrg","required":true,"in":"query","schema":{"type":"string"}},{"name":"artifact","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Insights Reports"]}}}} ``` ## GET /sfp/api/insights/reports/content/\* > Download a stored artifact by its full storage key. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"52.11.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/insights/reports/content/*":{"get":{"operationId":"InsightsReportsController_download","summary":"Download a stored artifact by its full storage key.","parameters":[{"name":"0","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Insights Reports"]}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.flxbl.io/flxbl/sfp-server/api-reference/insights-reports.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.