Public API

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 Supplier URLs.
`GET`	`/marketplace/companies/{companySlug}`	No	Get a buyer-first public Supplier Profile.
`GET`	`/marketplace/companies/{companySlug}/products/{productSlug}`	No	Get a public supplier Product page.
`GET`	`/marketplace/companies/{companySlug}/services/{serviceSlug}`	No	Get a public supplier 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 Supplier 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 Supplier identity, current Products and Services, restrained proof/details, related Categories, canonical URLs, and privacy-safe actions. It omits claim/tenant state, sales agent routing, publication/source diagnostics, raw snapshots, and raw evidence. Unknown or unpublished Suppliers return 404; domain-verified removed Suppliers 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"

Supplier 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 Supplier's current official domain. The verification link is single-use and expires. Successful verification removes the complete public Supplier, Product, Service, search, media, URL, sitemap, API, and MCP surface while retaining canonical identity and publication history. It does not claim the Supplier 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.

Compatibility terminology

Existing fields and values such as seller, sellerMatch, and seller_profile refer to the supplier company. Their names remain stable for API and MCP clients; they do not identify an individual salesperson.