# Visualization ## Get package visualization metadata with timeline > Returns metadata for a repository/branch including the commit timeline.\ > The timeline contains commit IDs, timestamps, and ordering — suitable for building\ > a timeline slider in the UI without loading snapshot data. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/visualization/packages/metadata":{"get":{"operationId":"VisualizationController_getMetadata","summary":"Get package visualization metadata with timeline","description":"Returns metadata for a repository/branch including the commit timeline.\n The timeline contains commit IDs, timestamps, and ordering — suitable for building\n a timeline slider in the UI without loading snapshot data.","parameters":[{"name":"repositoryIdentifier","required":true,"in":"query","schema":{"type":"string"}},{"name":"branch","required":true,"in":"query","schema":{"type":"string"}},{"name":"releaseConfigPath","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Metadata with timeline if available, null otherwise"},"400":{"description":"Missing required parameters"},"403":{"description":"Forbidden - Requires role: member, application"},"404":{"description":"Project not found"}},"tags":["Visualization"]}}}} ``` ## Upsert visualization metadata > Creates or updates visualization metadata for a repository/branch.\ > Returns the metadataId needed for batch commit uploads. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/visualization/packages/metadata":{"put":{"operationId":"VisualizationController_upsertMetadata","summary":"Upsert visualization metadata","description":"Creates or updates visualization metadata for a repository/branch.\n Returns the metadataId needed for batch commit uploads.","parameters":[],"responses":{"200":{"description":"Metadata upserted, returns metadataId"},"403":{"description":"Forbidden - Requires role: application"}},"tags":["Visualization"]}}}} ``` ## Get paginated commit snapshots > Returns commit snapshots with pagination. Each commit contains its\ > package snapshots (\~1-5KB). Default limit is 50, max is 200.\ > Results are ordered newest-first by commit\_order. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/visualization/packages/commits":{"get":{"operationId":"VisualizationController_getCommitsPaginated","summary":"Get paginated commit snapshots","description":"Returns commit snapshots with pagination. Each commit contains its\n package snapshots (~1-5KB). Default limit is 50, max is 200.\n Results are ordered newest-first by commit_order.","parameters":[{"name":"repositoryIdentifier","required":true,"in":"query","schema":{"type":"string"}},{"name":"branch","required":true,"in":"query","schema":{"type":"string"}},{"name":"offset","required":false,"in":"query","schema":{"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"Paginated commit snapshots"},"403":{"description":"Forbidden - Requires role: member, application"},"404":{"description":"No visualization data or project not found"}},"tags":["Visualization"]}}}} ``` ## Batch upsert commit snapshots > Upserts a batch of commit snapshots for a given metadataId.\ > The engine sends batches of \~100 commits at a time. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/visualization/packages/commits/batch":{"post":{"operationId":"VisualizationController_upsertCommitsBatch","summary":"Batch upsert commit snapshots","description":"Upserts a batch of commit snapshots for a given metadataId.\n The engine sends batches of ~100 commits at a time.","parameters":[],"responses":{"200":{"description":"Commits upserted"},"403":{"description":"Forbidden - Requires role: application"}},"tags":["Visualization"]}}}} ``` ## Get existing commit IDs for incremental collection > Returns the list of commit IDs already stored for a repository/branch.\ > The engine uses this to skip commits that have already been processed. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/visualization/packages/commits/existing":{"get":{"operationId":"VisualizationController_getExistingCommitIds","summary":"Get existing commit IDs for incremental collection","description":"Returns the list of commit IDs already stored for a repository/branch.\n The engine uses this to skip commits that have already been processed.","parameters":[{"name":"repositoryIdentifier","required":true,"in":"query","schema":{"type":"string"}},{"name":"branch","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Existing commit IDs and metadataId"},"403":{"description":"Forbidden - Requires role: application"}},"tags":["Visualization"]}}}} ``` ## Get snapshots for a single commit > Returns the package snapshots for a specific commit ID. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/visualization/packages/commits/{commitId}":{"get":{"operationId":"VisualizationController_getCommitById","summary":"Get snapshots for a single commit","description":"Returns the package snapshots for a specific commit ID.","parameters":[{"name":"repositoryIdentifier","required":true,"in":"query","schema":{"type":"string"}},{"name":"branch","required":true,"in":"query","schema":{"type":"string"}},{"name":"commitId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Commit snapshots"},"403":{"description":"Forbidden - Requires role: member, application"},"404":{"description":"Commit or project not found"}},"tags":["Visualization"]}}}} ``` ## Get visualization status > Check the current status of package visualization for a repository/branch.\ > Returns one of: \`never\_ran\`, \`generating\`, \`available\`, or \`failed\`.\ > Safe to poll — does not trigger any work. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/visualization/packages/status":{"get":{"operationId":"VisualizationController_getStatus","summary":"Get visualization status","description":"Check the current status of package visualization for a repository/branch.\n Returns one of: `never_ran`, `generating`, `available`, or `failed`.\n Safe to poll — does not trigger any work.","parameters":[{"name":"repositoryIdentifier","required":true,"in":"query","schema":{"type":"string"}},{"name":"branch","required":true,"in":"query","schema":{"type":"string"}},{"name":"releaseConfigPath","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Current visualization status"},"403":{"description":"Forbidden - Requires role: member, application"}},"tags":["Visualization"]}}}} ``` ## Trigger visualization refresh > Triggers a new visualization data collection via Hatchet workflow.\ > Returns a task execution ID for tracking.\ > Returns 409 Conflict if a visualization job is already running for this repository/branch. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/visualization/packages/refresh":{"post":{"operationId":"VisualizationController_refreshVisualization","summary":"Trigger visualization refresh","description":"Triggers a new visualization data collection via Hatchet workflow.\n Returns a task execution ID for tracking.\n Returns 409 Conflict if a visualization job is already running for this repository/branch.","parameters":[{"name":"repositoryIdentifier","required":true,"in":"query","schema":{"type":"string"}},{"name":"branch","required":true,"in":"query","schema":{"type":"string"}},{"name":"releaseConfigPath","required":true,"in":"query","schema":{"type":"string"}},{"name":"maxCommits","required":false,"in":"query","schema":{"type":"number"}}],"responses":{"202":{"description":"Refresh triggered"},"403":{"description":"Forbidden - Requires role: member, application"},"409":{"description":"Visualization already in progress"}},"tags":["Visualization"]}}}} ``` --- # Agent Instructions: 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: ``` GET https://docs.flxbl.io/flxbl/sfp-server/api-reference/visualization.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.