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

cloud/maplepress-backend/docs/API/create-user.md

@@ -0,0 +1,91 @@
+# Create User
+
+**POST /api/v1/users**
+
+Create a new user within a tenant.
+
+**Authentication**: Required (JWT Bearer token)
+
+**Tenant Context**: Required
+
+**Headers**:
+- `Content-Type: application/json`
+- `Authorization: JWT {access_token}`
+- `X-Tenant-ID: {tenant_id}` (required in development mode)
+
+**Request Body**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| email | string | Yes | User's email address |
+| name | string | Yes | User's full name |
+
+**Example Request**:
+
+```bash
+curl -X POST http://localhost:8000/api/v1/users \
+  -H "Content-Type: application/json" \
+  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
+  -H "X-Tenant-ID: 850e8400-e29b-41d4-a716-446655440000" \
+  -d '{
+    "email": "jane@techstart.com",
+    "name": "Jane Smith"
+  }'
+```
+
+**Example Response** (201 Created):
+
+```json
+{
+  "id": "950e8400-e29b-41d4-a716-446655440000",
+  "email": "jane@techstart.com",
+  "name": "Jane Smith",
+  "created_at": "2024-10-24T00:00:00Z"
+}
+```
+
+**Error Responses**:
+
+This endpoint returns errors in **RFC 9457 (Problem Details for HTTP APIs)** format.
+
+**Content-Type**: `application/problem+json`
+
+**400 Bad Request** - Invalid input:
+```json
+{
+  "type": "about:blank",
+  "title": "Bad Request",
+  "status": 400,
+  "detail": "Invalid request body format"
+}
+```
+
+**401 Unauthorized**:
+```json
+{
+  "type": "about:blank",
+  "title": "Unauthorized",
+  "status": 401,
+  "detail": "Authentication required"
+}
+```
+
+**409 Conflict** - Email already exists:
+```json
+{
+  "type": "about:blank",
+  "title": "Conflict",
+  "status": 409,
+  "detail": "User email already exists in this tenant"
+}
+```
+
+**500 Internal Server Error**:
+```json
+{
+  "type": "about:blank",
+  "title": "Internal Server Error",
+  "status": 500,
+  "detail": "Failed to create user"
+}
+```