Beta Early access — you're seeing this before public launch. Browse our books See terms of early access

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
Full REST integration~15 minutesAPI key + any HTTP client — no SDK needed
With TypeScript SDKComing soonNot yet on npm — the REST API covers everything today

Track 1: Sandbox — 2 Minutes, Zero Setup

The public sandbox runs read-only registry queries against live data. No signup, no API key, no SDK. It’s the same endpoint powering the “Try it now” box on the homepage.

Endpoint: POST https://api.soft.house/sandbox/call Auth: none required — 10 calls/hour per IP Operations (read-only): registry.search, registry.get, status.check

Step 1 — Search the skills registry (cURL)

curl -X POST https://api.soft.house/sandbox/call \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "mcp",
    "operation": "registry.search",
    "params": { "q": "checkout" }
  }'

Expected response:

{
  "result": {
    "skills": [
      { "skill_id": "soft-house.acp_checkout", "protocol": "acp", "certification_tier": "canonical" }
    ]
  },
  "sandbox": true,
  "calls_remaining": 9
}

That’s it — you just made a real, live API call.

Step 2 — Fetch one skill’s contract

curl -X POST https://api.soft.house/sandbox/call \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "mcp",
    "operation": "registry.get",
    "params": { "skill_id": "soft-house.acp_checkout" }
  }'

The sandbox is a read-only preview of the registry. Full protocol operations (creating wishes, mandates, and checkouts) require the authenticated API — see below.

Track 2: Real API Key — 5 Minutes

  1. Sign in at the Developer Dashboard with your soft.house account.
  2. Click Create Key. Keys are read-only by default (wishes:read); check “Allow creating & updating wishes” if you also want wishes:write.
  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. Make your first authenticated call — list your wishes. Any key can do this:
curl https://api.soft.house/api/wishes \
  -H "Authorization: Bearer $SOFT_HOUSE_API_KEY"
  1. Create a wish (requires a key with wishes:write):
curl -X POST https://api.soft.house/api/mcp/wishes \
  -H "Authorization: Bearer $SOFT_HOUSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Laptop under $1500",
    "description": "Looking for a developer laptop, 16GB+ RAM, good battery life.",
    "category": "electronics",
    "budget": 1500
  }'

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

Key scope & lifetime. API keys authenticate against the wish endpoints (GET /api/wishes, GET|POST /api/mcp/wishes, PATCH /api/mcp/wishes/:id) according to their granted scopes, and expire after 90 days by default (365-day max). Payment, mandate, and account-management endpoints deliberately do not accept API keys — those require an OAuth session. A key that is expired, revoked, or missing the required scope gets a 401 with code API_KEY_UNAUTHORIZED.

Track 3: TypeScript SDK — Coming Soon

@pragma/sdk-soft-house is not yet on npm — npm install @pragma/sdk-soft-house currently fails with E404. The SDK source is complete and lives in the monorepo; the npm publish is operator-gated. Everything the SDK will do is available today through the REST API (Tracks 1 and 2 above).

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

MilestoneStatusWhat it enables
Sandbox API✅ LiveZero-friction evaluation (this guide)
Documentation✅ LiveProtocol guides, API reference
Self-service API keys✅ LiveInstant key creation in Dashboard
Interactive API Reference✅ LiveScalar-powered OpenAPI explorer
TypeScript SDK🔜 Coming soonBuilt in the monorepo — npm publish is pending; API preview
Python SDK🔜 Coming soonBuilt in the monorepo — PyPI publish is pending; API preview

Next Steps

Introduction Authentication