API Overview

Base URL

All API requests are made to:

https://api.soft.house

Authentication

Include your API key in every request:

curl https://api.soft.house/wishes \
  -H "Authorization: Bearer sk_live_..."

Request Format

• Content-Type: application/json
• Method: Standard REST (GET, POST, PUT, DELETE)
• Encoding: UTF-8

Response Format

All responses follow a consistent structure:

{
  "data": { },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-01-20T10:30:00Z"
  }
}

Error Responses

{
  "error": {
    "code": "validation_error",
    "message": "budget.max must be a positive number",
    "field": "budget.max"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Protocol Detection

The API automatically detects which protocol to use based on request headers:

Header	Protocol
X-AP2-Mandate-ID	AP2
X-ACP-Session-ID	ACP
Default	Standard REST

You can also explicitly set the protocol:

curl https://api.soft.house/wishes \
  -H "Authorization: Bearer sk_live_..." \
  -H "X-Protocol: ap2"

Rate Limits

Endpoint	Limit
General API	100 requests/minute per user
Login attempts	5 per 15 minutes per IP
Mandate creation	10 per hour per user

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1706183400

Pagination

List endpoints support cursor-based pagination:

curl "https://api.soft.house/wishes?limit=10&offset=0"

Parameter	Type	Default	Description
limit	number	10	Items per page (max 100)
offset	number	0	Number of items to skip

Versioning

The API is currently at v2. Version is included in responses:

X-API-Version: 2

Available Endpoints

Resource	Description
Wishes	Create and manage wishes
Mandates	AP2/ACP mandate management
Payments	Payment processing
Users	User management
Webhooks	Event notifications