CardStudio Documentation

Complete developer guide, template format specification, and REST API documentation.

Card Template Schema (Version 1.0.0)

Every card in CardStudio is represented by a single standard JSON document complying with the CardStudio Template Schema.

{
  "$schema": "https://cardstudio.example/schema/card-template.v1.json",
  "format": "cardstudio.template",
  "version": "1.0.0",
  "id": "uuid-here",
  "meta": {
    "name": "Corporate ID Badge",
    "type": "id-badge"
  },
  "page": {
    "unit": "mm",
    "dpi": 300,
    "bleed": 3,
    "safeMargin": 4,
    "sides": ["front", "back"],
    "orientationDefault": "horizontal"
  },
  "layouts": {
    "horizontal": { "width": 85.6, "height": 54, "background": { "color": "#FFFFFF" } },
    "vertical": { "width": 54, "height": 85.6, "background": { "color": "#FFFFFF" } }
  },
  "sides": {
    "front": { "elements": [] },
    "back": { "elements": [] }
  }
}

REST API Endpoints

All API endpoints are prefixed with /api/v1 and return uniform JSON responses.

  • GET /api/v1/templates — List public approved templates
  • GET /api/v1/templates/{id} — Retrieve template details and schema
  • POST /api/v1/templates/validate — Dry-run JSON validation
  • POST /api/v1/cards — Create card from template
  • POST /api/v1/assets — Upload raster image or SVG asset