# API Contracts: Refactor CLI Scripts to Web Application

## 1. Tools API

### 1.1. Search Datasets
**Endpoint**: `POST /api/tools/search`
**Description**: Search for text patterns across all datasets in a specific environment.

**Request Body**:
```json
{
  "env": "dev",
  "query": "regex_pattern"
}
```

**Response (200 OK)**:
```json
{
  "count": 5,
  "results": [
    {
      "dataset_id": 123,
      "dataset_name": "sales_data",
      "field": "sql",
      "match_context": "SELECT * FROM ...",
      "full_value": "SELECT * FROM sales WHERE ..."
    }
  ]
}
```

### 1.2. Debug Database API
**Endpoint**: `POST /api/tools/debug/db-api`
**Description**: Test database API connectivity and structure between two environments.

**Request Body**:
```json
{
  "source_env": "dev",
  "target_env": "prod"
}
```

**Response (200 OK)**:
```json
{
  "source_db_count": 10,
  "target_db_count": 12,
  "details": {
    "source_dbs": [...],
    "target_dbs": [...]
  }
}
```

### 1.3. Get Dataset Structure
**Endpoint**: `GET /api/tools/debug/dataset/{env}/{dataset_id}`
**Description**: Retrieve the full JSON structure of a dataset.

**Response (200 OK)**:
```json
{
  "id": 123,
  "table_name": "sales",
  "columns": [...],
  "metrics": [...]
}
```

## 2. Connection Management API

### 2.1. List Connections
**Endpoint**: `GET /api/settings/connections`
**Response (200 OK)**:
```json
[
  {
    "id": "uuid",
    "name": "Production DWH",
    "type": "postgres",
    "host": "10.0.0.1",
    "database": "dwh",
    "username": "user",
    "created_at": "2026-01-07T10:00:00Z"
  }
]
```

### 2.2. Create Connection
**Endpoint**: `POST /api/settings/connections`
**Request Body**:
```json
{
  "name": "Production DWH",
  "type": "postgres",
  "host": "10.0.0.1",
  "port": 5432,
  "database": "dwh",
  "username": "user",
  "password": "secret_password"
}
```
**Response (201 Created)**:
```json
{
  "id": "uuid",
  "name": "Production DWH",
  "type": "postgres",
  ...
}
```

### 2.3. Delete Connection
**Endpoint**: `DELETE /api/settings/connections/{id}`
**Response (204 No Content)**

## 3. Task API (Existing, extended for Mapping)

### 3.1. Create Mapping Task
**Endpoint**: `POST /api/tasks`
**Request Body**:
```json
{
  "plugin_id": "dataset-mapper",
  "params": {
    "env": "dev",
    "dataset_id": 123,
    "source": "postgres",
    "connection_id": "uuid-of-saved-connection",
    "table_name": "sales",
    "table_schema": "public"
  }
}