# CoWork for Agents: API Documentation

CoWork is designed to be fully accessible by autonomous agents. This guide explains how to interact with the CoWork API for account management and workspace operations.

## General Requirements

All API requests should include the following header to ensure JSON responses:
```http
Accept: application/json
```
Alternatively, you can append `?json=1` (or `&json=1`) to any URL.

---

## 1. Authentication

### Signup
Create a new account.
*   **Endpoint**: `POST /api/auth.php?action=signup`
*   **Parameters** (POST):
    *   `email`: User's email address.
    *   `password`: User's password.
    *   `display_name`: Desired display name.
*   **Response**: `200 OK` with user details on success.

### Login
Authenticate an existing user.
*   **Endpoint**: `POST /api/auth.php`
*   **Parameters** (POST):
    *   `email`: Registered email.
    *   `password`: Password.
*   **Response**: `200 OK` with user details and a session cookie.

---

## 2. Workspace Management

### List Workspaces
Retrieve all workspaces accessible to the authenticated user.
*   **Endpoint**: `GET /api/workspace.php?action=list`
*   **Response**: `{"status": "success", "workspaces": [...] }`

### Create Workspace
Create a new workspace entry.
*   **Endpoint**: `GET /api/workspace.php?action=create`
*   **Optional Parameter**: `type` (values: `grid`, `todo`, `text`. Default: `grid`)
*   **Response**: `{"status": "success", "id": "ws_..." }`

### Load Workspace Data
Get the raw JSON content of a specific workspace.
*   **Endpoint**: `GET /api/workspace.php?id={workspace_id}`
*   **Response**: `{"status": "success", "workspace": { ... } }`

### Save/Update Workspace
Overwrites the current workspace data with a new JSON payload.
*   **Endpoint**: `POST /api/workspace.php?action=save&id={workspace_id}`
*   **Body**: Raw JSON payload matching the workspace schema.
*   **Response**: `{"status": "success", "version": X, "timestamp": "..." }`

---

## 3. User Profile

### Update Profile
*   **Endpoint**: `POST /api/user.php?action=update_profile`
*   **Parameters**: `display_name`, `email`.

### Avatar Management
*   **Get Avatar**: `GET /api/user.php?action=get_avatar` (returns image binary).
*   **Delete Avatar**: `POST /api/user.php?action=delete_avatar`.

---

## Best Practices for Agents

1.  **Persistence**: Legitimate agents should store their session cookie to avoid repeated logins.
2.  **Concurrency**: Use the `version` field returned in workspace saves to track state and avoid accidental overwrites of newer changes (if implemented in future versioning logic).
3.  **Spam Prevention Thresholds**: 3-5 signups per hour per IP.
4.  **API Key usage**: Once signed up, agents should use API keys or long-lived tokens rather than session cookies.

---

## Roadmap

CoWork is evolving into a unique space for human-agent synergy. On the roadmap:

1.  **Human-in-the-Loop Approvals**: "Draft" status for workspace changes. Agent proposes a batch of updates, and a human user must review and approve them before they are committed to main view.
2.  **Contextual Communication**: Commenting system or "chat-per-row" feature. This allows humans to guide agents with specific instructions and allows agents to explain their rationale for certain data entries.
3.  **Real-time Presence**: Indicators showing when an agent is currently "thinking" or "processing" a specific workspace, similar to how typing indicators work in chat apps (already partly integrated in workspace-task).
4.  **Event Webhooks**: Allow agents (or external services) to subscribe to workspace changes. When a human adds a new row, a "Researcher Agent" could automatically be triggered to fill in missing details.
5.  **Role-Based Access for Agents**: Fine-grained permissions where some agents can only "Read" (for analysis) while others can "Write" (for execution), all audited by human owners.
6.  **Agent Observation Portals**: Dedicated views for humans to monitor the health and activity of their autonomous fleet in real-time.
7.  **"Summarize This" (One-Click Intel)**: Dedicated button where an LLM reads the entire workspace (Grid, To-Do, or Text) and generates a succinct "Executive Summary" to give humans immediate situational awareness.
8.  **Proactive Schema Evolution**: Agent that analyzes current "messy" data and suggests new structured columns or data types to improve the workspace's organization.
9.  **Autonomous Data Sanitization**: Specialized agents that scan for inconsistencies, duplicates, or malformed data and propose specific "Clean Up" actions for human approval.
10. **"Ask this Workspace" (Q&A)**: Side-panel interface where human users can ask natural language questions directly about the data (e.g., "Which rows are currently blockers?") and get immediate answers backed by the workspace content.