Listings¶

A listing is a seller's offer of capacity. Creating one produces a draft; tier and reliability are derived by the server, never typed by the seller. A draft goes live after the machine is measured and you call revalidate.

Create a listing¶

POST /api/v1/listings/create (identical to POST /api/v1/listings). REST and the MCP post_listing / create_listing tools share one schema.

Field	Type	Notes
`capability`	object	Required. Validated by the engine.
`title`	string	1–160 characters.
`notes`	string	Optional, up to 4,000 characters. Contact details are stripped from public views.

curl -X POST https://api.example/api/v1/listings/create \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rack-01-listing" \
  -d @listing.json

listing.json (this is the shape used in Pewter's own tests):

{
  "title": "8x H100 rack",
  "notes": "demo",
  "capability": {
    "schema_version": "1",
    "kind": "gpu",
    "gpu": { "model": "H100", "canonical": "H100", "vram_gb": 80, "count_per_node": 8, "nodes": 1, "intra": "nvlink", "inter": "ib_400g" },
    "network": { "up_mbps": 10000, "down_mbps": 10000, "class": "datacenter", "public_ip": true },
    "region": { "country": "US" },
    "availability": { "from": "2026-10-01T00:00:00.000Z", "until": null, "schedule": "24x7", "min_hours": 1 },
    "price": { "unit": "gpu_hr", "amount_usd": 2, "negotiable": false },
    "contract_type": "rental"
  }
}

Response 201:

{ "data": { "id": "LST-…", "status": "draft", "title": "8x H100 rack", "capability": { "…": "…" }, "created_at": "…", "updated_at": "…" } }

Sending the request without a token returns 401. Replaying the same Idempotency-Key returns the same listing.

Other listing routes¶

Method & path	Purpose
`GET /listings`	Your own listings (opt-in paging).
`POST /listings/{id}/revalidate`	Ask Pewter to validate the listing against the machine's measurements.
`GET /listings/{id}/verification`	Validation state.
`GET /listings/{id}/node`	Machine linked to the listing.
`POST /listings/{id}/maintenance`	Announce maintenance.
`POST /listings/{id}/drain`	Stop taking new work.
`GET /capacity`	Other sellers' live capacity, anonymous (`seller_ref`, your own rows flagged `is_own: true`). Query: `kind`, `gpu`, `region`, `max_price`, `verification_min` (`S0`–`S3`), `limit`, `cursor`.