{ "openapi": "3.1.0", "info": { "title": "MakerWorld API", "version": "1.0.0", "description": "Public MakerWorld models, print profiles, designers, collections and design contests exposed through FetchLayer." }, "servers": [ { "url": "https://api.fetchlayer.dev/makerworld" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key." } } }, "paths": { "/search-models": { "post": { "operationId": "search-models", "tags": [ "Models" ], "summary": "Search models by keyword", "description": "Search MakerWorld for 3D printable and laser-cut models by keyword. Order by relevance, trending, newest, downloads, likes, collections, prints or boosts, and filter by Creative Commons license, category, nozzle size, and whether a ready-to-print profile exists. Each result carries the designer, popularity counts, license, tags, cover image and URL, plus a cursor for the next page.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Keyword or phrase to search MakerWorld models for." }, "modelType": { "type": "string", "description": "3d for printable models, laser for laser-cut and craft files.", "example": "3d" }, "sortBy": { "type": "string", "description": "relevance, trending, newest, boosts, downloads, likes, collections, or prints.", "example": "relevance" }, "licenses": { "type": "array", "items": { "type": "string" }, "description": "Restrict to these licenses: CC0, BY, BY-SA, BY-ND, BY-NC, BY-NC-SA, BY-NC-ND." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Restrict to these category ids (max 20), as returned by /categories." }, "nozzleDiameters": { "type": "array", "items": { "type": "number" }, "description": "Only models with a print profile built for one of these nozzle sizes in millimetres, for example 0.4 (max 8 values)." }, "printableOnly": { "type": "boolean", "description": "Only models that come with a ready-to-print profile." }, "limit": { "type": "number", "description": "Maximum models returned (max 2000), or -1 for everything available.", "example": "30" }, "pages": { "type": "number", "description": "Requests made while collecting results. One request returns up to 100 items (max 100), or -1 for the maximum allowed.", "example": "1" }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "default": { "value": { "query": "cable management", "sortBy": "trending", "licenses": [ "CC0", "BY" ], "printableOnly": true, "limit": 30 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "modelId": { "type": "string", "description": "Model id — the handle for /model-detail." }, "title": { "type": "string", "description": "Model title." }, "modelUrl": { "type": "string", "description": "Public MakerWorld permalink for the model." }, "license": { "type": "string", "description": "A Creative Commons code, or one of MakerWorld’s own named licenses where it is not a CC one." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags the designer attached." }, "isPrintable": { "type": "boolean", "description": "Whether the model ships with at least one ready-to-print profile." }, "isExclusive": { "type": "boolean", "description": "Available only to members on a paid tier." }, "designer": { "type": "object", "additionalProperties": true, "description": "Designer uid, name, handle, profile URL, follower count, level and verification." }, "stats": { "type": "object", "additionalProperties": true, "description": "likeCount, collectionCount, downloadCount, modelFileDownloadCount, printCount, commentCount, shareCount and boostCount." }, "coverUrl": { "type": "string", "description": "Cover image URL. Pass it to GET /media to stream the file." } } }, "description": "The matching models, in the requested order." }, "filters": { "type": "object", "additionalProperties": true, "description": "The filters this search actually ran with, after defaults were applied." }, "modelCount": { "type": "number", "description": "Number of models in this response." }, "nextCursor": { "type": "string", "description": "Pass back as cursor to continue, or null when the listing is exhausted." }, "hasNextPage": { "type": "boolean", "description": "Whether more results exist beyond this response." }, "pagesScraped": { "type": "number", "description": "Requests actually made. Each one counts against your plan." }, "totalAvailable": { "type": "number", "description": "Roughly how many results exist. Approximate — it varies with the ordering, drifts between identical requests, and stops rising past 10000. Use it for orientation, not as a count, and page until hasNextPage is false." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a walk that stopped early, a listing MakerWorld truncated, an upstream ceiling that was hit. Read it: an empty array means the result is complete, a non-empty one means it is not." }, "requestedUrl": { "type": "string", "description": "The MakerWorld page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO timestamp of when the data was retrieved." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "modelCount": 30, "pagesScraped": 1, "hasNextPage": true, "totalAvailable": 1840, "notes": [], "models": [ { "modelId": "412809", "title": "Under-desk cable tray", "license": "CC0", "isPrintable": true, "designer": { "uid": "99120043", "name": "benchy_lab", "handle": "benchylab", "followerCount": 4120 }, "stats": { "downloadCount": 18422, "likeCount": 2310, "printCount": 6011, "boostCount": 84 } } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/model-detail": { "post": { "operationId": "model-detail", "tags": [ "Models" ], "summary": "Get one model in full", "description": "Read everything MakerWorld publishes about a single model: description, designer, license and remix permission, categories and tags, popularity counts, the file manifest with types and sizes, gallery images and renders, remix lineage, contest placement, and each published print profile with its printer, nozzle size, estimated print time, filament use and rating.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Model id, or a MakerWorld model URL." }, "printProfileLimit": { "type": "number", "description": "Maximum print profiles to include (max 200), or -1 for all of them.", "example": "20" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" } }, "additionalProperties": false, "required": [ "model" ] }, "examples": { "default": { "value": { "model": "https://makerworld.com/en/models/412809-under-desk-cable-tray", "printProfileLimit": 20 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "modelId": { "type": "string", "description": "The resolved model id." }, "model": { "type": "object", "additionalProperties": true, "description": "The full model record.", "properties": { "description": { "type": "string", "description": "The model description, as HTML." }, "license": { "type": "string", "description": "License code, with model.allowsRemixing and model.licenseNote alongside it." }, "categories": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Categories the model sits in, with their ids." }, "files": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "The file manifest: name, type (3mf, stl…), sizeBytes and updatedAt." }, "images": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Gallery images and renders, with URLs you can stream through GET /media." }, "printProfiles": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Published print profiles: printer model, nozzle diameter, layer height, wall loops, infill, plate count, AMS requirement, print time, filament grams and rating." }, "printProfileCount": { "type": "number", "description": "How many profiles exist, which can exceed the number returned when printProfileLimit truncates the list." }, "originals": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Remix lineage — the models this one was derived from." }, "contest": { "type": "object", "additionalProperties": true, "description": "Contest entry and placement, when the model was entered in one." }, "stats": { "type": "object", "additionalProperties": true, "description": "Downloads, likes, collections, prints, comments, shares and boosts." } } }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a walk that stopped early, a listing MakerWorld truncated, an upstream ceiling that was hit. Read it: an empty array means the result is complete, a non-empty one means it is not." }, "requestedUrl": { "type": "string", "description": "The MakerWorld page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO timestamp of when the data was retrieved." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "modelId": "412809", "notes": [ "Print profile list truncated at 20 of 34." ], "model": { "title": "Under-desk cable tray", "license": "CC0", "allowsRemixing": true, "fileCount": 3, "printProfileCount": 34, "printProfiles": [ { "title": "0.4mm nozzle, 0.2mm layer", "printerModel": "Bambu Lab P1S", "printTimeSeconds": 9420, "filamentGrams": 61.4, "ratingScore": 4.8 } ] } } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/search-designers": { "post": { "operationId": "search-designers", "tags": [ "Designers" ], "summary": "Find designers by name", "description": "Look up MakerWorld designers by name or handle. Returns the designer uid the other routes take, the handle, profile URL, avatar, follower count, level and verification status — use it to turn a name you have into an id a profile lookup needs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Designer name or handle to look up." }, "limit": { "type": "number", "description": "Maximum designers returned (max 500), or -1 for everything available.", "example": "30" }, "pages": { "type": "number", "description": "Requests made while collecting results. One request returns up to 100 items (max 100), or -1 for the maximum allowed.", "example": "1" }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "default": { "value": { "query": "benchylab", "limit": 10 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "designers": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "uid": { "type": "string", "description": "Designer uid — the handle for /designer-profile." }, "handle": { "type": "string", "description": "MakerWorld @handle." }, "followerCount": { "type": "number", "description": "Followers on MakerWorld." }, "modelCount": { "type": "number", "description": "How many models the designer has published." }, "bio": { "type": "string", "description": "Empty on a search result — the full bio only comes back from /designer-profile." } } }, "description": "Matching designers." }, "designerCount": { "type": "number", "description": "Number of designers in this response." }, "nextCursor": { "type": "string", "description": "Pass back as cursor to continue, or null when the listing is exhausted." }, "hasNextPage": { "type": "boolean", "description": "Whether more results exist beyond this response." }, "pagesScraped": { "type": "number", "description": "Requests actually made. Each one counts against your plan." }, "totalAvailable": { "type": "number", "description": "Roughly how many results exist. Approximate — it varies with the ordering, drifts between identical requests, and stops rising past 10000. Use it for orientation, not as a count, and page until hasNextPage is false." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a walk that stopped early, a listing MakerWorld truncated, an upstream ceiling that was hit. Read it: an empty array means the result is complete, a non-empty one means it is not." }, "requestedUrl": { "type": "string", "description": "The MakerWorld page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO timestamp of when the data was retrieved." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "designerCount": 2, "notes": [], "designers": [ { "uid": "99120043", "name": "benchy_lab", "handle": "benchylab", "followerCount": 4120, "modelCount": 87, "isVerified": true } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/designer-profile": { "post": { "operationId": "designer-profile", "tags": [ "Designers" ], "summary": "Get a designer's profile", "description": "Read a MakerWorld designer's public profile: name, handle, bio, links, follower and following counts, how many models and print profiles they have published, the likes, downloads, prints and boosts they have received, their level, their verified and official badges, when they joined, and the models they have pinned. MakerWorld does not publish a designer's catalogue, so the models here are their pinned showcase — the counts are complete, the model list is not.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "designer": { "type": "string", "description": "Designer uid, @handle, or MakerWorld profile URL." }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" } }, "additionalProperties": false, "required": [ "designer" ] }, "examples": { "default": { "value": { "designer": "@benchylab" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "type": "object", "additionalProperties": true, "description": "The designer’s public profile record.", "properties": { "uid": { "type": "string", "description": "Designer uid." }, "bio": { "type": "string", "description": "Profile bio text." }, "links": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "External links the designer lists." }, "followerCount": { "type": "number", "description": "Followers, alongside followingCount." }, "modelCount": { "type": "number", "description": "Models the designer has published. A complete count — not the length of pinnedModels." }, "printProfileCount": { "type": "number", "description": "Print profiles published for other people's models." }, "downloadCount": { "type": "number", "description": "Lifetime downloads received, alongside likeCount, collectedCount, printCount and boostCount." }, "level": { "type": "number", "description": "MakerWorld’s publishing-activity level, with isVerified and isOfficial badges." }, "joinedAt": { "type": "string", "description": "When the designer joined MakerWorld." }, "pinnedModels": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "The designer’s showcase models. Not their full catalogue — MakerWorld does not publish one." }, "pinnedModelIds": { "type": "array", "items": { "type": "string" }, "description": "Ids of every pinned model, including those not expanded above. Pass one to /model-detail." } } }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a walk that stopped early, a listing MakerWorld truncated, an upstream ceiling that was hit. Read it: an empty array means the result is complete, a non-empty one means it is not." }, "requestedUrl": { "type": "string", "description": "The MakerWorld page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO timestamp of when the data was retrieved." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "notes": [], "profile": { "uid": "99120043", "name": "benchy_lab", "handle": "benchylab", "followerCount": 4120, "modelCount": 87, "downloadCount": 1204880, "level": 9, "isVerified": true, "joinedAt": "2023-08-02", "pinnedModelIds": [ "412809", "389114" ] } } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/search-collections": { "post": { "operationId": "search-collections", "tags": [ "Collections" ], "summary": "Search collections by keyword", "description": "Search curated MakerWorld collections by keyword, ordered by relevance or likes. Each result carries the collection owner, how many models it holds, how many likes it has, its tags and its cover image — a fast read on how the community itself is grouping models around a theme.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Keyword or phrase to search collections for." }, "sortBy": { "type": "string", "description": "relevance or likes.", "example": "relevance" }, "limit": { "type": "number", "description": "Maximum collections returned (max 500), or -1 for everything available.", "example": "30" }, "pages": { "type": "number", "description": "Requests made while collecting results. One request returns up to 100 items (max 100), or -1 for the maximum allowed.", "example": "1" }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "default": { "value": { "query": "desk organisation", "sortBy": "likes", "limit": 20 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "collections": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "collectionId": { "type": "string", "description": "Collection id — the handle for /collection-detail." }, "title": { "type": "string", "description": "Collection title." }, "modelCount": { "type": "number", "description": "Models in the collection, including any the owner has hidden." }, "likeCount": { "type": "number", "description": "Likes the collection has received." }, "owner": { "type": "object", "additionalProperties": true, "description": "The designer who curated it." } } }, "description": "Matching collections." }, "collectionCount": { "type": "number", "description": "Number of collections in this response." }, "nextCursor": { "type": "string", "description": "Pass back as cursor to continue, or null when the listing is exhausted." }, "hasNextPage": { "type": "boolean", "description": "Whether more results exist beyond this response." }, "pagesScraped": { "type": "number", "description": "Requests actually made. Each one counts against your plan." }, "totalAvailable": { "type": "number", "description": "Roughly how many results exist. Approximate — it varies with the ordering, drifts between identical requests, and stops rising past 10000. Use it for orientation, not as a count, and page until hasNextPage is false." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a walk that stopped early, a listing MakerWorld truncated, an upstream ceiling that was hit. Read it: an empty array means the result is complete, a non-empty one means it is not." }, "requestedUrl": { "type": "string", "description": "The MakerWorld page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO timestamp of when the data was retrieved." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "collectionCount": 20, "hasNextPage": true, "notes": [], "collections": [ { "collectionId": "5512", "title": "Desk tidy essentials", "modelCount": 34, "likeCount": 812, "owner": { "handle": "benchylab" } } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/collection-detail": { "post": { "operationId": "collection-detail", "tags": [ "Collections" ], "summary": "Get one collection and its models", "description": "Read a collection's title, description, owner, tags and like count, plus the models it contains with their popularity counts and URLs, paginated with a cursor. The collection's own modelCount includes models the owner has hidden, so it can exceed the number of models the listing returns.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "collection": { "type": "string", "description": "Collection id, or a MakerWorld collection URL." }, "limit": { "type": "number", "description": "Maximum models returned (max 2000), or -1 for everything available.", "example": "30" }, "pages": { "type": "number", "description": "Requests made while collecting results. One request returns up to 100 items (max 100), or -1 for the maximum allowed.", "example": "1" }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" } }, "additionalProperties": false, "required": [ "collection" ] }, "examples": { "default": { "value": { "collection": "5512", "limit": 50, "pages": 2 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "collectionId": { "type": "string", "description": "The resolved collection id." }, "collection": { "type": "object", "additionalProperties": true, "description": "The collection record.", "properties": { "description": { "type": "string", "description": "Collection description." }, "owner": { "type": "object", "additionalProperties": true, "description": "The designer who curated it." }, "modelCount": { "type": "number", "description": "Models in the collection, including any the owner has hidden — so it can exceed the models returned." }, "models": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "The models in this page of the collection, with designer, license, tags and stats." }, "nextCursor": { "type": "string", "description": "Pass back as cursor to continue through the collection." }, "hasNextPage": { "type": "boolean", "description": "Whether more models remain in the collection." } } }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a walk that stopped early, a listing MakerWorld truncated, an upstream ceiling that was hit. Read it: an empty array means the result is complete, a non-empty one means it is not." }, "requestedUrl": { "type": "string", "description": "The MakerWorld page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO timestamp of when the data was retrieved." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "collectionId": "5512", "notes": [], "collection": { "title": "Desk tidy essentials", "modelCount": 34, "likeCount": 812, "hasNextPage": false, "models": [ { "modelId": "412809", "title": "Under-desk cable tray", "stats": { "downloadCount": 18422 } } ] } } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/categories": { "post": { "operationId": "categories", "tags": [ "Discovery" ], "summary": "List model categories", "description": "Return the MakerWorld category tree. Each node carries the category id that the `categories` filter on a model search takes, plus its name, slug, description, image and child categories. Call it once and cache it — the tree changes rarely.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" } }, "additionalProperties": false }, "examples": { "default": { "value": {} } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "categoryId": { "type": "string", "description": "The id to pass in the categories filter on /search-models." }, "name": { "type": "string", "description": "Display name." }, "slug": { "type": "string", "description": "URL slug MakerWorld uses for the category." }, "children": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Child categories, same shape, nested." } } }, "description": "Top-level category nodes." }, "categoryCount": { "type": "number", "description": "Number of categories in this response." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a walk that stopped early, a listing MakerWorld truncated, an upstream ceiling that was hit. Read it: an empty array means the result is complete, a non-empty one means it is not." }, "requestedUrl": { "type": "string", "description": "The MakerWorld page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO timestamp of when the data was retrieved." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "categoryCount": 12, "notes": [], "categories": [ { "categoryId": "4", "name": "Household", "slug": "household", "children": [ { "categoryId": "41", "name": "Organisation", "slug": "organization" } ] } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/contests": { "post": { "operationId": "contests", "tags": [ "Discovery" ], "summary": "List design contests", "description": "Return MakerWorld's design contests — past, running and upcoming — with each one's theme, brief, start and end dates, entry and participant counts, view count, allowed licenses, remix-only flag, and which phase it is in. Filter by status, or pass `contest` to get a single one. Contests are what drive upload spikes on MakerWorld, so a running contest is the best single predictor of what is about to be published.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contest": { "type": "string", "description": "Return only this contest, by id or contest URL." }, "status": { "type": "string", "description": "Return only contests in this phase: upcoming, running, judging, or finished." }, "limit": { "type": "number", "description": "Maximum contests returned (max 200), or -1 for everything available.", "example": "20" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" } }, "additionalProperties": false }, "examples": { "default": { "value": { "status": "running", "limit": 20 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "contests": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "contestId": { "type": "string", "description": "Contest id — pass it back as contest to read one on its own." }, "theme": { "type": "string", "description": "The contest theme, with name and contestUrl alongside it." }, "rules": { "type": "string", "description": "The contest brief, as HTML." }, "status": { "type": "string", "description": "upcoming, running, judging, or finished." }, "startsAt": { "type": "string", "description": "Start date, with endsAt alongside it." }, "entryCount": { "type": "number", "description": "Models entered." }, "participantCount": { "type": "number", "description": "Distinct designers who entered." }, "allowedLicenses": { "type": "array", "items": { "type": "string" }, "description": "Licenses an entry is allowed to carry." }, "isRemixOnly": { "type": "boolean", "description": "Whether entries must be remixes." } } }, "description": "The contests matching the filter." }, "contestCount": { "type": "number", "description": "Number of contests in this response." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a walk that stopped early, a listing MakerWorld truncated, an upstream ceiling that was hit. Read it: an empty array means the result is complete, a non-empty one means it is not." }, "requestedUrl": { "type": "string", "description": "The MakerWorld page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO timestamp of when the data was retrieved." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "contestCount": 3, "notes": [], "contests": [ { "contestId": "188", "name": "Desk Upgrade Contest", "theme": "Workspace", "status": "running", "startsAt": "2026-09-01", "endsAt": "2026-09-30", "entryCount": 412, "participantCount": 288, "allowedLicenses": [ "CC0", "BY" ] } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/resolve-url": { "post": { "operationId": "resolve-url", "tags": [ "Utility" ], "summary": "Parse a MakerWorld URL", "description": "Turn any MakerWorld URL into structured input: whether it points at a model, a designer, a collection, a contest or a search, plus the id, slug, model type and ordering it encodes. Parsing a URL does not consume a credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Any MakerWorld URL, to be parsed into structured input." }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" } }, "additionalProperties": false, "required": [ "url" ] }, "examples": { "default": { "value": { "url": "https://makerworld.com/en/models/412809-under-desk-cable-tray" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "What the URL points at: model, designer, collection, contest, search, or unknown." }, "modelId": { "type": "string", "description": "Present when kind is model." }, "handle": { "type": "string", "description": "Present when kind is designer." }, "collectionId": { "type": "string", "description": "Present when kind is collection." }, "contestId": { "type": "string", "description": "Present when kind is contest." }, "query": { "type": "string", "description": "Present when kind is search." }, "slug": { "type": "string", "description": "The slug that followed the id, if any." }, "modelType": { "type": "string", "description": "3d or laser, when the URL carries one." }, "sortBy": { "type": "string", "description": "Ordering the URL asks for, verbatim." } }, "additionalProperties": false }, "examples": { "default": { "value": { "kind": "model", "modelId": "412809", "slug": "under-desk-cable-tray", "handle": null, "collectionId": null, "query": null } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/media": { "get": { "operationId": "media", "tags": [ "Utility" ], "summary": "Download a model image", "description": "Stream a model cover, gallery image, render or designer avatar, using a url taken from a model, collection or designer result. Only MakerWorld image hosts are accepted. HTTP Range requests are supported. This is a GET with query parameters, not a JSON POST, and it bills as one request.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "MakerWorld image URL, as returned on a model, collection or designer. Passed as a query parameter.", "schema": { "type": "string" } }, { "name": "filename", "in": "query", "required": false, "description": "Content-Disposition filename to serve the file as (max 200 characters).", "schema": { "type": "string" } }, { "name": "Range", "in": "header", "required": false, "description": "Standard HTTP Range request header, for example bytes=0-65535. Sent as a header, not a query parameter.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } } } }