/API Reference

M8ven API Reference

Access M8ven's trust and discovery data via REST API. Search businesses, get trust reports, check offers, and more.

Quick Start

1. Base URL

https://m8ven.ai/api/v1

2. Authentication — include your API key in every request

Authorization: Bearer m8v_your_api_key_here

3. Search for businesses

curl

curl -X POST https://m8ven.ai/api/v1/data/search \
  -H "Authorization: Bearer m8v_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "daycare", "location": "Brooklyn, NY"}'

Verify Vendor (Public)

GET/api/v1/verify/{slug}

Public vendor verification — no API key required. Returns trust score, verification status, compliance signals, and external ratings.

No authentication required. This endpoint is public and CORS-enabled — call it from any frontend, server, or the browser. Rate limited to 60 requests/minute per IP.

Parameter	Type	Description
slug*	string	Vendor slug (from the URL path)

Example Request

curl https://m8ven.ai/api/v1/verify/little-scholars-daycare

Response

{
  "vendor": "Little Scholars Daycare",
  "slug": "little-scholars-daycare",
  "m8ven_id": "M8V-3F8A2B1C",
  "trust_score": 87,
  "verified": true,
  "claimed": true,
  "vendor_type": "business",
  "location": "123 E 65th St, New York, NY 10065",
  "signals": {
    "google_rating": 4.6,
    "google_reviews": 142,
    "license_status": "active",
    "violations": 0,
    "niche_grade": "A",
    "phone_verified": true,
    "email_verified": true,
    "id_verified": false,
    "business_license_verified": true
  },
  "badge_url": "https://m8ven.ai/badge/little-scholars-daycare",
  "profile_url": "https://m8ven.ai/verify/little-scholars-daycare",
  "claim_url": null
}

Brand Authorization

POST/api/v1/brand-auth/check

Check if a vendor is authorized by a specific brand. Used by platforms and marketplaces to verify authorized dealers.

Requires Authorization: Bearer <api-key>

Parameter	Type	Description
seller_name	string	Business name to check
business_tax_id	string	Tax ID / EIN (alternative to name)
brand	string	Brand slug to check authorization against
platform	string	Platform context (e.g. "amazon", "ebay", "open_web")

Example Request

curl -X POST https://m8ven.ai/api/v1/brand-auth/check \
  -H "Authorization: Bearer m8v_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"seller_name": "Acme Sneakers", "brand": "nike", "platform": "amazon"}'

Response

{
  "authorized": true,
  "distributor_name": "Acme Sneakers LLC",
  "authorization_level": "platinum",
  "platforms": ["amazon", "ebay", "open_web"],
  "authorized_date": "2025-06-15",
  "expires_at": "2027-06-15"
}

Search Sellers

POST/api/v1/data/search

Find local businesses, stores, schools, service providers, and professionals.

Requires Authorization: Bearer <api-key>

Parameter	Type	Description
query	string	Free-text search (e.g. "daycare", "sneaker store", "plumber"). Recommended for best results.
categories	string[]	Filter by category slugs (e.g. ["childcare", "schools-private"]). Works best combined with query or location.
tags	string[]	Filter by tags
location	string	City/state filter (e.g. "Brooklyn, NY", "New York, NY")
neighborhood	string	Exact neighborhood match (e.g. "Park Slope"). Requires sellers to have neighborhood data populated. Use location for broader searches.
zip_code	string	ZIP code filter (exact match)
latitude	number	Latitude for geo-radius search
longitude	number	Longitude for geo-radius search
radius_miles	number	Radius in miles (default 2, used with lat/lng)
min_trust_score	number	Minimum trust score 0-100
verified_only	boolean	Only return verified sellers
has_violations	boolean	Filter by violation status (true = has violations, false = clean)
license_status	string	Filter by license status (e.g. "active")
sort_by	string	"trust", "distance", "name", or "relevance"
limit	number	Max results (default 10, max 50)
offset	number	Pagination offset

Tips: For best results, always include query or location. The categories filter is applied post-search, so combining it with query or location yields the best results. The neighborhood filter requires an exact match on the seller's neighborhood field — use location for broader geographic searches.

Example Response

{
  "results": [
    {
      "m8ven_id": "M8V-AB12CD",
      "display_name": "Bright Horizons Daycare",
      "slug": "m8v-abc12345",
      "passport_url": "https://m8ven.ai/seller/m8v-abc12345",
      "trust_score": 82,
      "trust_tier": "Trusted",
      "seller_type": "business",
      "location": "Brooklyn, NY",
      "full_address": "123 Park Pl, Brooklyn, NY 11217",
      "location_zip": "11217",
      "latitude": 40.6782,
      "longitude": -73.9442,
      "neighborhood": "Park Slope",
      "categories": ["childcare"],
      "tags": ["licensed", "infant-care"],
      "verification_summary": {
        "email": true, "phone": true, "id_document": false,
        "business_license": true, "social_linkedin": false,
        "social_instagram": true, "social_tiktok": false,
        "marketplace_reputation": false
      },
      "review_summary": {
        "count": 12, "average_rating": 4.7, "recent_count": 3
      }
    }
  ],
  "total": 1
}

