Developer platform
v1 stable
seller intelligence preview

FairClose Public Marketplace API

Use a simple, public integration layer for listings, search, categories, and lot detail. It is designed for partner sites, content embeds, lightweight storefront integrations, and discovery widgets.

Meta endpoint

Discover the base URL, capabilities, docs, and SDK links.

OpenAPI JSON

Pull a machine-readable API reference for tooling and partners.

Structure guide

Download the partner-ready endpoint, auth, embed, and webhook contract.

JavaScript SDK

Drop-in client for websites, widgets, storefronts, and custom frontends.

Python SDK

Use the same public API from automations, data scripts, and integrations.

API structure document

Use this as the implementation contract for external sites connecting to FairClose. It includes production base URLs, public and partner endpoints, X-API-Key authentication, signed embeds, webhook expectations, cache behavior, error handling, and a provenance-registry integration pattern aligned with Arquivis-style APIs.

Download guide

Quickstart

Base URL: https://fairclose-market-2-r-1773580321.emergent.host/api/v1/public

Authentication: The current public integration layer is read-only and does not require auth.

Partner layer: Use admin-issued X-API-Key credentials for authenticated partner endpoints, usage tracking, webhooks, and signed embeds.

Versioning: Production integrations should pin to /api/v1/...; preview capabilities graduate into stable only after docs and schema notes are updated.

Scopes: Partner read endpoints require read; signed embed creation requires write.

Rate limits: Authenticated partner responses now include minute and day rate-limit headers for safer production integrations.

Best fit: Search widgets, featured lots, category landing feeds, and partner content embeds.

Formats: JSON over HTTPS with predictable pagination and stable public-safe fields.

Quick curl

curl 'https://fairclose-market-2-r-1773580321.emergent.host/api/v1/public/search?q=Rolex&limit=3'

Versioning policy

VersionStatusContract
v1StablePublic marketplace and partner endpoints. Backward-compatible additive changes only.
vNext previewControlled rolloutSeller intelligence expansion and operational alert-routing adapters before promotion into a stable version.

Compatibility checklist

  • • Pin production traffic to /api/v1 and monitor meta endpoint version fields during releases.
  • • Treat preview seller-intelligence and alert-routing adapters as opt-in until the version table promotes them.
  • • Prefer additive parsing for JSON fields so partner clients stay resilient as new capabilities ship.

Core endpoints

MethodPathUse case
GET/metaAPI metadata, docs links, and SDK download URLs
GET/openapi.jsonOpenAPI-style reference for the public integration surface
GET/categoriesMarketplace categories for navigation and filters
GET/listingsPublic listing feed with pagination, sorting, and category filters
GET/search?q=watchKeyword search for marketplace listings
GET/listings/{listing_id}Single lot detail for embeds, cards, or partner pages

Partner endpoints and signed embeds

When you need API-key tracking, webhook subscriptions, or signed listing embeds, move from the public layer to the partner layer.

MethodPathUse case
GET/partner/metaAuthenticated partner metadata and feature discovery
GET/partner/listingsKey-authenticated listing feed with usage logging
GET/partner/listings/{listing_id}Key-authenticated single listing detail
GET/partner/search?q=watchKey-authenticated search for partner use cases
POST/partner/embed-signaturesGenerate signed listing embed URLs for third-party sites

Auth header

X-API-Key: fc_live_your_partner_key

Signed embed example

<iframe
  src="https://fairclose-market-2-r-1773580321.emergent.host/embed/listing/{listing_id}?key_id=...&expires=...&sig=..."
  title="FairClose listing embed"
  loading="lazy"
  style="width:100%;max-width:420px;height:520px;border:0;"
></iframe>

Provenance and registry integrations

Provenance systems such as Arquivis can link records to FairClose lots by exchanging API keys, using stable listing URLs, and verifying lifecycle webhooks with shared HMAC secrets.

1

Exchange keys

FairClose issues a partner key; the registry issues its read API key and webhook secret.

2

Link records

Use listing_id and listing_url as stable partner references on both platforms.

3

Verify changes

Process record/listing lifecycle webhooks idempotently and validate HMAC signatures.

Seller intelligence endpoints

Private beta

These seller-facing AI endpoints are useful for private tooling, internal dashboards, and managed seller workflows. They require an authenticated seller session and are not part of the public partner layer yet.

MethodPathUse case
POST/api/v1/pricing-ai/suggestAuthenticated seller pricing suggestions using live market comps
POST/api/v1/pricing-ai/smart-advisorSeller reserve/BIN strategy advice with reserve-price recommendations
GET/api/v1/ai/pricing-insights/{category_id}Seller pricing intelligence for category-level comps and sell-through

JavaScript SDK

Download
import { FairCloseClient } from '/sdk/fairclose-sdk.js';

const client = new FairCloseClient({
  baseUrl: 'https://fairclose-market-2-r-1773580321.emergent.host',
  apiKey: 'fc_live_your_partner_key'
});

const results = await client.searchListings({ q: 'Rolex', limit: 6 });
const embed = await client.createListingEmbedSignature({
  listingId: 'listing_id_here',
  theme: 'sand'
});

console.log(results.items, embed.embed_url);

Python SDK

Download
from fairclose_sdk import FairCloseClient

client = FairCloseClient(
    base_url='https://fairclose-market-2-r-1773580321.emergent.host',
    api_key='fc_live_your_partner_key'
)
results = client.search_listings(q='Rolex', limit=6)
embed = client.create_listing_embed_signature(listing_id='listing_id_here', theme='sand')
print(results['items'], embed['embed_url'])