# Agent Daily Goal - API Usage Manual

Welcome to the **Agent Daily Goal** API. This service allows autonomous AI agents to manage daily goals and log progress using a persistent **API Token**. Humans can log in to the web dashboard using their `username` and `password`, or directly access the dashboard via a URL query parameter using their `token`.

---

## 1. Concepts & Authentication

### Accounts & API Tokens
- Each account is mapped to a JSON file named `{username}.json` on the server (max 1000 accounts).
- When you register a new account, a secure, persistent **API Token** (prefixed with `agt_`) is generated.
- **Service Authentication:** All goal-management API requests require the `token` parameter. You can supply the token in three ways:
  1. As a query parameter: `?token=<your_api_token>`
  2. As a JSON key in the POST request body: `{"token": "<your_api_token>", ...}`
  3. In the HTTP headers: `Authorization: Bearer <your_api_token>`
- **Token Persistence:** The token never changes unless you explicitly request a reset via the API.

### Dashboard Access
- Humans can access the dashboard by visiting the homepage and logging in with their **Username** and **Password**.
- Alternatively, humans can open the dashboard directly using the token in the URL:
  `http://localhost/app/app/agent-daily-goal/index.php?token=<your_api_token>`

---

## 2. API Reference

All requests must be sent to the API endpoint:
`POST/GET /app/app/agent-daily-goal/api.php`

---

### 1. Register / Create Account
Creates a new account and returns a persistent API token.
- **Endpoint:** `POST /app/app/agent-daily-goal/api.php?action=register`
- **Request Headers:** `Content-Type: application/json`
- **Request Body (JSON):**
```json
{
  "username": "my_agent_007",
  "password": "my_secure_password_123"
}
```
- **Response (JSON):**
```json
{
  "status": "success",
  "message": "Account created successfully",
  "token": "agt_5f8a2c1e4d3b6e8a"
}
```

### 2. Login / Retrieve API Token
Authenticates using the `username` and `password` to retrieve the current persistent API Token.
- **Endpoint:** `POST /app/app/agent-daily-goal/api.php?action=login` (or `action=auth`)
- **Request Headers:** `Content-Type: application/json`
- **Request Body (JSON):**
```json
{
  "username": "my_agent_007",
  "password": "my_secure_password_123"
}
```
- **Response (JSON):**
```json
{
  "status": "success",
  "message": "Authenticated successfully.",
  "token": "agt_5f8a2c1e4d3b6e8a"
}
```

### 3. Reset API Token
Resets and generates a new API token for the account. You must authorize using either the `username`/`password` combination OR your current `token`.
- **Endpoint:** `POST /app/app/agent-daily-goal/api.php?action=reset_token`
- **Request Headers:** `Content-Type: application/json`
- **Request Body (JSON - option A):**
```json
{
  "username": "my_agent_007",
  "password": "my_secure_password_123"
}
```
- **Request Body (JSON - option B):**
```json
{
  "token": "agt_5f8a2c1e4d3b6e8a"
}
```
- **Response (JSON):**
```json
{
  "status": "success",
  "message": "Token reset successfully",
  "token": "agt_9d8e7f6c5b4a3f2e"
}
```

### 3. Get Goals & Configuration
Retrieves all goals under the authenticated account.
- **Endpoint:** `GET /app/app/agent-daily-goal/api.php?token=<your_api_token>`
  - Optional Query Parameter: `&group=1` or `&group=channel_project`. If set, the returned JSON groups goals hierarchically by Channel and Project.
- **Response (Flat List - Default):**
```json
{
  "status": "success",
  "username": "my_agent_007",
  "created_at": "2026-07-09T11:46:00+07:00",
  "goals": [
    {
      "id": "goal_1720516480",
      "name": "Upload YouTube Videos",
      "daily_target": 2,
      "unit": "clips",
      "start_date": "2026-07-05",
      "specific_targets": {},
      "logs": [
        {"date": "2026-07-05", "value": 10, "note": "Batch upload"}
      ]
    }
  ]
}
```
- **Response (Grouped List - when `&group=1`):**
```json
{
  "status": "success",
  "username": "my_agent_007",
  "created_at": "2026-07-09T11:46:00+07:00",
  "grouped": {
    "My Channel Name": {
      "My Project Name": [
        {
          "id": "goal_1720516480",
          "name": "Upload YouTube Videos",
          "daily_target": 2,
          "unit": "clips",
          "start_date": "2026-07-05",
          "specific_targets": {},
          "logs": [
            {"date": "2026-07-05", "value": 10, "note": "Batch upload"}
          ]
        }
      ]
    }
  }
}
```

### 4. Add Goal
Creates a new goal inside the account configuration.
- **Endpoint:** `POST /app/app/agent-daily-goal/api.php?action=add_goal`
- **Request Headers:** `Content-Type: application/json`
- **Request Body (JSON):**
```json
{
  "token": "agt_5f8a2c1e4d3b6e8a",
  "name": "Upload YouTube Videos",
  "daily_target": 2,
  "unit": "clips",
  "start_date": "2026-07-09"
}
```
- **Response (JSON):**
```json
{
  "status": "success",
  "message": "Goal added successfully",
  "goal_id": "goal_1720516480"
}
```

### 5. Log Progress
Logs completed progress value for a specific date.
- **Endpoint:** `POST /app/app/agent-daily-goal/api.php?action=log_progress&goal_id=<goal_id>`
- **Request Headers:** `Content-Type: application/json`
- **Request Body (JSON):**
```json
{
  "token": "agt_5f8a2c1e4d3b6e8a",
  "date": "2026-07-09",
  "value": 2,
  "note": "Uploaded morning clips"
}
```
- **Response (JSON):**
```json
{
  "status": "success",
  "message": "Progress logged successfully"
}
```

### 6. Set Settings
Updates the settings configuration object under the authenticated account (e.g. configuring which dynamic columns to display in the Projects view).
- **Endpoint:** `POST /app/app/agent-daily-goal/api.php?action=set_settings`
- **Request Headers:** `Content-Type: application/json`
- **Request Body (JSON):**
```json
{
  "token": "agt_5f8a2c1e4d3b6e8a",
  "project_columns": ["channel", "priority", "status"]
}
```
- **Response (JSON):**
```json
{
  "status": "success",
  "message": "Settings updated successfully."
}
```

### 7. Rename Project
Renames a project group name across all goals under the authenticated account.
- **Endpoint:** `POST /app/app/agent-daily-goal/api.php?action=rename_project`
- **Request Headers:** `Content-Type: application/json`
- **Request Body (JSON):**
```json
{
  "token": "agt_5f8a2c1e4d3b6e8a",
  "old_name": "Old Project Name",
  "new_name": "New Project Name"
}
```
- **Response (JSON):**
```json
{
  "status": "success",
  "message": "Project renamed successfully.",
  "updated_count": 3
}
```

---

## 3. Example Implementation in cURL

### Register Account
```bash
curl -X POST "http://localhost/app/app/agent-daily-goal/api.php?action=register" \
     -H "Content-Type: application/json" \
     -d '{"username": "my_agent_007", "password": "my_secure_password_123"}'
```

### Logging Progress
```bash
curl -X POST "http://localhost/app/app/agent-daily-goal/api.php?action=log_progress&goal_id=goal_1720516480" \
     -H "Content-Type: application/json" \
     -d '{"token": "agt_5f8a2c1e4d3b6e8a", "value": 10, "date": "2026-07-09", "note": "Finished uploads"}'
```