monorepo/cloud/maplepress-backend/docs/API/create-site.md

Create WordPress Site

POST /api/v1/sites

Create a new WordPress site and generate API credentials for the WordPress plugin.

Authentication: Required (JWT Bearer token)

Headers:

• Content-Type: application/json
• Authorization: JWT {access_token} (tenant is automatically determined from JWT)

Request Body:

Field	Type	Required	Description
domain	string	Yes	WordPress site domain (e.g., example.com)
site_url	string	Yes	Full WordPress site URL (e.g., https://example.com)

Example Request:

curl -X POST http://localhost:8000/api/v1/sites \
  -H "Content-Type: application/json" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "domain": "example.com",
    "site_url": "https://example.com"
  }'

Example Response (201 Created):

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "domain": "example.com",
  "site_url": "https://example.com",
  "api_key": "live_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "verification_token": "mvp_xyz789abc123",
  "status": "pending",
  "search_index_name": "site_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Important Notes:

• The api_key is shown only once - save it immediately!
• The site starts with status: "pending" until verified
• The verification_token should be used by the WordPress plugin for site verification
• The search_index_name is the Meilisearch index for this site

Error Responses:

This endpoint returns errors in RFC 9457 (Problem Details for HTTP APIs) format.

Validation Error Response (400 Bad Request):

{
  "type": "about:blank",
  "title": "Validation Error",
  "status": 400,
  "detail": "One or more validation errors occurred",
  "errors": {
    "domain": ["Invalid domain format", "Domain is required"],
    "site_url": ["Invalid URL format", "Site URL is required"]
  }
}

Content-Type: application/problem+json

Common Validation Error Messages:

Field	Error Messages
domain	"Invalid domain format", "Domain is required"
site_url	"Invalid URL format", "Site URL is required"

Other Error Responses:

• 401 Unauthorized: Missing or invalid JWT token

  {
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Authentication required"
  }
  

• 409 Conflict: Domain already registered by another user

  {
    "type": "about:blank",
    "title": "Conflict",
    "status": 409,
    "detail": "Domain already exists"
  }
  

• 500 Internal Server Error: Server error

  {
    "type": "about:blank",
    "title": "Internal Server Error",
    "status": 500,
    "detail": "Failed to create site"
  }