REST API Reference

Create a new user account.

{
  "email": "user@example.com",
  "password": "securePassword123",
  "name": "Jane Doe"
}

{
  "success": true,
  "user": { "id": "uuid", "email": "user@example.com" },
  "session": { "access_token": "...", "refresh_token": "..." }
}

Sign in with email and password. Rate limited: 5 attempts per 15 minutes.

{
  "email": "user@example.com",
  "password": "securePassword123"
}

Initiate Google OAuth login flow. Redirects to Google consent screen.

Sign out and invalidate the current session. Requires authentication.

Create a new wish. Subject to AI moderation. Rate limited: 10 per hour.

{
  "title": "Dog walker in San Francisco",
  "description": "Need someone to walk my golden retriever 3x/week",
  "category": "pet-care",
  "budget_max": 150,
  "budget_type": "fixed",
  "location_text": "San Francisco, CA",
  "urgency": "normal",
  "visibility": "public"
}

{
  "id": "uuid",
  "title": "Dog walker in San Francisco",
  "status": "pending_moderation",
  "protocol_type": "ap2",
  "moderation_score": 92,
  "created_at": "2025-11-08T12:00:00Z"
}

List the authenticated user's wishes.

Retrieve a specific wish by ID. Public wishes are accessible without authentication.

Update a wish. Only the owner can update. Re-triggers moderation if content changes.

Browse public wishes. Supports search, category filtering, and location-based results.

Create an intent mandate with budget cap. ECDSA-signed for tamper prevention.

{
  "wish_id": "uuid",
  "max_amount": 150.00,
  "currency": "USD",
  "mandate_type": "intent"
}

Create a cart mandate from an intent mandate with specific items and amounts.

Execute payment from a cart mandate via Google Pay.

List, retrieve, and manage mandates. Supports filtering by type and status.

Create a Stripe checkout session for a wish. Uses SharedPaymentToken for scoped authorization.

{
  "wish_id": "uuid",
  "amount": 140.00,
  "currency": "usd",
  "success_url": "https://wish.now/confirm-payment/{id}",
  "cancel_url": "https://wish.now/wishes/{id}"
}

Complete payment processing. Uses idempotency keys to prevent double-charging (24-hour cache).

Create a SharedPaymentToken with merchant scope, max amount, and expiry for delegated payments.

JavaScript (fetch)

const response = await fetch('https://api.soft.house/api/wishes', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    title: 'Dog walker in San Francisco',
    category: 'pet-care',
    budget_max: 150
  })
});
const wish = await response.json();

Python (requests)

import requests

response = requests.post(
    'https://api.soft.house/api/wishes',
    headers={'Authorization': f'Bearer {token}'},
    json={
        'title': 'Dog walker in San Francisco',
        'category': 'pet-care',
        'budget_max': 150
    }
)
wish = response.json()

cURL

curl -X POST https://api.soft.house/api/wishes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"title":"Dog walker in SF","budget_max":150}'