{"openapi":"3.1.0","info":{"title":"ModelDirectory.org read API","version":"1.1.0","description":"The public, no-auth read endpoints for ModelDirectory.org. These return the same facts the website shows for published models: metadata, licenses (with SPDX id and canonical URL), fingerprints, and on-chain proofs. Write actions and account data are not part of this spec.","contact":{"url":"https://modeldirectory.org/contact.html"}},"servers":[{"url":"https://modeldirectory.org","description":"Main site, API proxied under /api"},{"url":"https://api.modeldirectory.org","description":"API subdomain"}],"paths":{"/api/health":{"get":{"operationId":"getHealth","summary":"Service health and load","responses":{"200":{"description":"Service is up.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/status":{"get":{"operationId":"getStatus","summary":"Status of database, payments, and email","responses":{"200":{"description":"Operational.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Degraded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/models/stats":{"get":{"operationId":"getStats","summary":"Catalog totals","description":"Counts for the whole catalog: total models, how many are fingerprinted, how many are on-chain, and how many creators.","responses":{"200":{"description":"Totals.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stats"}}}}}}},"/api/models/":{"get":{"operationId":"listModels","summary":"Browse and search published models","description":"Returns a page of published models. Pagination is page-based: pass page and limit. There is no total count in the response on purpose; use /api/models/stats for the global total.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Free-text search over name, description, tags."},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by category, for example gadgets, toys, art."},{"name":"format","in":"query","schema":{"type":"string","enum":["STL","OBJ","STEP","3MF"]},"description":"Filter by file format."},{"name":"source","in":"query","schema":{"type":"string"},"description":"Filter by source platform, for example thingiverse, printables."},{"name":"sort","in":"query","schema":{"type":"string"},"description":"Sort order, for example newest, popular."},{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Page number, starting at 1."},{"name":"limit","in":"query","schema":{"type":"integer","default":20},"description":"Page size."}],"responses":{"200":{"description":"A page of models.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelListResponse"}}}}}}},"/api/models/{id}":{"get":{"operationId":"getModel","summary":"One model as JSON","description":"Full record for a published model, including any confirmed on-chain anchors and the machine-readable license (license_spdx, license_url).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The model.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelDetailResponse"}}}},"404":{"description":"Not found or not published.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/models/verify":{"get":{"operationId":"verifyFingerprint","summary":"Look up a fingerprint","description":"Checks a SHA-256 hash against the registry and reports whether it is recorded and whether it is on-chain.","parameters":[{"name":"hash","in":"query","required":true,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"description":"A 64-character SHA-256 hex string."}],"responses":{"200":{"description":"Lookup result. found is false when the hash is unknown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyResult"}}}},"400":{"description":"Missing or malformed hash.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/models/{id}/proof":{"get":{"operationId":"getModelProof","summary":"On-chain proof for a model","description":"Returns the blockchain proof for a published model, checked live against the chain.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Proof, if the model is anchored.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/models/{id}/certificate":{"get":{"operationId":"getModelCertificate","summary":"Certificate for a model","description":"A signed certificate plus any on-chain proof for a published model.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Certificate data.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/creators/":{"get":{"operationId":"listCreators","summary":"List creators","responses":{"200":{"description":"Creators.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/creators/{name}":{"get":{"operationId":"getCreator","summary":"A creator profile","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Profile and published models.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Creator"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/leaderboard/":{"get":{"operationId":"getLeaderboard","summary":"Public leaderboard","responses":{"200":{"description":"Leaderboard.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/blockchain/status":{"get":{"operationId":"getBlockchainStatus","summary":"On-chain stamping worker status","description":"Reports the active chain, contract address, and worker health.","responses":{"200":{"description":"Worker status.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/first-aired":{"get":{"summary":"Where a byte-identical file has been seen, per platform, with the overall first","parameters":[{"name":"hash","in":"query","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"},"description":"SHA-256 of the file bytes"}],"responses":{"200":{"description":"found flag, first {platform, at, url, basis}, sightings[]"}}}},"/api/verify":{"get":{"summary":"Alias of /api/models/verify: registry lookup by SHA-256, includes partner-registered hashes","parameters":[{"name":"hash","in":"query","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"}}],"responses":{"200":{"description":"found flag; model or partner_registry record with on-chain anchors"}}}},"/api/badge/{sha256}.svg":{"get":{"summary":"Provenance badge SVG for a hash (unknown / registered / origin verified). Never errors.","parameters":[{"name":"sha256","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"image/svg+xml, cacheable"}}}},"/api/models/{id}/verify-ots":{"get":{"summary":"Live Bitcoin (OpenTimestamps) verification for a model, with the raw .ots proof URL","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"confirmed flag, block height, attested time, ots_proof_url"},"404":{"description":"no Bitcoin timestamp for this model"}}}},"/api/partner/stamps":{"post":{"summary":"Register a published file's SHA-256 (partners; Authorization: Bearer md_live_...)","responses":{"200":{"description":"already registered (idempotent)"},"201":{"description":"registered; anchoring is asynchronous"}}},"get":{"summary":"List your registered stamps (partners)","responses":{"200":{"description":"stamps[]"}}}},"/api/search":{"get":{"operationId":"searchModels","summary":"Relevance search across the model index (weighted FTS + fuzzy + synonyms).","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query (typo-tolerant)."},{"name":"platform","in":"query","schema":{"type":"string"},"description":"Comma-separated: printables,thingiverse,makerworld,myminifactory,cults3d,thangs."},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string"},"description":"STL, OBJ, STEP, 3MF, …"},{"name":"scope","in":"query","schema":{"type":"string","enum":["all","title","title,desc","ai"]}},{"name":"difficulty","in":"query","schema":{"type":"string","enum":["beginner","intermediate","advanced"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["best","most-downloaded","most-liked","new"]},"description":"Default best; an unknown value returns 400."},{"name":"limit","in":"query","schema":{"type":"integer","default":40}},{"name":"page","in":"query","schema":{"type":"integer","default":1}}],"responses":{"200":{"description":"Results + exact total + facet counts.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Missing q or invalid sort."}}}},"/api/suggest":{"get":{"operationId":"suggest","summary":"Autocomplete suggestions for a partial query (typo-tolerant).","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Partial query (≥2 chars)."},{"name":"limit","in":"query","schema":{"type":"integer","default":8}}],"responses":{"200":{"description":"{ suggestions: string[] }","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"restricted":{"type":"boolean"}}},"Stats":{"type":"object","properties":{"models":{"type":"integer","description":"Total models in the catalog."},"fingerprinted":{"type":"integer","description":"Models that carry a SHA-256 fingerprint."},"on_chain":{"type":"integer","description":"Models anchored on a blockchain."},"creators":{"type":"integer"}}},"Anchor":{"type":"object","properties":{"chain":{"type":"string","enum":["polygon","bitcoin_ots","solana"]},"label":{"type":"string"},"status":{"type":"string","enum":["pending","confirmed","failed"]},"reference":{"type":"string","description":"Transaction hash for Polygon, OTS object key for Bitcoin."},"block":{"type":["integer","string","null"]},"attested_at":{"type":["string","null"],"format":"date-time"},"explorer_url":{"type":["string","null"],"description":"A public link to read the anchor."}}},"Model":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":["string","null"]},"model_name":{"type":"string"},"creator_name":{"type":["string","null"]},"creator_verified":{"type":"boolean"},"description":{"type":["string","null"]},"category":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"format":{"type":["string","null"]},"license":{"type":["string","null"],"description":"Internal license code, for example cc-by."},"license_spdx":{"type":["string","null"],"description":"SPDX identifier, for example CC-BY-4.0. Null if unknown."},"license_url":{"type":["string","null"],"description":"Canonical license URL. Null if unknown."},"sha256_original":{"type":["string","null"],"description":"SHA-256 fingerprint of the file."},"blockchain_chain":{"type":["string","null"]},"blockchain_tx_hash":{"type":["string","null"]},"blockchain_block_number":{"type":["string","null"]},"proof_tier":{"type":"integer","description":"0 registered, 1 Polygon, 2 multi-chain, 3 certificate."},"is_published":{"type":"boolean"},"is_free_download":{"type":"boolean"},"price_cents":{"type":["integer","null"]},"download_count":{"type":"integer","description":"ModelDirectory-native download count. Often 0 for crawled models; for social proof prefer tv_download_count."},"like_count":{"type":"integer","description":"ModelDirectory-native like count. Often 0 for crawled models; for social proof prefer tv_like_count."},"view_count":{"type":"integer","description":"ModelDirectory-native view count."},"tv_download_count":{"type":["integer","null"],"description":"Download count from the source platform (Thingiverse, Printables, etc.). The primary social-proof number for crawled models."},"tv_like_count":{"type":["integer","null"],"description":"Like or favorite count from the source platform."},"tv_view_count":{"type":["integer","null"],"description":"View count from the source platform."},"thumbnail_url":{"type":["string","null"],"description":"Primary thumbnail image URL."},"thumbnail_rendered_url":{"type":["string","null"],"description":"Our own server-rendered thumbnail, when available."},"external_platform":{"type":["string","null"]},"external_url":{"type":["string","null"]},"published_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":["string","null"],"format":"date-time"}}},"ModelListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"models":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}}},"ModelDetailResponse":{"type":"object","properties":{"success":{"type":"boolean"},"model":{"$ref":"#/components/schemas/Model"},"anchors":{"type":"array","items":{"$ref":"#/components/schemas/Anchor"}},"social_mentions":{"type":"array","description":"Mentions of this model found across social platforms (Reddit, YouTube, forums). A community-trust signal.","items":{"$ref":"#/components/schemas/SocialMention"}},"makes_count":{"type":"integer","description":"Number of community makes (people who printed it). A strong trust signal."},"makes_preview":{"type":"array","description":"Preview of recent community makes, often with photos.","items":{"type":"object"}},"cross_platform_links":{"type":"array","description":"Confirmed links to the same model on other platforms.","items":{"type":"object"}}}},"SocialMention":{"type":"object","description":"A reference to this model found on an external or social platform.","properties":{"id":{"type":"string"},"source":{"type":"string","description":"Platform, for example reddit, youtube, lemmy."},"source_url":{"type":"string"},"post_title":{"type":["string","null"]},"context_text":{"type":["string","null"],"description":"Snippet of the post or comment that mentions the model."},"post_score":{"type":["integer","null"],"description":"Upvotes or score of the post, when known."},"comment_count":{"type":["integer","null"]},"view_count":{"type":["integer","null"]}}},"VerifyResult":{"type":"object","properties":{"found":{"type":"boolean"},"hash":{"type":"string"},"model":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"creator":{"type":["string","null"]},"format":{"type":["string","null"]},"license":{"type":["string","null"]},"license_spdx":{"type":["string","null"]},"license_url":{"type":["string","null"]},"proof_tier":{"type":"integer"},"on_chain":{"type":"boolean"},"blockchain":{"type":["object","null"]}}}}},"Creator":{"type":"object","description":"A creator profile and their published models.","properties":{"name":{"type":"string"}}}}}}