Public API
Use Tradebird's versioned public API for marketplace retrieval.
The public API is the HTTP surface behind the public marketplace. It is versioned under /api/v1.
Base URL
Set the API base URL once and reuse it in requests:
TRADEBIRD_API_BASE_URL="https://api.tradebird.ai/api/v1"Public endpoints
| Method | Path | Auth | Purpose |
|---|---|---|---|
GET | /health | No | Health check. |
GET | /marketplace/listings/search | No | Search current public Product and Service listings. |
GET | /marketplace/search/suggestions | No | Suggest typed Category, Product, Service, and Seller URLs. |
GET | /marketplace/companies/{companySlug} | No | Get a buyer-first public Seller Profile. |
GET | /marketplace/companies/{companySlug}/products/{productSlug} | No | Get a public seller Product page. |
GET | /marketplace/companies/{companySlug}/services/{serviceSlug} | No | Get a public seller Service page. |
POST | /marketplace/companies/{companySlug}/claims | No | Start domain-email verification to claim a company profile. |
POST | /marketplace/company-claims/{claimId}/verify | Yes | Verify a claim and attach the profile to a workspace. |
POST | /marketplace/companies/{companySlug}/removal-requests | No | Start official-domain verification for full public removal. |
POST | /marketplace/company-removal-requests/{requestId}/verify | No | Verify and apply a non-destructive public removal. |
GET | /marketplace/categories/{categorySlug} | No | Get a public category page. |
GET | /marketplace/category-roots/{rootKind} | No | List a Product or Service Category root. |
GET | /marketplace/categories/{rootKind}/{categorySlug} | No | Get a typed Product or Service Category. |
GET | /marketplace/articles | No | List current public Articles. |
GET | /marketplace/articles/{articleSlug} | No | Get one current public Article. |
GET | /marketplace/market-maps | No | List current public Market Maps. |
GET | /marketplace/market-maps/{marketMapSlug} | No | Get one current public Market Map. |
API reference
Open the interactive Scalar reference:
Tradebird Public API Reference
Listing search example
curl "${TRADEBIRD_API_BASE_URL}/marketplace/listings/search?q=5-axis%20CNC&limit=5"The listing-search response contains one relevance-ranked Product/Service sequence, an exact total, supported filters, Category directions, and an optional exact Seller match. Exact Category queries may resolve to a typed Category URL. Product Variants and public SKUs lead to their parent Product; they are not separate listing cards.
Product and Service discovery integrations use /marketplace/listings/search.
Company profile example
curl "${TRADEBIRD_API_BASE_URL}/marketplace/companies/nordic-automation-demo-a-s"The response contains one selected-version Seller identity, current Products
and Services, restrained proof/details, related Categories, canonical URLs,
and privacy-safe actions. It omits claim/tenant state, seller-agent routing,
publication/source diagnostics, raw snapshots, and raw evidence. Unknown or
unpublished Sellers return 404; domain-verified removed Sellers return 410.
Company claim example
curl -X POST "${TRADEBIRD_API_BASE_URL}/marketplace/companies/nordic-automation-demo-a-s/claims" \
-H "Content-Type: application/json" \
-d '{
"requesterName": "Jane Smith",
"requesterEmail": "jane@nordic-automation.example"
}'Category page example
curl "${TRADEBIRD_API_BASE_URL}/marketplace/categories/industrial-automation"Seller Profile removal example
curl -X POST "${TRADEBIRD_API_BASE_URL}/marketplace/companies/nordic-automation-demo-a-s/removal-requests" \
-H "Content-Type: application/json" \
-d '{
"requesterName": "Jane Smith",
"requesterEmail": "jane@nordic-automation-demo.example"
}'Removal requires email control of the Seller's current official domain. The verification link is single-use and expires. Successful verification removes the complete public Seller, Product, Service, search, media, URL, sitemap, API, and MCP surface while retaining canonical identity and publication history. It does not claim the Seller or create a workspace.
Article example
curl "${TRADEBIRD_API_BASE_URL}/marketplace/articles/how-to-evaluate-a-cnc-machining-partner"Article detail responses contain the canonical Markdown source, selected public media metadata, typed marketplace relationships, publication dates, and safe next actions. They do not contain rendered HTML or editorial pipeline state.
Response principles
Public responses should be stable and agent-readable. Where useful, responses include canonical URLs, typed related concepts, and selected public proof while excluding private workspace state and internal publication/source mechanics.