API & MCP Docs

Overview

Submit an asset description and get a transparent Floor / Expected / Upside valuation, with the reasoning, sourced comparables, and adjustable assumptions behind it. Valuations run real web research, so they are asynchronous: create one, then poll for the result.

Base URL: https://valuemysurplus.vercel.app

Authentication

All API requests authenticate with an account API key via a Bearer token. Create and manage keys in your account settings. Keep your secret key server-side — it grants full access to your account's valuations.

Authorization: Bearer vms_sk_your_key_here

Create a valuation

POST /api/v1/valuations — returns 202 Accepted immediately with a record in researching status. The engine runs in the background; poll the record until its status becomes complete.

curl -X POST https://valuemysurplus.vercel.app/api/v1/valuations \
  -H "Authorization: Bearer vms_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Used 1500 kVA oil-filled pad-mount transformer, 13.8kV/480V",
    "quantity": 1,
    "condition": "used-good",
    "category": "transformer",
    "country": "United States",
    "region": "TX"
  }'

Request fields:

description   string   required   what the asset is (type, specs, scale)
quantity      integer  default 1  number of units
condition      enum     default "used-good"  new | used-good | used-fair | salvage
category       string   optional   category hint (e.g. "OCTG", "valves")
country        string   optional   location country
region         string   optional   location region/city

Response (202):

{ "id": "a4997bbe-...", "status": "researching", ... }

Retrieve / poll a valuation

GET /api/v1/valuations/{id} — poll every few seconds until status is complete or failed (typically under two minutes).

curl https://valuemysurplus.vercel.app/api/v1/valuations/a4997bbe-... \
  -H "Authorization: Bearer vms_sk_..."

Response (200, when complete):

{
  "id": "a4997bbe-...",
  "status": "complete",
  "result": {
    "currency": "USD",
    "floorValue": 32000,
    "expectedValue": 52000,
    "upsideValue": 72000,
    "scrapFloor": 7500,
    "confidence": "medium"
  },
  "reasoning": "Reconditioned asking ref $77,100 × condition 0.85 × recovery 0.80 ...",
  "formulaExplanation": "...",
  "comparables": [
    { "description": "Reconditioned 1500 kVA pad-mount", "unitPrice": 77100,
      "currency": "USD", "sourceUrl": "https://...", "similarityScore": 0.9 }
  ],
  "assumptions": [
    { "key": "recovery_rate", "label": "Recovery rate", "value": 0.8,
      "defaultValue": 0.8, "kind": "rate" }
  ],
  "pipeline": [ { "key": "identify", "title": "Identify the asset", "summary": "..." } ],
  "engine": { "source": "engine", "model": "claude-sonnet-4-6" }
}

List valuations

GET /api/v1/valuations — returns recent valuations for the authenticated account.

{ "data": [ { "id": "...", "status": "complete", "result": { ... } } ] }

Errors

401  unauthorized      missing or invalid API key
400  invalid_request   body failed validation (see "details")
404  not_found         valuation doesn't exist or isn't on your account
500  internal_error    something went wrong on our end

MCP server (for AI agents)

The same engine is available as an MCP server, so AI agents can value surplus as a tool call. It runs over stdio and wraps the REST API.

Add it to an MCP client (e.g. Claude Desktop / Claude Code):

{
  "mcpServers": {
    "valuemysurplus": {
      "command": "npx",
      "args": ["-y", "@valuemysurplus/mcp"],
      "env": {
        "VMS_API_KEY": "vms_sk_...",
        "VMS_API_URL": "https://valuemysurplus.vercel.app"
      }
    }
  }
}

Tools exposed:

value_asset      Value a surplus asset.
                 Inputs: description (required), quantity, condition,
                 category, country, region.
list_valuations  List recent valuations for the account.

The MCP tools call the same async engine; value_asset returns the created valuation, which reaches complete shortly after.