# 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**:
    ```json
    {
      "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": "..." }`