Docs

Glyphae is a curated 3D asset catalog for AI: real materials, hardware, and decals, documented for the model. This page covers the data model, accounts, and the HTTP API for managing assets from a CLI or AI harness.

The catalog

Each asset is one entry with stable fields. Assets live on R2 at https://assets.glyphae.com/<pack>/<path>; the index is served as JSON (see Manifest). Key fields:

  • id — stable slug (e.g. glacial_concrete).
  • category — material, hardware, or decal.
  • scaleM — real-world longest dimension in meters (null for tileable materials/decals). Place hardware at its real scale; never scale fasteners non-uniformly.
  • license — usage terms (e.g. CC0, Solar Beam (crafted)).
  • ai — docs for the model: whenToUse, optional params, gotchas.
  • pbr — real-time PBR maps + constants (materials only).
  • formats — downloadable representations (GLB, PBR maps, source, fab files), each with ext, label, kind, path.

The manifest

The public index of published assets, in a stable array shape — the canonical entry point for an AI:

GET https://glyphae.com/data/manifest.json

Files resolve against https://assets.glyphae.com/<pack>/<path>.

Accounts & profiles

  • Sign in with a magic link or email + password at /sign-in.
  • Set a public profile (username, website, description) in /account.
  • Your public profile and contributions live at /u/<username>.
  • Create API keys in /account to drive the API below.

API

Base URL https://glyphae.com/api. Reads are public; writes need a session cookie or an API key sent as the x-api-key header. You manage your own contributions; admins may edit the curated catalog. The machine-readable spec is at /api/openapi.json.

Search the catalog (public)

curl "https://glyphae.com/api/assets?category=material&q=concrete"

Query params: q (text), category, pack, limit. Single asset: GET /api/assets/<id>.

Create an asset

curl -X POST https://glyphae.com/api/assets \
  -H "x-api-key: $GLYPHAE_KEY" \
  -H "content-type: application/json" \
  -d '{
    "id": "brushed_steel_01",
    "name": "Brushed Steel 01",
    "pack": "studio",
    "category": "material",
    "scaleM": null,
    "license": "CC0",
    "description": "Fine linear brushed stainless.",
    "preview": "studio/brushed_steel_01/preview.png",
    "ai": { "whenToUse": "Appliances, fixtures, anodized panels." },
    "formats": [],
    "status": "PUBLISHED"
  }'

PATCH /api/assets/<id> updates fields or status(DRAFT / PUBLISHED); DELETE /api/assets/<id>removes it. New contributions default to DRAFT (hidden from the gallery until you publish).

Uploading files

Binaries go straight to R2 via a presigned PUT — the server never proxies bytes:

# 1) ask for a presigned PUT (contributor files are namespaced under u/<your-id>)
curl -X POST https://glyphae.com/api/uploads \
  -H "x-api-key: $GLYPHAE_KEY" -H "content-type: application/json" \
  -d '{ "path": "brushed_steel_01/albedo.jpg", "contentType": "image/jpeg" }'
# -> { "key": "u/<id>/brushed_steel_01/albedo.jpg", "uploadUrl": "https://...", "publicUrl": "..." }

# 2) upload the bytes straight to R2 (Content-Type must match the one you requested)
curl -X PUT "$UPLOAD_URL" -H "content-type: image/jpeg" --data-binary @albedo.jpg

# 3) set the asset's preview / format paths via POST/PATCH /api/assets

Contributor keys write under your own namespace (u/<your-id>); any pack you send is honored only for admins (who manage curated packs). contentType must be an image, glTF/GLB, or zip type.

CLI / AI harness quickstart

  1. Create an API key in /account (shown once — store it).
  2. Export it: export GLYPHAE_KEY=glyphae_…
  3. Read the catalog from /data/manifest.json; search via GET /api/assets.
  4. Manage assets with POST/PATCH/DELETE /api/assets and POST /api/uploads.

An MCP server and a glyph CLI wrapping this API are the next surface; the HTTP API + keys are the stable foundation they build on.