Initial commit: Open sourcing all of the Maple Open Technologies code.

cloud/maplepress-backend/docs/API/list-sites.md

@@ -0,0 +1,79 @@
+# List WordPress Sites
+
+**GET /api/v1/sites**
+
+Retrieve all WordPress sites for the authenticated user's tenant.
+
+**Authentication**: Required (JWT Bearer token)
+
+**Headers**:
+- `Authorization: JWT {access_token}`
+
+**Query Parameters**:
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| page_size | integer | No | Number of results per page (default: 20, max: 100) |
+| page_state | string | No | Pagination token from previous response |
+
+**Example Request**:
+
+```bash
+curl -X GET 'http://localhost:8000/api/v1/sites?page_size=20' \
+  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+```
+
+**Example Response** (200 OK):
+
+```json
+{
+  "sites": [
+    {
+      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+      "domain": "example.com",
+      "status": "active",
+      "is_verified": true,
+      "created_at": "2024-10-27T10:00:00Z"
+    },
+    {
+      "id": "b2c3d4e5-f6g7-8901-bcde-f12345678901",
+      "domain": "another-site.com",
+      "status": "pending",
+      "is_verified": false,
+      "created_at": "2024-10-27T11:00:00Z"
+    }
+  ],
+  "page_state": "base64_encoded_pagination_token"
+}
+```
+
+**Notes**:
+- Returns a summary view (limited fields) for performance
+- Use `page_state` for pagination through large result sets
+- Sites are ordered by creation date (newest first)
+
+**Error Responses**:
+
+This endpoint returns errors in **RFC 9457 (Problem Details for HTTP APIs)** format.
+
+**Content-Type**: `application/problem+json`
+
+**401 Unauthorized**:
+```json
+{
+  "type": "about:blank",
+  "title": "Unauthorized",
+  "status": 401,
+  "detail": "Authentication required"
+}
+```
+
+**500 Internal Server Error**:
+```json
+{
+  "type": "about:blank",
+  "title": "Internal Server Error",
+  "status": 500,
+  "detail": "Failed to retrieve sites"
+}
+```