Quickstart

Time to First Transaction

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

Path	Time	Requires
Sandbox (this guide)	~2 minutes	Nothing — no signup, no key
With real API key	~5 minutes	Sign in + create key in Dashboard
Full REST integration	~15 minutes	API key + any HTTP client — no SDK needed
With TypeScript SDK	Coming soon	Not yet on npm — the REST API covers everything today

---

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.

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

4. 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"
  }'

---

Track 3: TypeScript SDK — Coming Soon

Once published, you will create your first wish with full type safety:

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

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 will include 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 TypeScript SDK preview for the full planned API surface and configuration options.

---

TTFT Roadmap

Milestone	Status	What it enables
Sandbox API	✅ Live	Zero-friction evaluation (this guide)
Documentation	✅ Live	Protocol guides, API reference
Self-service API keys	✅ Live	Instant key creation in Dashboard
Interactive API Reference	✅ Live	Scalar-powered OpenAPI explorer
TypeScript SDK	🔜 Coming soon	Built in the monorepo — npm publish is pending; API preview
Python SDK	🔜 Coming soon	Built in the monorepo — PyPI publish is pending; API preview

---

Next Steps

• Authentication — Learn about API keys, OAuth flows, and token scopes
• Wishes API — Full reference for wish operations
• API Reference — Interactive OpenAPI documentation
• TypeScript SDK preview — Planned SDK surface (not yet on npm)
• Protocol Guides — Deep-dives on AP2, ACP, TAP, MCP, and A2A