API reference

Public read endpoints can be called anonymously unless the server is configured to require API keys.

X-API-Key: $MESHSCOUT_API_KEY

Authorization: Bearer $MESHSCOUT_API_KEY

Search query parameters

Advanced search tags

The search box parser also understands inline tags in q. Example: gridfinity author:Zack tag:storage before:2024-01-01.

Search response

{
  "hits": [],
  "query": "gridfinity",
  "filters": [],
  "offset": 0,
  "limit": 24,
  "grouped": true,
  "shown": 24,
  "estimatedTotalHits": 120000,
  "processingTimeMs": 42,
  "cached": false
}

Model object

{
  "id": "785e340f-b563-4132-9782-924d068096b0",
  "modelId": "668856af-7ecf-4f78-b46c-607c1f375971",
  "groupKey": "author:example",
  "source": "cults",
  "sourceName": "Cults",
  "sourceColor": "#e35b64",
  "sourceFavicon": "https://cults3d.com/favicon.ico",
  "sourceModelId": "external-source-id",
  "url": "https://source-site.example/model",
  "title": "Example model",
  "description": "Short indexed description.",
  "author": "ExampleAuthor",
  "authorUrl": "https://source-site.example/author",
  "category": "Organization",
  "license": "CC BY",
  "commercialAllowed": true,
  "image": "https://cdn.example/image.jpg",
  "tags": ["gridfinity", "storage"],
  "downloads": 1200,
  "likes": 50,
  "views": 8000,
  "publishedAt": "2026-01-01T00:00:00.000Z",
  "indexedAt": "2026-07-30T00:00:00.000Z"
}

Model detail response

{
  "model": {},
  "images": [{ "image_url": "https://..." }],
  "tags": ["gridfinity"],
  "variants": [],
  "relatedByAuthor": [],
  "generatedAt": "2026-07-30T00:00:00.000Z"
}

Search quality feedback

Supported feedback types are not_relevant, duplicate_result, wrong_creator, broken_media, missing_details, and unsafe_preview. Duplicate reports also require comparedSourceModelId. Anonymous and signed-in submissions use separate daily limits.

{
  "sourceModelId": "785e340f-b563-4132-9782-924d068096b0",
  "feedbackType": "broken_media",
  "queryText": "gridfinity",
  "resultPosition": 3,
  "resultPage": 1
}

Signed-in source choice

PATCH /api/auth/profile accepts a modelDiscovery object. It controls which available source copy a grouped card opens automatically, while preserving every source variant in search and model details. An explicit source selected in the search toolbar overrides the account order for that search.

{
  "modelDiscovery": {
    "sourceOrder": ["makerworld", "printables", "thingiverse"],
    "avoidPaidWhenFree": true,
    "preferVerifiedCreator": true,
    "rankingMode": "balanced",
    "neverAutoOpenUnreachable": true
  }
}

Discovery parameters

{
  "sources": [
    {
      "id": "makerworld",
      "name": "MakerWorld",
      "color": "#00b578",
      "favicon": "https://makerworld.com/favicon.ico",
      "total": 2000000,
      "offset": 0,
      "limit": 10,
      "hasMore": true,
      "models": []
    }
  ],
  "cached": true,
  "generatedAt": "2026-07-30T00:00:00.000Z"
}

GET /api/collections/public accepts q, limit, and offset. While curated public collections are enabled, curated=1 returns only reviewed Staff Picks and excludeCurated=1 keeps those picks out of a separate ordinary-results request.

Staff publishing tools use GET /api/admin/weekly-reports, POST /api/admin/weekly-reports/generate, PATCH /api/admin/weekly-reports/{reportId}, and explicit blog-draft or publish actions. Generated datasets remain private until a reviewer sends one to the blog, and public publishing is separately feature controlled.

Create/update collection body

{
  "name": "Print Soon",
  "description": "Weekend projects",
  "visibility": "private"
}

Collection object

{
  "id": "collection-id",
  "name": "Print Soon",
  "description": "Weekend projects",
  "visibility": "public",
  "owner_username": "Grim",
  "model_count": 10,
  "images": ["https://..."],
  "curation_status": "featured",
  "curation_theme": "practical",
  "curation_note": "A useful starting point for workshop upgrades.",
  "curation_quality_score": 91,
  "created_at": "2026-07-30T00:00:00.000Z",
  "updated_at": "2026-07-30T00:00:00.000Z"
}

Release history is available for verified or claimed creators while the feature is enabled. Cross-posts are shown once, with exact source listings retained as variants.

These routes use the signed-in account session. Watch previews and tests are read-only and do not move the Watch cursor or send notifications.

Common errors

Rate-limit headers

API responses, except the health check, include rate-limit headers. Treat X-RateLimit-Reset as the time to retry after a 429.

X-RateLimit-Limit: 240
X-RateLimit-Remaining: 239
X-RateLimit-Reset: 2026-07-30T00:00:00.000Z

Pagination

Most lists use limit and offset. Model search returns estimatedTotalHits and shown.

/api/search?q=frog&limit=48&offset=96

Caching

Some responses include cached and generatedAt. Cached responses are safe to use and are normal for search, discovery lanes, and model details.

Integration tips

• Use grouping for search interfaces so duplicate uploads collapse into one card.
• Use variants when you want all known source copies for each grouped result.
• Use page sizes around 24-48 for interactive UIs.
• Use deep search only for deliberate advanced searches.
• Always link users back to the original model URL and show source/license attribution.
• Do not assume a license allows commercial use. Check commercialAllowed and still point users to the source page.