API
Every material in the atlas, as JSON. Free, no key needed to read, and every answer allows any website to read it (CORS). Each material is classified the same way: its place in the material tree, pattern, layout, finish, condition, usage, style, colour, sheen, real-world size and tags.
Endpoints
| Request | What you get |
|---|---|
GET /api/v1/materials | Search and filter. q, category, sort (name, light, dark, size, resolution, id), offset, limit up to 100, and any Browse filter: color, sheen, metallic, finish, condition, pattern, layout, usage, style, maps, features, resolution, size, license, lightness. Values are comma-separated ids from the taxonomy. |
GET /api/v1/materials/{id} | One material's full record: name, description, its place in the material tree, every classified field, tags, real-world size, maps, resolutions with download sizes, file formats and license. |
GET /api/v1/materials/{id}/similar | Similar materials, limit up to 24. |
GET /api/v1/taxonomy | The material tree and every facet, each value with its definition. |
GET /api/v1/openapi.json | This API in OpenAPI 3.1, for tools and AI agents. |
Examples
Seamless, weathered wood:
curl 'https://pbratlas.com/api/v1/materials?category=wood&condition=weathered&features=seamless' Every material, page by page, in an order that does not change: follow next until it is null.
curl 'https://pbratlas.com/api/v1/materials?sort=id&limit=100' One material:
curl 'https://pbratlas.com/api/v1/materials/km8kamub' Sharing materials
Software can share materials for its users, PBRdesigner included. Make a key on your account page and send it with every request: Authorization: Bearer <key>. A shared material is checked, previewed and classified like every material here, and goes live after a quick review.
| Request | What it does |
|---|---|
POST /api/v1/uploads | A multipart form: license (CC0-1.0 or CC-BY-4.0), credit_name (optional; without it no name is shown), and either package, a PBR Atlas .zip from PBRdesigner, or the maps, each under its role: baseColor, normal, roughness, metalness, ao, height, opacity, emissive, or maps to have the role read from the file name. Maps are at least 1,024 pixels and all one size. Optionally describe it: descriptive_name, description, material (a node of the taxonomy), pattern, layout, finish, condition, style, usage (repeat it), tags (comma separated). What you leave out is filled in after review; what you give stands. Answers 202 with the upload and its status_url. |
GET /api/v1/uploads/{id} | Its status: received, processing, review, classifying (approved, being described), approved (live, with its page), rejected (with the reviewer's reason) or failed (with what to change). |
GET /api/v1/uploads | Everything your account has shared. |
DELETE /api/v1/uploads/{id} | Takes it down and deletes its files. |
curl -H 'Authorization: Bearer <key>' -F license=CC0-1.0 -F credit_name='Your name' -F package=@material.zip https://pbratlas.com/api/v1/uploads Good to know
- Ids are permanent. Names and fields can improve as classification does.
- Real-world sizes are estimated from what the material shows;
estimatedsays so. needs_reviewis true when one of a material's classified fields has low confidence.- Downloading the maps needs a free account on the site.
- Errors come back as
{"error": {"status", "message"}}with the HTTP status.