API documentation

One paid endpoint, free quotes, free retrieval. Machine-readable: /openapi.json, /llms.txt, /api/v1/coverage, /api/v1/pricing.

1 · Quote (free)

POST the task without payment headers. You get HTTP 402 with the x402 requirement (0.053 USDC), the normalised task (category, quantity, unit, language pair, pricing basis) and the sources that would be consulted. Nothing is stored and no source is called. A task that maps to no category, or to several equally, is refused here with AMBIGUOUS_TASK (422) and candidate categories.

POST https://auctionpriceintelligence.online/api/v1/price-intelligence
Content-Type: application/json

{
  "task": {
    "description": "Translate 10,000 English words into Spanish",   // any language, kept verbatim
    "quantity": 10000, "unit": "word",                                  // optional; parsed from text otherwise
    "source_language": "en", "target_language": "es",                   // optional
    "category": "translation",                                          // optional: translation | interpretation | transcription | proofreading | content_writing | web_extraction | …
    "pricing_basis": "fixed"                                            // optional: fixed | hourly
  },
  "currency": "USD",          // USD | USDC | EUR | GBP | CAD | AUD | INR | JPY | PLN | CHF
  "convert_currencies": true, // ECB reference rates, with provenance per observation
  "lookback": "auto",         // auto | 24h | 7d | 30d | 90d | 1y | all
  "market": "auto",           // auto | agent_marketplace | freelance_marketplace | public_procurement
  "role": "customer"          // optional: customer | executor (wording only)
}
// Shortest form: {"task": "Extract product name, price and availability from 500 product pages"}

2 · Pay and run

Resend the identical body with PAYMENT-SIGNATURE (base64 x402 v2 payload, exact scheme, USDC) and an Idempotency-Key (16–128 characters). The same key never charges twice; one payment authorises exactly one query; a different body under the same key is refused (409).

{
  "query_id": "apq_…",
  "status": "PRICE_ESTIMATE_AVAILABLE",
  "currency": "USD",
  "estimated_market_price": { "low": "15.00", "median": "86.00", "high": "352.00" },
  "sample_size": 31, "confidence": "MEDIUM",
  "basis": "AWARDED_NEGOTIATED_ONLY",
  "market": { "segment": "FREELANCE_MARKETPLACE", "evidence_group": "OUTCOMES", "unit": "job",
              "range_basis": "P10_P90", "recency_weighted_median": "…", "percentiles": { … },
              "dispersion": { "relative_iqr": 1.2 }, "outliers": { … }, "mechanism_mix": { … } },
  "confidence_factors": { "sample_size": 31, "mean_similarity": 0.62, "share_within_90_days": 1, … },
  "observed_period": { "from": "…", "to": "…" },
  "evidence_mix": { "completed_paid": 0, "completed": 0, "awarded": 31, "closed_winning_bid": 0,
                    "historical_bids": 0, "active_bids": 0, "customer_budget": 0, "asking_price": 0 },
  "distributions": [ { "segment": "FREELANCE_MARKETPLACE", "evidence_group": "BIDS", "summary": { … } },
                     { "segment": "PUBLIC_PROCUREMENT", "evidence_group": "OUTCOMES", "summary": { … } } ],
  "by_marketplace": [ … ], "by_mechanism": [ … ], "by_currency": [ … ],
  "unit_prices": { "unit": "word", "comparables_with_quantity": 0, "per_unit": null, "note": "…" },
  "trend": { "direction": "STABLE", "comparison": "30-day median vs previous 30-day median", … },
  "competition": { "median_bids_per_auction": 5, "median_average_bid_below_max_budget_pct": 41.4, … },
  "price_reduction": { "vs_stated_max_budget_pct": null, "meaning": "…" },
  "comparables": [ { "source": "freelancer", "source_reference": "https://www.freelancer.com/projects/…",
                     "title": "…", "original_language": "en", "event_at": "…", "mechanism": "NEGOTIATED",
                     "lifecycle": { "winner_selected": true, "work_completed": true, "payment_completed": null },
                     "similarity": 0.75, "similarity_factors": { … },
                     "used": [ { "price_type": "AWARDED_PRICE", "evidence_class": "AWARDED",
                                 "original_amount": "20", "original_currency": "USD", "amount": "20.00",
                                 "conversion": null, "derivation": "…", "outlier": "NORMAL" } ] } ],
  "comparables_total": 105, "comparables_url": "https://auctionpriceintelligence.online/api/v1/queries/apq_…/comparables",
  "sources": [ { "source": "ted", "status": "CACHED", "fetched_at": "…" }, … ],
  "freshness": { "generated_at": "…", "latest_observation_at": "…", "oldest_used_observation_at": "…" },
  "currency_handling": { "requested": "USD", "reporting": "USD", "conversions_applied": 60, "rate_date": "…" },
  "interpretation": { "summary": "…", "for_customer": "…", "for_executor": "…" },
  "unknowns": [ … ], "limitations": [ … ],
  "versions": { "pricing_model_version": "…", "normalization_version": "…", "stats_version": "…" },
  "payment": { "charged": true, "status": "settled", "amount": "0.053", "currency": "USDC", "transaction": "0x…" }
}

3 · Retrieve (free)

GET /api/v1/queries/{query_id} and /api/v1/queries/{query_id}/comparables with Authorization: Bearer <Idempotency-Key>. The stored snapshot is returned exactly as generated (with its algorithm versions), for 90 days.

Results

PRICE_ESTIMATE_AVAILABLE — At least 5 comparable outcomes (or, failing that, bids) in one market segment: low/median/high, sample size, confidence, evidence mix, comparables. Charged.
LIMITED_DATA — 1–4 primary comparables (or only budgets): the comparables are returned, no statistic is manufactured. Charged.
INSUFFICIENT_COMPARABLES — The category has observations, but none passed the hard filters (pricing basis, quantity band, similarity). Charged — real research was done.
NO_COMPARABLE_DATA — Every relevant source answered and no comparable auction exists in coverage. No unrelated price is substituted. Charged.
AMBIGUOUS_TASK — The task maps to no category or to several equally. Refused before payment (HTTP 422) with candidate categories. Never charged.
SOURCE_UNAVAILABLE — Sources could not be read and nothing is stored for the category, so absence of data cannot be claimed. Not charged.
UNABLE_TO_ESTIMATE — Comparables exist only in currencies that cannot be converted under your settings. Not charged.

Evidence model

Price types: CUSTOMER_MAX_BUDGET CUSTOMER_MIN_BUDGET BUYER_ESTIMATED_VALUE FRAMEWORK_MAXIMUM ASKING_PRICE BID BID_AVERAGE BID_LOWEST BID_HIGHEST WINNING_BID AWARDED_PRICE COMPLETED_PRICE PAID_PRICE . Evidence classes, strongest first: COMPLETED_PAID COMPLETED AWARDED CLOSED_WINNING_BID HISTORICAL_BIDS ACTIVE_BIDS CUSTOMER_BUDGET ASKING_PRICE . Outcomes, bids and budgets are separate distributions; fixed totals and hourly rates are never pooled; public-procurement contracts and marketplace jobs are separate segments. Statistics are exact decimals (no floating point), percentiles use linear interpolation (PERCENTILE.INC), extreme outliers are excluded transparently, and no language model produces or selects any number.

Errors

Stable envelope {"error": {"code", "message", "details?"}}. 400 invalid, 402 payment, 409 idempotency/replay, 413 body over 16 KB, 415 content type, 422 ambiguous/unsupported, 429 rate limit, 503 not configured or payment provider unavailable — none of these is charged.