ss-tools/specs/011-git-integration-dashboard/contracts/api.md

API Contracts: Git Integration Plugin

Feature: Git Integration for Dashboard Development Date: 2026-01-22

Base Path

/api/git

Endpoints

1. Configuration

GET /config/{dashboard_uuid}

Retrieve Git configuration for a specific dashboard.

• Response: GitServerConfig (excluding full token)

POST /config

Save or update Git configuration.

• Request: GitServerConfig
• Response: GitServerConfig

2. Repository Operations

POST /init/{dashboard_uuid}

Initialize/Clone the repository for the dashboard.

• Request: Empty (uses stored config)
• Response: { "status": "success", "message": "Repository cloned" }

GET /status/{dashboard_uuid}

Get current status (changes between Superset export and local git HEAD).

• Response:

  {
    "branch": "main",
    "changes": [
      { "file_path": "charts/sales.yaml", "change_type": "MODIFIED" }
    ],
    "is_clean": false
  }
  

POST /sync/{dashboard_uuid}

Fetch latest dashboard export from Superset and unpack into the git working directory (overwriting local files to match Superset state).

• Response: { "status": "success", "changes_detected": true }

3. Branch Management

GET /branches/{dashboard_uuid}

List all local and remote branches.

• Response: List[Branch]

POST /branches/{dashboard_uuid}

Create a new branch.

• Request: { "name": "feature/new-chart", "source_branch": "main" }
• Response: Branch

POST /checkout/{dashboard_uuid}

Switch to a different branch. Warning: This updates the Superset Dashboard content to match the branch state!

• Request: { "branch_name": "main" }
• Response: { "status": "success", "message": "Switched to main and updated dashboard" }

4. Commit & Push

POST /commit/{dashboard_uuid}

Commit staged changes.

• Request: { "message": "Updated sales chart", "files": ["charts/sales.yaml"] }
• Response: Commit

POST /push/{dashboard_uuid}

Push commits to remote.

• Response: { "status": "success" }

POST /pull/{dashboard_uuid}

Pull changes from remote.

• Response: { "status": "success", "updates": [...] }

5. History

GET /history/{dashboard_uuid}

Get commit log.

• Query Params: limit=20, branch=main
• Response: List[Commit]

6. Deployment

GET /environments

List configured target environments.

• Response: List[Environment]

POST /deploy/{dashboard_uuid}

Deploy current branch state to a target environment.

• Request: { "environment_id": "uuid", "commit_hash": "optional-hash" }
• Response: { "status": "success", "job_id": "..." }