SAPI Documentation

Add visitor sessions, form handling, and temporary data storage to your AI-built websites. No login required — sessions are anonymous and cookie-based.

Overview

SAPI provides four capabilities for visitor interactions:

How It Works

Session Lifecycle

When a visitor loads your website, a JavaScript snippet calls the session endpoint. The server creates a session in Redis with a 1-hour TTL, sets an httpOnly cookie, and returns a CSRF token. The session extends automatically when data is written (up to 24 hours max).

Authentication Model

SAPI uses two different authentication models:

Sessions

{
    "success": true,
    "data": {
        "session_id": "wss_a1b2c3d4e5f6...",
        "csrf_token": "f7e8d9c0b1a2...",
        "expires_in": 3600,
        "is_new": true
    }
}

Set-Cookie: wss_session=wss_a1b2c3d4...; HttpOnly; Secure; SameSite=Lax; Path=/sapi/project/{project_id}/; Max-Age=3600

{
    "success": true,
    "data": {
        "csrf_token": "new_token_here...",
        "expires_in": 3600
    }
}

Data Store

Store key-value data per visitor session. Ideal for shopping carts, user preferences, wizard state, and other temporary data. All data is stored in Redis and expires with the session.

{
    "success": true,
    "data": {
        "cart_items": [{ "product_id": 42, "quantity": 2 }],
        "cart_total": 29.98
    }
}

{
    "cart_items": [{ "product_id": 42, "quantity": 2 }],
    "cart_total": 29.98
}

{
    "success": true,
    "data": {
        "keys_updated": ["cart_items", "cart_total"],
        "session_expires_in": 14400
    }
}

Forms

Forms have two sides: configuration (you, the owner) and submission (your visitors). You define which forms exist, what fields they require, and what action the server takes when a form is submitted. Visitors only see the form name and send their field values.

Form Configuration (Authenticated)

These endpoints require a Bearer token (wps_ or wpa_). Use them directly or through MCP tools (configure_form, list_forms, remove_form).

{
    "form_name": "contact",
    "required_fields": ["name", "email", "message"],
    "action": {
        "type": "iapi",
        "service": "resend",
        "endpoint": "send-email",
        "input_template": {
            "to": "you@example.com",
            "subject": "Contact from {{fields.name}}",
            "html": "From: {{fields.name}} ({{fields.email}})<br>{{fields.message}}"
        }
    },
    "max_submits_per_session": 3
}

Form Submission (Anonymous)

This endpoint is called by visitors on your website. The form must be pre-configured by the owner.

{
    "form_name": "contact",
    "fields": {
        "name": "Jan Jansen",
        "email": "jan@example.nl",
        "message": "I have a question about your service."
    }
}

{
    "success": true,
    "data": {
        "form_accepted": true,
        "submits_remaining": 2,
        "action_result": {
            "status": "completed",
            "service": "resend",
            "endpoint": "send-email"
        }
    }
}

Security

CSRF Protection

SAPI uses the Double Submit Cookie pattern. The session cookie is httpOnly (not accessible from JavaScript), but the CSRF token is returned in the API response. Your JavaScript must include the token on every write request.

How to Send the CSRF Token

CORS

SAPI validates the Origin header against your project's domain. Requests from unauthorized origins are rejected. Subdomains of websitepublisher.ai are allowed automatically.

Rate Limiting

Anti-Abuse

Maximum 5 concurrent sessions per IP address per project. Excessive session creation triggers automatic rate limiting.

Error Handling

All errors return a consistent format:

{
    "success": false,
    "error": {
        "message": "Description of the error",
        "code": 403
    }
}

HTTP Status Codes

Complete Example

Here's the full flow for adding a contact form to your website:

# 1. Configure the form (as owner, via API or MCP tool)
curl -X POST "https://api.websitepublisher.ai/sapi/project/{project_id}/forms/configure" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "form_name": "contact",
    "required_fields": ["name", "email", "message"],
    "action": {
        "type": "iapi",
        "service": "resend",
        "endpoint": "send-email",
        "input_template": {
            "to": "you@example.com",
            "subject": "Contact from {{fields.name}}",
            "html": "From: {{fields.name}} ({{fields.email}})<br>{{fields.message}}"
        }
    }
  }'

# 2. Visitor starts a session (from your website JavaScript)
curl -c cookies.txt "https://api.websitepublisher.ai/sapi/project/{project_id}/session"
# → Returns: csrf_token in response body + wss_session cookie

# 3. Visitor submits the form
curl -b cookies.txt -X POST "https://api.websitepublisher.ai/sapi/project/{project_id}/form/submit" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: {csrf_token_from_step_2}" \
  -d '{
    "form_name": "contact",
    "fields": {
        "name": "Jan Jansen",
        "email": "jan@example.nl",
        "message": "Great website!"
    }
  }'
# → Email sent via Resend integration

# 4. Verify form config
curl "https://api.websitepublisher.ai/sapi/project/{project_id}/forms" \
  -H "Authorization: Bearer YOUR_TOKEN"