REST API

Authentication

All API requests require an API key sent as a Bearer token. Generate a key from Connected Apps in your account settings. API access requires a paid plan.

Authorization: Bearer ph_...

All responses are JSON. Errors return { "error": "..." } with an appropriate HTTP status code.

Endpoints

GET /api/custom-sheet-templates

List all custom sheet templates owned by the authenticated user.

curl https://polyhedral.co/api/custom-sheet-templates \
  -H "Authorization: Bearer ph_..."

Returns an array of template objects.

POST /api/custom-sheet-templates

Create a new template. Required fields: name, code, buildType.

curl -X POST https://polyhedral.co/api/custom-sheet-templates \
  -H "Authorization: Bearer ph_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sci-Fi Character",
    "code": "<Section title=\"Stats\"><Field name=\"hp\" type=\"number\" /></Section>",
    "buildType": "in-app",
    "description": "A sci-fi RPG character sheet",
    "fieldSchema": [
      { "name": "hp", "type": "number", "label": "Hit Points", "default": 10 }
    ]
  }'

Request Body

• name (string, required) — display name
• code (string, required) — JSX source code
• buildType (string, required) — "in-app" or "external"
• description (string, optional)
• source (string, optional) — attribution or origin
• fieldSchema (array, optional) — typed field definitions
• nameField (string | null, optional) — field used as character name
• thumbnailUrl (string, optional)

Returns the created template object.

GET /api/custom-sheet-templates/{id}

Fetch a single template by ID.

curl https://polyhedral.co/api/custom-sheet-templates/TEMPLATE_ID \
  -H "Authorization: Bearer ph_..."

PATCH /api/custom-sheet-templates/{id}

Update one or more fields on an existing template. Only include the fields you want to change.

curl -X PATCH https://polyhedral.co/api/custom-sheet-templates/TEMPLATE_ID \
  -H "Authorization: Bearer ph_..." \
  -H "Content-Type: application/json" \
  -d '{ "code": "<Section title=\"Stats\">...</Section>" }'

DELETE /api/custom-sheet-templates/{id}

Delete a template and its thumbnail.

curl -X DELETE https://polyhedral.co/api/custom-sheet-templates/TEMPLATE_ID \
  -H "Authorization: Bearer ph_..."

Returns { "success": true }.

POST /api/custom-sheet-templates/validate

Validate JSX syntax without creating or updating a template. Useful for checking code before pushing it.

curl -X POST https://polyhedral.co/api/custom-sheet-templates/validate \
  -H "Authorization: Bearer ph_..." \
  -H "Content-Type: application/json" \
  -d '{ "code": "<Section title=\"Stats\"><Field name=\"hp\" type=\"number\" /></Section>" }'

Returns { "valid": true } on success, or { "valid": false, "error": "...", "line": 1, "column": 5 } on failure.

Example Workflows

Create a Template from a File

# Validate first
curl -X POST https://polyhedral.co/api/custom-sheet-templates/validate \
  -H "Authorization: Bearer ph_..." \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg code "$(cat my-sheet.jsx)" '{ code: $code }')"

# Create
curl -X POST https://polyhedral.co/api/custom-sheet-templates \
  -H "Authorization: Bearer ph_..." \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
    --arg name "My Custom Sheet" \
    --arg code "$(cat my-sheet.jsx)" \
    '{ name: $name, code: $code, buildType: "in-app" }'
  )"

Update Code from a Script

TEMPLATE_ID="your-template-id"

curl -X PATCH "https://polyhedral.co/api/custom-sheet-templates/$TEMPLATE_ID" \
  -H "Authorization: Bearer ph_..." \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg code "$(cat my-sheet.jsx)" '{ code: $code }')"

Preview a Template

After creating or updating a template, open it in the browser to preview:

https://polyhedral.co/home/sheets/preview/TEMPLATE_ID

Error Codes

• 400 — Missing required fields
• 401 — Missing or invalid API key
• 403 — Paid plan required
• 404 — Template not found
• 500 — Server error