Wishes API

Create a Wish

POST /wishes

Request Body

Parameter	Type	Required	Description
query	string	Yes	Natural language description
budget	object	No	Budget constraints
budget.max	number	No	Maximum budget
budget.currency	string	No	Currency code (default: USD)
protocol	string	No	Protocol preference: ap2, acp, auto
category	string	No	Product category
metadata	object	No	Custom key-value pairs

Example

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

Response (201 Created)

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

List Wishes

GET /wishes

Query Parameters

Parameter	Type	Default	Description
limit	number	10	Items per page
offset	number	0	Offset for pagination
status	string	-	Filter by status

Response (200 OK)

{
  "data": [
    {
      "id": "wish_abc123",
      "status": "active",
      "query": "Find me a laptop under $1500",
      "budget": { "max": 1500, "currency": "USD" },
      "protocol": "ap2",
      "created_at": "2026-01-20T10:30:00Z"
    }
  ],
  "meta": { "total": 12, "limit": 10, "offset": 0 }
}

Get a Wish

GET /wishes/:id

Returns a single wish by ID.

Update a Wish

PUT /wishes/:id

Request Body

Parameter	Type	Description
query	string	Updated search query
budget	object	Updated budget
status	string	New status
metadata	object	Updated metadata

Delete a Wish

DELETE /wishes/:id

Returns 204 No Content on success.

Wish Statuses

Status	Description
active	Currently being processed
pending	Waiting for agent assignment
fulfilled	Successfully completed
cancelled	Cancelled by user
expired	Exceeded time limit