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

cloud/maplepress-backend/docs/API/plugin-verify-api-key.md

@@ -0,0 +1,73 @@
+# Verify API Key (WordPress Plugin)
+
+**GET /api/v1/plugin/status**
+
+Verify that an API key is valid and retrieve site information. This endpoint is used by the WordPress plugin to verify the connection and display quota information.
+
+**Authentication**: Required (API Key)
+
+**Headers**:
+- `Authorization: Bearer {api_key}`
+
+**Example Request**:
+
+```bash
+curl -X GET http://localhost:8000/api/v1/plugin/status \
+  -H "Authorization: Bearer live_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
+```
+
+**Example Response** (200 OK):
+
+```json
+{
+  "site_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "tenant_id": "t1t2t3t4-t5t6-7890-tttt-tttttttttttt",
+  "domain": "example.com",
+  "site_url": "https://example.com",
+  "status": "active",
+  "is_verified": true,
+  "storage_used_bytes": 52428800,
+  "search_requests_count": 234,
+  "monthly_pages_indexed": 50,
+  "total_pages_indexed": 145,
+  "search_index_name": "site_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "api_key_prefix": "live_sk_a1b2",
+  "api_key_last_four": "s9t0",
+  "plugin_version": "1.0.0",
+  "message": "API key is valid"
+}
+```
+
+**Notes**:
+- Used by WordPress plugin to verify connection on plugin activation
+- Returns site information and usage tracking statistics
+- If the API key is invalid or missing, returns 401 Unauthorized
+- Usage-based billing: No quotas or limits, only usage tracking for billing
+- If the request reaches this handler, the API key has already been validated by the middleware
+- API key must start with `live_sk_` or `test_sk_` prefix
+
+**Error Responses**:
+
+This endpoint returns errors in **RFC 9457 (Problem Details for HTTP APIs)** format.
+
+**Content-Type**: `application/problem+json`
+
+**401 Unauthorized** - Invalid or missing API key:
+```json
+{
+  "type": "about:blank",
+  "title": "Unauthorized",
+  "status": 401,
+  "detail": "Invalid or missing API key"
+}
+```
+
+**500 Internal Server Error**:
+```json
+{
+  "type": "about:blank",
+  "title": "Internal Server Error",
+  "status": 500,
+  "detail": "Failed to verify API key"
+}
+```