Quickstart

Make your first API call in 2 minutes using the sandbox — no account or SDK required. Full integration in under 15 minutes.

Time to First Transaction

This guide gets you to a real API response as fast as possible:

PathTimeRequires
Sandbox (this guide)~2 minutesNothing — no signup, no key
With real API key~5 minutesSign in + create key in Dashboard
With TypeScript SDK~15 minutesAPI key + npm install @soft-house/sdk

Track 1: Sandbox — 2 Minutes, Zero Setup

The sandbox returns realistic mock data for all endpoints. No signup. No API key. No SDK install. Write operations are accepted but no-ops.

Base URL: https://sandbox.api.soft.house Auth: Not required for sandbox requests Data: Realistic mock responses — all writes are no-ops

Step 1 — Create a wish (cURL)

curl -X POST https://sandbox.api.soft.house/wishes \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Find me a laptop under $1500",
    "budget": { "max": 1500, "currency": "USD" },
    "protocol": "auto"
  }'

Expected response:

{
  "id": "wish_sandbox_abc123",
  "status": "active",
  "query": "Find me a laptop under $1500",
  "budget": { "max": 1500, "currency": "USD" },
  "protocol": "ap2",
  "created_at": "2026-01-20T10:30:00Z"
}

That’s it — you just made your first API call.

Step 2 — List wishes

curl https://sandbox.api.soft.house/wishes \
  -H "Content-Type: application/json"

Step 3 — Check protocol detection

The protocol: "auto" field lets the API select the best protocol. To test explicit protocol selection:

curl -X POST https://sandbox.api.soft.house/wishes \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Order groceries delivery",
    "budget": { "max": 80, "currency": "USD" },
    "protocol": "acp"
  }'

Track 2: Real API Key — 5 Minutes

  1. Sign in at the Developer Dashboard with your soft.house account.
  2. Click Create Key to generate an API key instantly.
  3. Copy the key (shown only once) and store it as an environment variable:
export SOFT_HOUSE_API_KEY=mcp_YOUR_USER_ID_YOUR_TOKEN
  1. Use https://api.soft.house (not sandbox) with the Authorization header:
curl -X POST https://api.soft.house/wishes \
  -H "Authorization: Bearer $SOFT_HOUSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Find me a laptop under $1500",
    "budget": { "max": 1500, "currency": "USD" },
    "protocol": "auto"
  }'

API keys are shown only once when created. Store them securely in environment variables.

Track 3: TypeScript SDK — 15 Minutes

Install the official SDK:

npm install @soft-house/sdk

Then create your first wish with full type safety:

import { SoftHouse } from '@soft-house/sdk';

const soft = new SoftHouse({
  apiKey: process.env.SOFT_HOUSE_API_KEY!,
});

// Create a wish — protocol auto-detected
const wish = await soft.wishes.create({
  query: 'Find me a laptop under $1500',
  budget: { max: 1500, currency: 'USD' },
});

console.log('Wish created:', wish.id);
console.log('Status:', wish.status);

The SDK includes typed resources for all API endpoints:

// Mandates (AP2 + ACP)
const mandate = await soft.mandates.create({
  type: 'intent',
  protocol_type: 'ap2',
  max_amount: 1500,
});

// Payments (idempotency key required)
const payment = await soft.payments.create({
  mandate_id: mandate.id,
  amount: 119999,
  idempotency_key: 'pay_unique_456',
});

See the full TypeScript SDK reference for all resources and configuration options.

TTFT Roadmap

MilestoneStatusWhat it enables
Sandbox API✅ LiveZero-friction evaluation (this guide)
Documentation✅ LiveProtocol guides, API reference
Self-service API keys✅ LiveInstant key creation in Dashboard
TypeScript SDK v0.1✅ Livenpm install @soft-house/sdk with full types
Interactive API Reference✅ LiveScalar-powered OpenAPI explorer
Python SDK🔄 Nextpip install soft-house

Next Steps

Introduction Authentication