# TestArena API Reference

TestArena provides a RESTful API for programmatic job submission and status monitoring.

## Base URL

All API endpoints are prefixed with `/api`.

```
http://<your-server>/api
```

## Authentication

The API uses Basic Authentication. You must provide your username and password in the request body for job submission.

## Endpoints

### 1. Submit Job

Submit a new test job to the queue.

-   **URL**: `/submit_job`
-   **Method**: `POST`
-   **Content-Type**: `application/json`

#### Request Body

| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `username` | string | Yes | Your TestArena username |
| `password` | string | Yes | Your TestArena password |
| `branch_name` | string | Yes | Git branch name to test |
| `scenarios` | array | Yes | List of scenario names to execute |

#### Example Request

```bash
curl -X POST http://localhost:5000/api/submit_job \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "your_password",
    "branch_name": "feature/new-driver",
    "scenarios": ["adc_init_test", "gpio_init_test"]
  }'
```

#### Success Response

**Code**: `200 OK`

```json
{
  "success": true,
  "job_id": 123,
  "status": "waiting",
  "remote_triggered": true,
  "message": "Job submitted successfully"
}
```

#### Error Response

**Code**: `401 Unauthorized`

```json
{
  "error": "Invalid credentials"
}
```

**Code**: `400 Bad Request`

```json
{
  "error": "Missing required fields: username, password, branch_name, scenarios"
}
```

---

### 2. Get Job Status

Retrieve the status and details of a specific job.

-   **URL**: `/job/<job_id>`
-   **Method**: `GET`

#### URL Parameters

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `job_id` | integer | Yes | The ID of the job to retrieve |

#### Example Request

```bash
curl http://localhost:5000/api/job/123
```

#### Success Response

**Code**: `200 OK`

```json
{
  "job_id": 123,
  "status": "in_progress",
  "branch_name": "feature/new-driver",
  "scenarios": ["adc_init_test", "gpio_init_test"],
  "remote_results": {
    "adc_init_test": ["PASS", "http://.../report.html"],
    "gpio_init_test": ["FAIL", "http://.../report.html"]
  },
  "created_at": "2023-10-27T10:00:00",
  "completed_at": null,
  "remote_queue_id": "123"
}
```

#### Error Response

**Code**: `404 Not Found`

```json
{
  "error": "Job not found"
}
```