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

RequestWhat you get
GET /api/v1/materialsSearch 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}/similarSimilar materials, limit up to 24.
GET /api/v1/taxonomyThe material tree and every facet, each value with its definition.
GET /api/v1/openapi.jsonThis 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.

RequestWhat it does
POST /api/v1/uploadsA 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/uploadsEverything 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; estimated says so.
  • needs_review is 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.