Endpoint reference

Every route on this page is public and needs no API key. The agent routes send these CORS (cross-origin resource sharing) headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Accept

/openapi.json describes every route below in OpenAPI 3.1.

Discovery

/api/materials lists only the materials that the Shader Library shows. Retired materials are left out. Image effects are listed separately under imageEffects ({ categories, count, effects, requiresWebGPU, usage }). Shader Library describes the material fields.

Generation

The kinds are template (the default), background, element-brief and design-sequence. A design-sequence response is a response-schema-1 envelope whose document is a version-3 compatibility source for Design Lab, the layered composition tool. Apply that document with applySource in /studio. Design Lab normalizes it to CanvasDocument schema 2 with Design Lab source version 4. Read the source again, then export with design.export. Generation API has the request fields.

Errors return { error: { code, field, message }, schemaVersion: 1 }:

Brand identity

Both GET routes send Cache-Control: public, max-age=300 and both POST routes send no-store. POST /api/brand/kit responds with Content-Type: <type>; charset=utf-8 and Content-Disposition: inline with the file name tokens.json, brand.css, tailwind.css or brand.md. The CSS and Tailwind files reference fonts at ../fonts/…. The font files, the ZIP and the logo pack come only from the Browser API action identity.export.kit.

Both routes are stateless. They store nothing and fetch no remote URL. Asset and font paths must be data: URLs or paths on the Glyphfield origin. Invalid source is not an HTTP error on /api/brand/validate. That route returns ok: false with issues[], and each issue has a path, a code and a message. /api/brand/kit returns 400 invalid_identity and names the first invalid path. Both routes return 400 invalid_json, 400 unknown_field, 413 request_too_large above 5,250,000 bytes, 415 unsupported_media_type for a body that is not JSON, and 500 brand_request_failed.

Browser API

Every active Studio tool registers the Browser API (window.glyphfield.studio, version 1). It operates controls by accessible label, reads and applies source, runs tool actions and downloads returned Blobs. Studio Browser API documents it.

Supporting routes

/api/surface-textures/{assetId}/{map} accepts only the asset IDs in the open surface library (/api/catalog lists them under surfaceLibrary.openPbrAssets) and the maps color, displacement, metalness, normal and roughness. It does not proxy arbitrary URLs. Responses carry X-Surface-License and X-Surface-Provider headers and Cache-Control: public, max-age=86400, s-maxage=2592000, stale-while-revalidate=604800. An unknown asset or map, or a map that the asset does not include, returns 404. An unreachable or failing upstream host returns 502.

/api/github-stars caches a successful count for five minutes (s-maxage=300, stale-while-revalidate=3600). When GitHub does not answer, it returns 503 with stars: null, and clients must accept that response.

Discovery order

1. /llms.txt, then /api/agent.
2. /api/labs.
3. The catalog for the task: /api/materials, /api/identities, /api/elements or /api/catalog.
4. GET /api/generate before an HTTP generation request.
5. /api/docs/{slug} or /llms-full.txt for operating detail.

Catalog IDs, schemas and action lists returned by these routes are authoritative. When the contract from GET /api/generate differs from this documentation, the contract is correct.