TrustedMarket Developers
API docs, recipes, and Claudia — your developer assistant
Quick Start
Base URL: https://trustedmarket.io/api/v1
Auth: Clerk JWT in Authorization: Bearer <token> header. Public endpoints work without auth.
Format: JSON request/response. Content-Type: application/json
CSRF: State-changing requests (POST/PATCH/DELETE) require Origin header matching the app domain.
OpenAPI: /api/v1/openapi.json — import into Postman, Insomnia, or any API client.
Full spec: docs/api-specification.md — detailed field descriptions, examples, error codes.
Try It
Paste these in your terminal:
Search for plumbers near Toronto:
curl "https://trustedmarket.io/api/v1/search/smart?q=plumber&userLat=43.65&userLng=-79.38&limit=5"Browse all cleaning services:
curl "https://trustedmarket.io/api/v1/search?category=cleaning&geo=everywhere&limit=10"Get all categories:
curl "https://trustedmarket.io/api/v1/categories"Search
/api/v1/searchBrowse listings with filters (category, price, rating, distance, images, reviews)
Response example
{
"listings": [
{
"id": "clx1abc...",
"title": "Professional House Cleaning",
"price": 85,
"pricingModel": "FIXED",
"serviceArea": "Toronto, ON",
"distanceKm": 3.2,
"images": [
"https://..."
],
"category": {
"name": "Cleaning",
"slug": "cleaning"
},
"provider": {
"id": "clx...",
"displayName": "Maria S.",
"avgRating": 4.8,
"reviewCount": 23,
"serviceArea": "Toronto, ON"
}
}
],
"pagination": {
"total": 142,
"page": 1,
"totalPages": 15,
"limit": 10
}
}/api/v1/search/smartNLP-powered search — understands plain language queries
Response example
{
"listings": [
{
"id": "clx2abc...",
"title": "Emergency Plumbing",
"price": 95,
"pricingModel": "HOURLY",
"provider": {
"displayName": "Mike O.",
"avgRating": 4.6,
"reviewCount": 7
},
"category": {
"name": "Plumbing",
"slug": "plumbing"
}
}
],
"pagination": {
"total": 8,
"page": 1,
"totalPages": 1,
"limit": 10
},
"interpretation": "Searching for plumbers in Halifax",
"locationLabel": "Halifax, NS"
}/api/v1/categoriesAll categories and subcategories (140 items)
Response example
[
{
"id": "clx9def...",
"name": "Skilled Trades",
"slug": "skilled-trades",
"parentId": null
},
{
"id": "clx9ghi...",
"name": "Plumbing",
"slug": "plumbing",
"parentId": "clx9def..."
},
{
"id": "clx9jkl...",
"name": "Cleaning",
"slug": "cleaning",
"parentId": null
},
{
"id": "clx9mno...",
"name": "Deep Cleaning",
"slug": "deep-cleaning",
"parentId": "clx9jkl..."
}
]Listings
/api/v1/listings/:idListing detail with provider info and reviews
Response example
{
"id": "clx1abc...",
"title": "Professional House Cleaning",
"description": "Thorough cleaning service...",
"price": 85,
"pricingModel": "FIXED",
"type": "SERVICE",
"serviceArea": "Toronto, ON",
"images": [
"https://..."
],
"category": {
"name": "Cleaning",
"slug": "cleaning"
},
"provider": {
"id": "clx...",
"displayName": "Maria S.",
"avgRating": 4.8,
"reviewCount": 23,
"bio": "10 years experience...",
"serviceArea": "Toronto, ON"
},
"reviews": [
{
"id": "clx...",
"rating": 5,
"text": "Excellent service!",
"author": {
"name": "Alex T."
},
"createdAt": "2026-04-15T..."
}
]
}/api/v1/search?category=:slugBrowse by category slug
Providers
/api/v1/providers/:idProvider profile — bio, rating, review count, listings
Response example
{
"id": "clx...",
"displayName": "Maria S.",
"bio": "Professional cleaner with 10 years experience.",
"serviceArea": "Toronto, ON",
"avgRating": 4.8,
"reviewCount": 23,
"trustScore": 92,
"listings": [
{
"id": "clx1abc...",
"title": "Professional House Cleaning",
"price": 85,
"pricingModel": "FIXED",
"status": "ACTIVE"
}
]
}/api/v1/providers/:id/reviewsProvider reviews with pagination
Response example
{
"reviews": [
{
"id": "clx...",
"rating": 5,
"ratingQuality": 5,
"ratingCommunication": 5,
"ratingPunctuality": 4,
"ratingValue": 5,
"text": "Amazing work!",
"author": {
"id": "clx...",
"name": "Alex T."
},
"createdAt": "2026-04-15T..."
}
],
"pagination": {
"total": 23,
"page": 1,
"totalPages": 3
}
}/api/v1/providers/profileCurrent user's provider profile
Response example
{
"id": "clx...",
"displayName": "Your Business Name",
"bio": "Your bio...",
"serviceArea": "Halifax, NS",
"avgRating": 4.5,
"reviewCount": 12,
"listings": [
{
"id": "clx...",
"title": "Your listing",
"price": 50,
"status": "ACTIVE"
}
]
}Users
/api/v1/users/profileCurrent user's profile
Response example
{
"id": "clx...",
"name": "Jody Brownell",
"email": "jody@...",
"role": "BOTH",
"location": "Charters Settlement, NB",
"avatarUrl": "https://...",
"createdAt": "2026-03-01T..."
}/api/v1/users/profileUpdate profile (name, location, avatar)
Response example
{
"id": "clx...",
"name": "Jody Brownell",
"email": "jody@...",
"role": "BOTH",
"location": "Charters Settlement, NB",
"avatarUrl": "https://...",
"createdAt": "2026-03-01T..."
}/api/v1/users/preferencesTheme, view mode, locale preferences
Response example
{
"theme": "rose-pine",
"viewMode": "tiles",
"locale": "en-CA"
}/api/v1/users/preferencesSave preferences (persists across devices)
Response example
{
"theme": "rose-pine",
"viewMode": "tiles",
"locale": "en-CA"
}Claudia (Agent)
/api/v1/agentChat with Claudia — search, navigate, create listings, file feedback
Response example
{
"reply": "Found 5 plumbers nearby.",
"searchResults": [
{
"id": "clx...",
"title": "Emergency Plumbing",
"price": 95,
"provider": {
"displayName": "Mike O.",
"avgRating": 4.6
}
}
],
"searchMeta": {
"total": 5,
"query": "plumber",
"location": "Halifax, NS"
},
"navigateTo": null,
"openWizard": null,
"actions": null
}/api/v1/agent/historyLoad chat history from DB
Response example
{
"messages": [
{
"id": "clx...",
"role": "user",
"content": "find me a plumber",
"createdAt": "2026-05-07T..."
},
{
"id": "clx...",
"role": "assistant",
"content": "Found 5 plumbers nearby.",
"createdAt": "2026-05-07T..."
}
]
}/api/v1/agent/historySave a chat message
Response example
{
"messages": [
{
"id": "clx...",
"role": "user",
"content": "find me a plumber",
"createdAt": "2026-05-07T..."
},
{
"id": "clx...",
"role": "assistant",
"content": "Found 5 plumbers nearby.",
"createdAt": "2026-05-07T..."
}
]
}/api/v1/agent/historyClear all chat history permanently
Response example
{
"messages": [
{
"id": "clx...",
"role": "user",
"content": "find me a plumber",
"createdAt": "2026-05-07T..."
},
{
"id": "clx...",
"role": "assistant",
"content": "Found 5 plumbers nearby.",
"createdAt": "2026-05-07T..."
}
]
}Feedback
/api/v1/feedbackSubmit bug report, feature request, or feedback
Response example
{
"id": "clx...",
"type": "bug",
"title": "Search returns zero results",
"description": "When I search for...",
"status": "open",
"githubIssueUrl": "https://github.com/...",
"createdAt": "2026-05-07T..."
}/api/v1/feedback/searchSearch existing feedback for dupe detection
Response example
[
{
"id": "clx...",
"title": "Search broken for plumbers",
"type": "bug",
"status": "open",
"dupeCount": 2,
"createdAt": "2026-05-06T..."
}
]Images
/api/v1/images/uploadUpload image (EXIF auto-stripped). Buckets: profiles, listings, portfolios, reviews, feedback
Response example
{
"url": "https://s3.ca-central-1.amazonaws.com/bucket/listings/abc123.webp",
"key": "listings/abc123.webp",
"bucket": "listings",
"entityId": "clx..."
}AI Polish
/api/v1/ai/polishClaudia Assist — polish text for listings, reviews, bios, messages, feedback
Response example
{
"polished": "Professional house cleaning service with 10 years of experience in the Greater Toronto Area.",
"declined": false,
"decline_reason": null
}Geocoding
/api/v1/geocodeForward/reverse geocode via AWS Location Service
Response example
{
"label": "Halifax, NS",
"lat": 44.6488,
"lng": -63.5752,
"country": "CAN",
"region": "Nova Scotia"
}Built by the TrustedMarket team — Claudius builds, Claudia guides.