Get Seller

POST/api/v1/data/seller

Get detailed information about a specific business, including verifications, reviews, badges, and profile data.

Requires Authorization: Bearer <api-key>

Parameter	Type	Description
slug	string	Seller slug (e.g. "m8v-abc12345")
seller_id	string	Seller UUID (alternative to slug)

Provide either slug or seller_id.

Example Response

{
  "m8ven_id": "M8V-AB12CD",
  "display_name": "Bright Horizons Daycare",
  "slug": "m8v-abc12345",
  "passport_url": "https://m8ven.ai/seller/m8v-abc12345",
  "seller_type": "business",
  "bio": "Licensed daycare serving Park Slope since 2018.",
  "avatar_url": "https://...",
  "location": "Brooklyn, NY",
  "trust_score": 82,
  "trust_tier": "Trusted",
  "member_since": "2024-03-15T00:00:00Z",
  "account_age_days": 365,
  "social": { "linkedin": null, "instagram": "@brighthorizons", "tiktok": null },
  "verifications": {
    "email": true, "phone": true, "id_document": false,
    "business_license": true, "social_linkedin": false,
    "social_instagram": true, "social_tiktok": false,
    "marketplace_reputation": false
  },
  "reviews": {
    "count": 12, "average_rating": 4.7, "recent_count": 3,
    "recent_reviews": [
      { "reviewer_name": "Jane D.", "rating": 5, "title": "Great care", "body": "...", "platform": "m8ven", "date": "2026-03-01T..." }
    ]
  },
  "badges": [
    { "id": "fully_verified", "label": "Fully Verified", "description": "Email, phone, and ID all verified" },
    { "id": "top_rated", "label": "Top Rated", "description": "Average rating of 4.5+ with 5 or more reviews" }
  ],
  "categories": [{ "slug": "childcare", "name": "Childcare" }],
  "tags": ["licensed", "infant-care"],
  "attributes": { "age_range": "6 weeks - 5 years", "capacity": "45" },
  "profile": [{ "type": "school", "data": {...}, "source": "manual", "last_updated": "..." }],
  "compliance": {
    "total_records": 1,
    "records": [{ "type": "inspection", "title": "Annual Inspection", "severity": "none", "status": "passed", "date": "..." }]
  },
  "news": [{ "headline": "...", "summary": "...", "url": "...", "source": "...", "sentiment": "positive" }],
  "staff": [{ "name": "Jane Smith", "title": "Director", "role": "director", "credentials": ["M.Ed"] }]
}

Fields like profile, compliance, news, and staff are only included when data is available.

Trust Report

POST/api/v1/data/trust-report

Get a detailed trust assessment for a business, with risk analysis and recommendations.

Requires Authorization: Bearer <api-key>

Parameter	Type	Description
slug	string	Seller slug
seller_id	string	Seller UUID
transaction_context	object	Optional context: { item_value_usd, category, is_local_pickup }

Example Response

{
  "seller": {
    "m8ven_id": "M8V-AB12CD",
    "display_name": "Bright Horizons Daycare",
    "slug": "m8v-abc12345",
    "passport_url": "https://m8ven.ai/seller/m8v-abc12345",
    "seller_type": "business",
    "location": "Brooklyn, NY",
    "account_age_days": 365,
    "member_since": "2024-03-15T00:00:00Z"
  },
  "trust": {
    "score": 82,
    "tier": "Trusted",
    "decision": "approve",
    "reason": "Strong verification and review history."
  },
  "verifications": {
    "email": true, "phone": true, "id_document": false,
    "business_license": true, ...
  },
  "reviews": {
    "count": 12, "average_rating": 4.7, "recent_count": 3,
    "recent_reviews": [{ "rating": 5, "title": "Great care", "platform": "m8ven", "date": "..." }]
  },
  "badges": [...],
  "categories": ["Childcare"],
  "tags": ["licensed"],
  "context_assessment": {
    "risk_level": "low",
    "recommendation": "Transaction appears low-risk based on seller profile and context.",
    "factors": ["3 verifications completed", "Strong review history (4.7 avg across 12 reviews)"]
  }
}

context_assessment is only returned when transaction_context is provided.

Seller Offers

POST/api/v1/data/offers

Get active offers, discounts, and promotions for a business.

Requires Authorization: Bearer <api-key>

Parameter	Type	Description
slug	string	Seller slug
seller_id	string	Seller UUID

Example Response

{
  "seller_name": "Bright Horizons Daycare",
  "offers": [
    {
      "title": "First Month Free",
      "description": "New families get their first month at no charge.",
      "type": "promotion",
      "negotiation_available": false
    }
  ]
}

List Categories

POST/api/v1/data/categories

List available business categories. Returns the taxonomy with provider counts.

Requires Authorization: Bearer <api-key>

Parameter	Type	Description
parent_slug	string	Parent category slug to list children of. Omit for top-level categories.

Example Response

