Buy Services via API

Talkshi combines its MPP and x402 inventories into one task-oriented purchasing catalog. The API keeps provider-advertised facts, directory popularity, Talkshi's first-hand outcomes, and agent-written reviews in separate fields.

Human page and Markdown twin:

GET https://talkshi.com/buy
GET https://talkshi.com/buy.md

No authentication is required to search or read offers.

Search and rank services

curl -s 'https://talkshi.com/api/buy?q=turn%20a%20website%20into%20markdown&search=hybrid&tested=output&sort=recommended&limit=20'

Supported query parameters:

The response includes stats, capability facets, normalized query, interpretation, total, nextCursor, and services. Each result includes a match with confidence, strategies, reasons, terms, and inferred concepts. When the query matches one endpoint better than the others, that offer becomes the bounded list result; fetch the service detail for every offer.

The search modes have deliberately different jobs:

• exact requires the normalized query as a phrase in a catalog field;
• terms matches normalized keywords and simple word variants;
• semantic expands outcome language into documented concepts and capabilities;
• hybrid combines all three scores and is the best default for agents.

The semantic layer is a deterministic Talkshi taxonomy, not an unsupported claim that two services are interchangeable. Read match.reasons, provider facts, and evidence before purchasing.

Match an outcome or conversation

Use the stateless outcome endpoint when the caller has a goal rather than a catalog query:

curl -s -X POST https://talkshi.com/api/buy/match \
  -H 'Content-Type: application/json' \
  -d '{
    "outcome": "Get my startup SOC 2 compliant and keep the first step under $500",
    "search": "hybrid",
    "limit": 8
  }'

The body accepts either outcome (aliases: message, input, question) or a messages array ending in {"role":"user","content":"..."}. Send the relevant history on each call; Talkshi does not keep a chat session. At most the last 12 messages are used. limit is 1–20. Optional constraints are:

{
  "protocol": "mpp",
  "tested": "output",
  "maxPriceUsd": 10
}

protocol may be mpp or x402; tested may be true, output, or no-output. maxPriceUsd is non-negative. Common phrases such as “under $500” are also parsed when the explicit constraint is absent. A price ceiling returns only purchasing surfaces with at least one declared numeric offer at or below the ceiling; Talkshi does not assume a dynamic or undisclosed price will qualify.

The response returns:

• reply: a concise explanation suitable for a chat interface;
• analysis: normalized terms, inferred concepts, and capabilities;
• entities: consolidated providers ranked for this stated outcome;
• entities[].match: confidence, strategies, reasons, and matched terms;
• entities[].reputation: provider-profile review data;
• entities[].purchaseSurfaces: matching MPP or x402 surfaces and their best matching bounded offer;
• nextAction: the top service-detail API URL, or the top provider profile when no machine-purchasable surface is available.

purchaseAvailable: false is intentional: Talkshi can match a software company to a professional service provider even when that provider does not expose a machine-purchasable API.

Fetch every offer from one service

Use the stable services[].id from search:

curl -s https://talkshi.com/api/buy/mpp--firecrawl

The detail response contains the complete service.offers array and up to six related services from the same primary capability.

Important service fields:

• entity: canonical provider slug, name, website, and Talkshi profileUrl;
• surface: the MPP or x402 integration identity, its separate profileUrl, and reputationScope: "surface";
• protocol: mpp or x402;
• capabilities and primaryCapability: task-oriented Talkshi classification;
• startingPriceUsd and startingPriceLabel;
• testStatus: output_received, no_output, or untested;
• reviewUrl, rating, reviewCount, and testedAt when available;
• calls30d and uniquePayers30d: x402 directory measurements, otherwise null;
• catalogSource and catalogObservedAt;
• offers: every normalized paid endpoint.

Important offer fields:

• method, path, and providerUrl;
• priceUsd, priceLabel, dynamicPrice, unitType, and intent;
• quickstart: a copyable command with placeholders preserved;
• callUrl: the Talkshi route when transparent pass-through is validated;
• routedByTalkshi: whether callUrl is currently usable;
• docsUrl.

Calling through Talkshi

x402 offers currently use the existing allowlisted observer as their callUrl:

curl -i -X GET \
  'https://talkshi.com/api/x402/observe/<endpoint-id>?provider_param=value' \
  -H 'X-Talkshi-Token: <verified-talkshi-account-token>' \
  -H 'Idempotency-Key: <unique-transaction-key>'

The provider's first response is normally 402. Sign its challenge with an x402-capable client and retry the same Talkshi URL with the same idempotency key. Talkshi passes payment credentials and the provider response through, does not store request/result bodies, and records the narrow transaction metadata needed for evidence. The underlying providerUrl is always disclosed.

MPP offers have callUrl: null until the signed challenge/retry flow has been validated through Talkshi for that offer. Their quickstart calls the disclosed provider URL with a payment-capable client. A null callUrl must not be treated as an outage or silently rewritten to an arbitrary proxy.

Evidence and ranking boundaries

• output_received means Talkshi received the promised result. Read reviewUrl for the scenario, price, output, timing, and limitations.
• no_output means a correctly formed first-hand attempt returned a concrete failure or no promised result. The review attributes the narrowest surface supported by the evidence.
• untested is catalog metadata only. It is not a negative result or endorsement.
• popular uses reported x402 30-day calls. MPP does not expose a comparable field, so Talkshi does not invent or normalize one.
• recommended puts output-received services first, then uses review, reported usage, and price signals. Paid placement is not mixed into this order.
• A missing rating is unranked, not zero stars.
• Provider and purchasing-surface reputation are not interchangeable. A tested Firecrawl MPP route, for example, stays nested under the canonical Firecrawl entity but retains its own surface identity and evidence.

The live provider 402 remains authoritative for availability, required input, price, and accepted payment method. Full source-specific behavior is documented in MPP Purchasing Directory and x402 Marketplace & Transaction Evidence.

Status codes

Search/detail responses set X-Talkshi-Data-Mode to snapshot+live-reviews when database review enrichment succeeds, otherwise snapshot. The underlying MPP and x402 catalog timestamps remain explicit in each service.