{ "openapi": "3.1.0", "info": { "title": "Printables API", "version": "1.0.0", "description": "Public Printables 3D models, designers, collections and design contests exposed through FetchLayer as structured JSON." }, "servers": [ { "url": "https://api.fetchlayer.dev/printables" } ], "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 public Printables models by keyword or phrase. Filter by category, licence, material, printer, design tool, nozzle size, price, print time, finished weight, filament use, featured and contest-winning status, and publication date, then page through the results with a cursor. Every id-shaped filter here takes an id from /filter-values, not a name.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Keyword or phrase to search Printables models for." }, "sort": { "type": "string", "description": "best_match, latest, popular, rating, or makes_count.", "example": "best_match" }, "licenseIds": { "type": "array", "items": { "type": "string" }, "description": "Restrict to these licences, by id (max 20). Ids come from /filter-values." }, "printerIds": { "type": "array", "items": { "type": "number" }, "description": "Restrict to models with sliced files for these printers, by id (max 20). There are 639 printer ids — read them from /filter-values." }, "modelingAppIds": { "type": "array", "items": { "type": "string" }, "description": "Restrict to models made with these design tools, by id (max 20). Ids come from /filter-values." }, "nozzleDiameters": { "type": "array", "items": { "type": "number" }, "description": "Restrict to sliced files for these nozzle sizes in millimetres, for example 0.4 (max 10)." }, "fileKinds": { "type": "array", "items": { "type": "string" }, "description": "Which ready-to-print files a model must carry: GCODE, SLA, or NONE." }, "printDuration": { "type": "object", "additionalProperties": true, "description": "Print time range in hours, as { from, to }." }, "weight": { "type": "object", "additionalProperties": true, "description": "Finished weight range in grams, as { from, to }." }, "usedMaterial": { "type": "object", "additionalProperties": true, "description": "Filament used range in grams, as { from, to }." }, "publishedWithinDays": { "type": "number", "description": "Only models published in the last N days (max 3650)." }, "categoryId": { "type": "string", "description": "Restrict to one category, by id. Ids come from /filter-values." }, "materialIds": { "type": "array", "items": { "type": "number" }, "description": "Restrict to models for these materials, by id (max 20). Ids come from /filter-values." }, "price": { "type": "string", "description": "all, paid, or free.", "example": "all" }, "featured": { "type": "boolean", "description": "Only models Printables has featured." }, "hasMake": { "type": "boolean", "description": "Only models somebody has posted a printed copy of." }, "aiGenerated": { "type": "boolean", "description": "Filter on whether the model was AI generated." }, "contestWinnersOnly": { "type": "boolean", "description": "Only models that placed in a contest." }, "limit": { "type": "number", "description": "Maximum models returned (max 2000), or -1 for everything available.", "example": "30" }, "pages": { "type": "number", "description": "Pages of results to collect in one request (max 100), or -1 for the maximum allowed." }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "format": { "type": "string", "description": "json, or markdown to get the result rendered as text.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "default": { "value": { "query": "cable management", "sort": "popular", "price": "free", "hasMake": true, "limit": 30 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "additionalProperties": true, "description": "The filters this search actually ran with, after defaults were resolved." }, "totalMatches": { "type": [ "number", "null" ], "description": "Models matching the query across all of Printables, before paging." }, "models": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Model id — the handle for /model-detail." }, "name": { "type": [ "string", "null" ], "description": "Model title as published." }, "url": { "type": "string", "description": "Public Printables permalink for the model." }, "publishedAt": { "type": [ "string", "null" ], "description": "When the current version was published." }, "firstPublishedAt": { "type": [ "string", "null" ], "description": "When the model first went public, which can predate publishedAt." }, "category": { "type": "object", "additionalProperties": true, "description": "Category the designer filed it under, with its id and name." }, "designer": { "type": "object", "additionalProperties": true, "description": "Designer id, handle, display name, profile URL, avatar, verification and company flag." }, "image": { "type": "object", "additionalProperties": true, "description": "Cover image, with its absolute URL and dimensions. The full gallery is on /model-detail." }, "stats": { "type": "object", "additionalProperties": true, "description": "Downloads, likes, views, makes, comments, rating average and count, collections, file and image counts." }, "price": { "type": [ "number", "null" ], "description": "Store price, or null for a free model." }, "clubExclusive": { "type": "boolean", "description": "True when the model sits behind a paid membership." }, "latestContestPlacement": { "type": "object", "additionalProperties": true, "description": "Most recent contest placing, when the model has one." } } }, "description": "The matching models." }, "modelCount": { "type": "number", "description": "Models in this response." }, "pagesScraped": { "type": "number", "description": "Pages actually collected. Each page counts as one request against your plan." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass back as cursor to continue, or null when the listing is exhausted." }, "hasNextPage": { "type": "boolean", "description": "Whether more results are available beyond this response." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a truncated walk, a listing that may be incomplete, an upstream limit. Read it before treating a result set as complete." }, "requestedUrl": { "type": "string", "description": "The Printables page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "resultType": { "type": "string", "description": "Which shape this response is, e.g. model-search or contest-detail." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "model-search", "totalMatches": 1842, "modelCount": 30, "pagesScraped": 1, "hasNextPage": true, "notes": [], "models": [ { "id": "512345", "name": "Under-desk cable tray", "url": "https://www.printables.com/model/512345-under-desk-cable-tray", "designer": { "id": "90210", "handle": "printsmith", "displayName": "PrintSmith" }, "stats": { "downloads": 41280, "likes": 1832, "makes": 214, "ratingAverage": 4.9 }, "price": null } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/browse-models": { "post": { "operationId": "browse-models", "tags": [ "Models" ], "summary": "Browse models without a keyword", "description": "Return models from one category or from all of Printables, ordered by trending, newest, rating, makes, views or likes. This is the endpoint for trend research: a keyword search answers \"who made a thing like this\", browsing answers \"what is the community printing this week\".", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sort": { "type": "string", "description": "trending, latest, rating, makes, views, or likes.", "example": "trending" }, "tagIds": { "type": "array", "items": { "type": "number" }, "description": "Restrict to models carrying these tags, by id (max 20) — tag ids, not tag names." }, "categoryId": { "type": "string", "description": "Restrict to one category, by id. Ids come from /filter-values." }, "materialIds": { "type": "array", "items": { "type": "number" }, "description": "Restrict to models for these materials, by id (max 20). Ids come from /filter-values." }, "price": { "type": "string", "description": "all, paid, or free.", "example": "all" }, "featured": { "type": "boolean", "description": "Only models Printables has featured." }, "hasMake": { "type": "boolean", "description": "Only models somebody has posted a printed copy of." }, "aiGenerated": { "type": "boolean", "description": "Filter on whether the model was AI generated." }, "contestWinnersOnly": { "type": "boolean", "description": "Only models that placed in a contest." }, "limit": { "type": "number", "description": "Maximum models returned (max 2000), or -1 for everything available.", "example": "30" }, "pages": { "type": "number", "description": "Pages of results to collect in one request (max 100), or -1 for the maximum allowed." }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "format": { "type": "string", "description": "json, or markdown to get the result rendered as text.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false }, "examples": { "default": { "value": { "sort": "trending", "categoryId": "1", "price": "free", "limit": 50, "pages": 2 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "additionalProperties": true, "description": "The browse filters applied, after defaults were resolved." }, "models": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Model id — the handle for /model-detail." }, "name": { "type": [ "string", "null" ], "description": "Model title as published." }, "url": { "type": "string", "description": "Public Printables permalink for the model." }, "publishedAt": { "type": [ "string", "null" ], "description": "When the current version was published." }, "firstPublishedAt": { "type": [ "string", "null" ], "description": "When the model first went public, which can predate publishedAt." }, "category": { "type": "object", "additionalProperties": true, "description": "Category the designer filed it under, with its id and name." }, "designer": { "type": "object", "additionalProperties": true, "description": "Designer id, handle, display name, profile URL, avatar, verification and company flag." }, "image": { "type": "object", "additionalProperties": true, "description": "Cover image, with its absolute URL and dimensions. The full gallery is on /model-detail." }, "stats": { "type": "object", "additionalProperties": true, "description": "Downloads, likes, views, makes, comments, rating average and count, collections, file and image counts." }, "price": { "type": [ "number", "null" ], "description": "Store price, or null for a free model." }, "clubExclusive": { "type": "boolean", "description": "True when the model sits behind a paid membership." }, "latestContestPlacement": { "type": "object", "additionalProperties": true, "description": "Most recent contest placing, when the model has one." } } }, "description": "The matching models." }, "modelCount": { "type": "number", "description": "Models in this response." }, "pagesScraped": { "type": "number", "description": "Pages actually collected. Each page counts as one request against your plan." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass back as cursor to continue, or null when the listing is exhausted." }, "hasNextPage": { "type": "boolean", "description": "Whether more results are available beyond this response." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a truncated walk, a listing that may be incomplete, an upstream limit. Read it before treating a result set as complete." }, "requestedUrl": { "type": "string", "description": "The Printables page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "resultType": { "type": "string", "description": "Which shape this response is, e.g. model-search or contest-detail." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "model-browse", "modelCount": 50, "pagesScraped": 2, "hasNextPage": true, "notes": [], "filters": { "sort": "trending", "categoryId": "1", "price": "free" }, "models": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/model-detail": { "post": { "operationId": "model-detail", "tags": [ "Models" ], "summary": "Get one model in full", "description": "Everything Printables publishes for a single model: the long description as HTML, the licence, the tags, every gallery image, the complete file listing with per-file slicing settings, the models it was remixed from, every contest placing, and the full counter set. Accepts a model id or any Printables model URL. Files are described — name, size, kind, printer, material, layer height, estimated time and filament — but carry no download URL, because Printables issues model-file downloads only to a signed-in account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Model id, or a Printables model URL containing one." }, "format": { "type": "string", "description": "json, or markdown to get the result rendered as text.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "model" ] }, "examples": { "default": { "value": { "model": "https://www.printables.com/model/512345-under-desk-cable-tray" } } } } } }, "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": { "summary": { "type": [ "string", "null" ], "description": "Short plain-text blurb." }, "descriptionHtml": { "type": [ "string", "null" ], "description": "The designer's long description, as HTML." }, "license": { "type": "object", "additionalProperties": true, "description": "The licence the model is published under." }, "tags": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Tags the designer applied, with their ids." }, "images": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Every gallery image, ordered; order 0 is the cover. Pass a url to GET /media to stream the bytes." }, "files": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "printSettings": { "type": "object", "additionalProperties": true, "description": "Layer height, nozzle diameter, estimated print hours, filament grams, printer and material. Present only on a sliced file." } } }, "description": "The file listing. Each entry carries name, sizeBytes, kind (geometry or sliced), folder, note and uploadedAt — but no download URL, because Printables publishes none." }, "printSettings": { "type": "object", "additionalProperties": true, "description": "Settings recorded for the model as a whole, including whether it is multi-material." }, "authorship": { "type": [ "string", "null" ], "description": "own, remix, or reupload." }, "remixedFrom": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Models this one was derived from, with ids and URLs." }, "contestPlacements": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Every contest placing, not just the most recent." }, "instructionsPdfUrl": { "type": [ "string", "null" ], "description": "The designer's printing instructions, when they attached any. Streamable through GET /media." }, "fileKind": { "type": [ "string", "null" ], "description": "Which ready-to-print file kind the model ships, when any." }, "stats": { "type": "object", "additionalProperties": true, "description": "Downloads, likes, views, makes, comments, rating average and count, collections, file and image counts." } } }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a truncated walk, a listing that may be incomplete, an upstream limit. Read it before treating a result set as complete." }, "requestedUrl": { "type": "string", "description": "The Printables page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "resultType": { "type": "string", "description": "Which shape this response is, e.g. model-search or contest-detail." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "model-detail", "modelId": "512345", "notes": [], "model": { "id": "512345", "name": "Under-desk cable tray", "license": { "id": "7", "name": "CC BY-NC-SA 4.0" }, "authorship": "own", "fileKind": "GCODE", "files": [ { "id": "88121", "name": "tray_body.stl", "sizeBytes": 2184320, "kind": "geometry", "printSettings": null } ], "printSettings": { "layerHeightsMm": [ 0.2 ], "printDurationHours": 4.5, "weightGrams": 62, "multiMaterial": false } } } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/user-profile": { "post": { "operationId": "user-profile", "tags": [ "Designers" ], "summary": "Get a designer's profile", "description": "Read a Printables designer's public profile: handle and display name, biography, join date, verification status and date, follower and following counts, makes posted, total downloads across everything they have published, public collection count, and the gamified profile level. Accepts a handle, an @handle, a profile URL, or a numeric designer id.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "description": "Designer handle, @handle, profile URL, or numeric designer id." }, "format": { "type": "string", "description": "json, or markdown to get the result rendered as text.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "user" ] }, "examples": { "default": { "value": { "user": "@printsmith" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "description": "The resolved designer id." }, "profile": { "type": "object", "additionalProperties": true, "description": "The designer record.", "properties": { "handle": { "type": [ "string", "null" ], "description": "The @name in the profile URL." }, "displayName": { "type": [ "string", "null" ], "description": "Display name, which can differ from the handle." }, "bio": { "type": [ "string", "null" ], "description": "Free-text biography, as plain text." }, "joinedAt": { "type": [ "string", "null" ], "description": "When the account was created." }, "verified": { "type": "boolean", "description": "Whether Printables has verified the account." }, "isCompany": { "type": "boolean", "description": "True when the account is a company rather than an individual." }, "followers": { "type": [ "number", "null" ], "description": "Follower count." }, "following": { "type": [ "number", "null" ], "description": "Accounts this designer follows." }, "makes": { "type": [ "number", "null" ], "description": "Photos of other people's models this designer printed and posted." }, "downloads": { "type": [ "number", "null" ], "description": "Total downloads across every model the designer published." }, "collections": { "type": [ "number", "null" ], "description": "Public collections the designer maintains." }, "profileLevel": { "type": [ "number", "null" ], "description": "The gamified profile level Printables shows on the designer page." } } }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a truncated walk, a listing that may be incomplete, an upstream limit. Read it before treating a result set as complete." }, "requestedUrl": { "type": "string", "description": "The Printables page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "resultType": { "type": "string", "description": "Which shape this response is, e.g. model-search or contest-detail." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "user-profile", "userId": "90210", "notes": [], "profile": { "id": "90210", "handle": "printsmith", "displayName": "PrintSmith", "verified": true, "followers": 12840, "downloads": 1840221, "profileLevel": 9 } } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/user-models": { "post": { "operationId": "user-models", "tags": [ "Designers" ], "summary": "List a designer’s published models", "description": "Every model one designer has published, newest first, paged the same way as a search. Use it to measure a creator: how often they publish, what they publish into, and how downloads and makes are distributed across their catalogue rather than concentrated in one hit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "description": "Designer handle, @handle, profile URL, or numeric designer id." }, "limit": { "type": "number", "description": "Maximum models returned (max 2000), or -1 for everything available.", "example": "30" }, "pages": { "type": "number", "description": "Pages of results to collect in one request (max 100), or -1 for the maximum allowed." }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "format": { "type": "string", "description": "json, or markdown to get the result rendered as text.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "user" ] }, "examples": { "default": { "value": { "user": "printsmith", "limit": 200, "pages": 5 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "description": "The resolved designer id." }, "models": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Model id — the handle for /model-detail." }, "name": { "type": [ "string", "null" ], "description": "Model title as published." }, "url": { "type": "string", "description": "Public Printables permalink for the model." }, "publishedAt": { "type": [ "string", "null" ], "description": "When the current version was published." }, "firstPublishedAt": { "type": [ "string", "null" ], "description": "When the model first went public, which can predate publishedAt." }, "category": { "type": "object", "additionalProperties": true, "description": "Category the designer filed it under, with its id and name." }, "designer": { "type": "object", "additionalProperties": true, "description": "Designer id, handle, display name, profile URL, avatar, verification and company flag." }, "image": { "type": "object", "additionalProperties": true, "description": "Cover image, with its absolute URL and dimensions. The full gallery is on /model-detail." }, "stats": { "type": "object", "additionalProperties": true, "description": "Downloads, likes, views, makes, comments, rating average and count, collections, file and image counts." }, "price": { "type": [ "number", "null" ], "description": "Store price, or null for a free model." }, "clubExclusive": { "type": "boolean", "description": "True when the model sits behind a paid membership." }, "latestContestPlacement": { "type": "object", "additionalProperties": true, "description": "Most recent contest placing, when the model has one." } } }, "description": "The matching models." }, "modelCount": { "type": "number", "description": "Models in this response." }, "pagesScraped": { "type": "number", "description": "Pages actually collected. Each page counts as one request against your plan." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass back as cursor to continue, or null when the listing is exhausted." }, "hasNextPage": { "type": "boolean", "description": "Whether more results are available beyond this response." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a truncated walk, a listing that may be incomplete, an upstream limit. Read it before treating a result set as complete." }, "requestedUrl": { "type": "string", "description": "The Printables page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "resultType": { "type": "string", "description": "Which shape this response is, e.g. model-search or contest-detail." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "user-models", "userId": "90210", "modelCount": 143, "pagesScraped": 4, "hasNextPage": false, "nextCursor": null, "notes": [], "models": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/user-collections": { "post": { "operationId": "user-collections", "tags": [ "Designers" ], "summary": "List a designer's public collections", "description": "The collections a designer has made public, each with its model count, likes, timestamps and a sample of its cover thumbnails. Collections are curation signal: what a maker saves tells you what they are about to print, and which models the community keeps filing away.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "description": "Designer handle, @handle, profile URL, or numeric designer id." }, "format": { "type": "string", "description": "json, or markdown to get the result rendered as text.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "user" ] }, "examples": { "default": { "value": { "user": "printsmith" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "description": "The resolved designer id." }, "collections": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Collection id — the handle for /collection-detail." }, "name": { "type": [ "string", "null" ], "description": "Collection name." }, "modelCount": { "type": [ "number", "null" ], "description": "Models in the collection. This is the real total." }, "likes": { "type": [ "number", "null" ], "description": "Likes on the collection." }, "sampleModels": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "A sample of the models, not the whole list — Printables publishes only the cover thumbnails." } } }, "description": "The designer’s public collections." }, "collectionCount": { "type": "number", "description": "Collections in this response." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a truncated walk, a listing that may be incomplete, an upstream limit. Read it before treating a result set as complete." }, "requestedUrl": { "type": "string", "description": "The Printables page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "resultType": { "type": "string", "description": "Which shape this response is, e.g. model-search or contest-detail." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "user-collections", "userId": "90210", "collectionCount": 6, "notes": [], "collections": [ { "id": "4412", "name": "Desk upgrades", "modelCount": 28, "likes": 94 } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/collection-detail": { "post": { "operationId": "collection-detail", "tags": [ "Collections" ], "summary": "Get one collection", "description": "A single collection: name, description, owner, model count, likes and timestamps. Accepts a collection id or a Printables collection URL. Printables publishes only the collection's cover thumbnails, so sampleModels is a sample — modelCount is the authoritative total, and the full member list is not public.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "collection": { "type": "string", "description": "Collection id, or a Printables collection URL." }, "format": { "type": "string", "description": "json, or markdown to get the result rendered as text.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "collection" ] }, "examples": { "default": { "value": { "collection": "https://www.printables.com/collection/4412-desk-upgrades" } } } } } }, "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": { "name": { "type": [ "string", "null" ], "description": "Collection name." }, "descriptionHtml": { "type": [ "string", "null" ], "description": "Description as authored, as HTML." }, "owner": { "type": "object", "additionalProperties": true, "description": "The designer who owns the collection." }, "modelCount": { "type": [ "number", "null" ], "description": "Models in the collection — the real total." }, "likes": { "type": [ "number", "null" ], "description": "Likes on the collection." }, "sampleModels": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "A sample of members, each with id, slug, URL and cover image. Not the full list." } } }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a truncated walk, a listing that may be incomplete, an upstream limit. Read it before treating a result set as complete." }, "requestedUrl": { "type": "string", "description": "The Printables page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "resultType": { "type": "string", "description": "Which shape this response is, e.g. model-search or contest-detail." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "collection-detail", "collectionId": "4412", "notes": [], "collection": { "id": "4412", "name": "Desk upgrades", "modelCount": 28, "likes": 94, "owner": { "handle": "printsmith" }, "sampleModels": [] } } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/contests": { "post": { "operationId": "contests", "tags": [ "Contests" ], "summary": "List design contests", "description": "The Printables design contests, each with its id, name, slug, URL, rules and prize list as authored by the organiser, and entry count. Contests are where Prusa points the community for a month at a time, so the entry counts are a clean read on what themes pull makers in. The ids returned here are what /contest-detail takes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "description": "json, or markdown to get the result rendered as text.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false }, "examples": { "default": { "value": {} } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "contests": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Contest id — the handle for /contest-detail." }, "name": { "type": [ "string", "null" ], "description": "Contest name." }, "url": { "type": "string", "description": "Public contest permalink." }, "descriptionHtml": { "type": [ "string", "null" ], "description": "Rules and prize list, as authored by the organiser." }, "entryCount": { "type": [ "number", "null" ], "description": "Models entered into the contest." } } }, "description": "The design contests." }, "contestCount": { "type": "number", "description": "Contests in this response." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a truncated walk, a listing that may be incomplete, an upstream limit. Read it before treating a result set as complete." }, "requestedUrl": { "type": "string", "description": "The Printables page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "resultType": { "type": "string", "description": "Which shape this response is, e.g. model-search or contest-detail." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "contests", "contestCount": 42, "notes": [], "contests": [ { "id": "312", "name": "Kitchen Helpers", "url": "https://www.printables.com/contest/312-kitchen-helpers", "entryCount": 486 } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/contest-detail": { "post": { "operationId": "contest-detail", "tags": [ "Contests" ], "summary": "Get one contest and its winners", "description": "One contest with its placed entries, best placing first, each carrying the winning model in full summary form — designer, category, stats and cover image. Accepts a contest id or a Printables contest URL. A contest winner list is the closest thing Printables has to an editorial ranking, which makes it a useful training set for what the community rewards.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contest": { "type": "string", "description": "Contest id, or a Printables contest URL." }, "format": { "type": "string", "description": "json, or markdown to get the result rendered as text.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "contest" ] }, "examples": { "default": { "value": { "contest": "312" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "contestId": { "type": "string", "description": "The resolved contest id." }, "contest": { "type": "object", "additionalProperties": true, "description": "The contest record.", "properties": { "name": { "type": [ "string", "null" ], "description": "Contest name." }, "descriptionHtml": { "type": [ "string", "null" ], "description": "Rules and prize list, as authored by the organiser." }, "entryCount": { "type": [ "number", "null" ], "description": "Models entered into the contest." }, "winners": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "placement": { "type": [ "number", "null" ], "description": "1 is first place." }, "model": { "type": "object", "additionalProperties": true, "description": "The winning model, in the same shape as a search result." } } }, "description": "Placed entries, best placing first." } } }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a truncated walk, a listing that may be incomplete, an upstream limit. Read it before treating a result set as complete." }, "requestedUrl": { "type": "string", "description": "The Printables page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "resultType": { "type": "string", "description": "Which shape this response is, e.g. model-search or contest-detail." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "contest-detail", "contestId": "312", "notes": [], "contest": { "id": "312", "name": "Kitchen Helpers", "entryCount": 486, "winners": [ { "placement": 1, "model": { "id": "498112", "name": "Magnetic spice rack", "stats": { "downloads": 88210, "makes": 512 } } } ] } } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/filter-values": { "post": { "operationId": "filter-values", "tags": [ "Utility" ], "summary": "Get the ids the filters take", "description": "The filter vocabulary a model search needs: the category tree with each node’s path and children, the licences, the materials, the printers, and the design tools — each with the id to pass. Every id-shaped filter on /search-models and /browse-models takes an id, never a name, and an id that does not exist returns an empty result set rather than an error. There are 639 valid printer values alone, so guessing \"Prusa MK4\" instead of its id is the single most common way to get zero results from a query that looks correct. Call this once, cache it, and map names to ids yourself. It does not consume a credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "description": "json, or markdown to get the result rendered as text.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "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": { "id": { "type": "string", "description": "Pass as categoryId on a search or browse." }, "level": { "type": [ "number", "null" ], "description": "Depth in the tree; 0 is a top-level category." } } }, "description": "The category tree. Each node carries its id, name, English name, ancestor path, depth level, and immediate children." }, "licenses": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Licences, with the ids to pass as licenseIds." }, "materials": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Filaments and resins, with the ids to pass as materialIds." }, "printers": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Printers a model’s sliced files can be filtered by, with id, name, family, and whether it is a Prusa machine. This is the long list — 639 values." }, "modelingApps": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Design tools, with the ids to pass as modelingAppIds." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a truncated walk, a listing that may be incomplete, an upstream limit. Read it before treating a result set as complete." }, "requestedUrl": { "type": "string", "description": "The Printables page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "resultType": { "type": "string", "description": "Which shape this response is, e.g. model-search or contest-detail." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "taxonomy", "notes": [], "categories": [ { "id": "1", "name": "Art & design", "nameEn": "Art & design", "level": 0, "children": [ { "id": "14", "name": "Sculptures" } ] } ], "licenses": [ { "id": "7", "name": "CC BY-NC-SA 4.0" } ], "materials": [ { "id": "1", "name": "PLA" } ], "printers": [ { "id": "287", "name": "Original Prusa MK4", "family": "Original Prusa", "isPrusa": true } ], "modelingApps": [ { "id": "3", "name": "Fusion 360" } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/resolve-url": { "post": { "operationId": "resolve-url", "tags": [ "Utility" ], "summary": "Parse a Printables URL", "description": "Turn any Printables URL into structured fields: whether it points at a model, a designer, a collection, a contest or a search, plus the id or keyword it carries and any sort or category encoded in the query string. Useful for turning a pasted link into an argument for one of the other routes. It makes no upstream request and does not consume a credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Any Printables URL, to be parsed into structured fields." }, "format": { "type": "string", "description": "json, or markdown to get the result rendered as text.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "url" ] }, "examples": { "default": { "value": { "url": "https://www.printables.com/model/512345-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, user, collection, contest, search, or unknown." }, "modelId": { "type": "string", "description": "Present when kind is model." }, "handle": { "type": "string", "description": "Present when kind is user — the @name from the profile URL." }, "userId": { "type": [ "string", "null" ], "description": "Present when kind is user and the URL carries the designer's id; otherwise null." }, "collectionId": { "type": "string", "description": "Present when kind is collection." }, "contestId": { "type": [ "string", "null" ], "description": "Present when kind is contest; null when the URL names the contest by slug alone." }, "query": { "type": "string", "description": "Present when kind is search — the keyword the URL searched for." }, "url": { "type": "string", "description": "The URL as parsed, normalized." }, "sort": { "type": [ "string", "null" ], "description": "Ordering the URL encodes, when it carries one." }, "categoryId": { "type": [ "string", "null" ], "description": "Category id the URL encodes, when it carries one." } }, "additionalProperties": false }, "examples": { "default": { "value": { "kind": "model", "modelId": "512345", "slug": "under-desk-cable-tray", "url": "https://www.printables.com/model/512345-under-desk-cable-tray", "sort": null, "categoryId": null } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/media": { "get": { "operationId": "media", "tags": [ "Utility" ], "summary": "Download an image or document", "description": "Stream a Printables image or attached document: a gallery image, a file preview, a designer avatar, or the printing-instructions PDF, using a url taken from a model result. Only Printables media hosts are accepted. HTTP Range requests are supported, so a large file can be fetched in pieces. This is a GET with query parameters, not a JSON POST, and it bills as one request. It does not serve model files — Printables publishes no public download URL for geometry or sliced files.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Printables image or document URL, as returned on a model. 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": [] } ] } } } }