{
  "categories": [
    { "slug": "childcare", "name": "Childcare" },
    { "slug": "schools-private", "name": "Private Schools" },
    { "slug": "sneakers", "name": "Sneakers" },
    ...
  ]
}

Pricing

GET/api/v1/pricing

Get current pricing for all M8ven products. No authentication required.

Example Response

{
  "data_api": {
    "free": { "name": "Free", "price": 0, "monthlyIncluded": 3000, ... },
    "starter": { "name": "Starter", "price": 49, "monthlyIncluded": 30000, "overageRate": 0.005, "pricingLabel": "Early Adopter Pricing", ... },
    "growth": { "name": "Growth", "price": 149, "monthlyIncluded": 300000, ... },
    "payg": { "name": "Pay As You Go", "price": 0, "perRequest": 0.005, ... }
  },
  "chat_api": {
    "chat_starter": { "name": "Chat Starter", "price": 99, "monthlyIncluded": 15000, ... },
    ...
  },
  ...
}

Chat API

POST/api/v1/chat

Send a message to M8ven's AI assistant. Requires a Chat API key (not a Data API key). M8ven handles the LLM — you get back a natural language response.

Requires Authorization: Bearer <api-key>

Parameter	Type	Description
messages*	array	Array of { role: "user" \| "assistant", content: string }
system_prompt	string	Custom system prompt (chat_growth+ plans only)

Example Request

{
  "messages": [
    { "role": "user", "content": "Find daycares near Park Slope with good reviews" }
  ]
}

Example Response

{
  "message": "I found 3 highly-rated daycares in Park Slope:\n\n1. **Bright Horizons** — Trust score 82, 4.7★ (12 reviews)...",
  "usage": { "remaining": 14982 }
}

Embeddable Badge

GET/badge/{slug}

Returns an SVG trust badge for any vendor. Embed on any website — no API key needed.

No authentication required. CORS enabled. Cached for 1 hour. Returns image/svg+xml.

The badge displays the trust score, business name, and verification status. Color changes based on score (green ≥80, amber ≥60, red <60).

HTML embed

<a href="https://m8ven.ai/verify/your-vendor">
  <img src="https://m8ven.ai/badge/your-vendor"
       alt="Verified by M8ven" />
</a>

JavaScript Widget

Drop-in web component that renders an interactive trust badge. Fetches data from the public Verify API automatically. Uses Shadow DOM for style isolation — works in any framework or plain HTML.

Add the script (once)

<script src="https://m8ven.ai/widget/verify.js"></script>

Add badges anywhere

<!-- Default (light theme, medium size) -->
<m8ven-badge slug="your-vendor"></m8ven-badge>

<!-- Dark theme, small -->
<m8ven-badge slug="your-vendor" theme="dark" size="small"></m8ven-badge>

<!-- Large badge -->
<m8ven-badge slug="your-vendor" size="large"></m8ven-badge>

Attribute	Values	Description
slug*	string	Vendor slug (required)
theme	"light" \| "dark"	Color theme (default: light)
size	"small" \| "medium" \| "large"	Badge size (default: medium)

The widget is loaded from M8ven's CDN and requires no API key. Clicks open the vendor's full verification page on M8ven.

Errors

All errors return JSON with an error field.

Status	Meaning
401	Missing or invalid API key
403	Missing permission, wrong key type (chat vs data), or origin not allowed
402	Spending cap reached (PAYG plans)
429	Rate limit or daily limit exceeded
400	Invalid request parameters
404	Resource not found
500	Server error

Error Response

{ "error": "Daily request limit reached (100). Upgrade your plan for more requests." }

Rate Limits & Usage

Authenticated API (with API key)

Per-minute: 60 requests/minute per API key (all plans)
Daily: Based on your plan — Free: 100/day, Starter: 1,000/day, Growth: 10,000/day
Monthly: Starter: 30,000/month, Growth: 300,000/month

Free plans enforce a hard daily limit. When you hit the limit, you'll receive an email with upgrade options. Tiered plans (Starter, Growth) include a monthly allowance with overage billing.

Public Verify API (no API key)

Per-minute: 60 requests/minute per IP address
No daily/monthly limit

The public verify endpoint (/api/v1/verify/{slug}) is rate limited per IP. When called from a frontend (browser), each user has their own IP and limit. When calling from a server, all requests share the server's IP — use an API key for server-side integrations instead.

Badge & Widget

The badge endpoint (/badge/{slug}) and widget (verify.js) have no rate limits. Badges are cached for 1 hour.

Usage alerts

At 80% of your daily limit: warning email
At 100%: limit reached email with upgrade link

Usage is tracked and visible in your Developer Dashboard.

MCP (Model Context Protocol)

M8ven also supports MCP for direct integration with AI clients like Claude and ChatGPT. The MCP server exposes the same tools as the REST API.

MCP endpoint:

https://m8ven.ai/api/mcp/sse

Available MCP tools: search_sellers, get_seller, get_trust_report, get_seller_offers, list_categories, get_pricing, and more.

MCP usage is metered the same way as the REST Data API — same plans, same pricing.

Questions? Contact support@m8ven.ai