Scrwly API

Send API keys as Authorization: Bearer $SCRWLY_API_KEY. X-Scrwly-Key is also accepted. Missing, invalid, revoked, or disabled keys return 401 before any model/provider call.

Keys are stored as SHA-256 hashes with a visible prefix only. Admin key creation, rotation, revocation, and disable actions are available under /api/v1/admin/api-keys when SCRWLY_ADMIN_TOKEN is configured.

Use /api/v1/openapi.json for the OpenAPI 3.1 contract, /api/v1/schema/0.1 or /api/v1/schema/latest for the scene JSON Schema, and /api/v1/capabilities for supported providers, themes, node types, components, export formats, and current platform limits.

Converts a natural language prompt into a validated visual scene and returns both the structured scene JSON and rendered SVG. The explicit route /api/v1/generate is equivalent.

Request Body

{
  "prompt": "Create a simple diagram explaining photosynthesis",
  "theme": "clean-light",
  "primaryColor": "#111111",
  "provider": "mock",
  "audience": "middle school science students"
}

{
  "prompt": "Create a simple clock diagram",
  "theme": "clean-light",
  "primaryColor": "#e11d48",
  "provider": "mock"
}

{
  "id": "scene_abc123",
  "sceneId": "scene_abc123",
  "sceneVersion": "0.1",
  "scene": {
    "version": "0.1",
    "schemaVersion": "0.1",
    "id": "photosynthesis-cycle",
    "title": "Photosynthesis",
    "canvas": { "width": 900, "height": 600, "background": "background", "padding": 40 },
    "theme": { "id": "clean-light" },
    "nodes": []
  },
  "svg": "<svg ...></svg>",
  "validation": { "valid": true, "errors": [], "warnings": [] },
  "qa": { "passed": true, "score": 0.96, "issues": [] },
  "provider": "mock",
  "themeOverrides": {
    "primaryColor": "#111111"
  },
  "warnings": [],
  "metadata": {
    "provider": "mock",
    "latencyMs": 42,
    "retryCount": 0,
    "requestId": "req_abc123"
  }
}

curl -X POST https://scrwly.com/api/v1 \
  -H "Authorization: Bearer $SCRWLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{   "prompt": "Create a simple diagram explaining photosynthesis",   "theme": "clean-light",   "primaryColor": "#111111",   "provider": "mock",   "audience": "middle school science students" }'

Validates a supplied scene and renders it to SVG. Invalid scenes return HTTP 422 with structured validation errors. Include primaryColor to override the rendered SVG primary theme color.

{
  "primaryColor": "#111111",
  "scene": {
    "version": "0.1",
    "id": "simple-label",
    "title": "Simple Label",
    "canvas": { "width": 900, "height": 600, "background": "background", "padding": 40 },
    "theme": { "id": "clean-light" },
    "nodes": [
      {
        "id": "title",
        "type": "text",
        "text": "Simple Label",
        "x": 450,
        "y": 80,
        "align": "center",
        "fontSize": 28
      }
    ]
  }
}

{
  "valid": true,
  "svg": "<svg ...></svg>",
  "validation": { "valid": true, "errors": [], "warnings": [] },
  "themeOverrides": {
    "primaryColor": "#111111"
  },
  "metadata": {
    "requestId": "req_abc123",
    "latencyMs": 12
  }
}

Successful generations return a persistent sceneId. Use GET /api/v1/scenes to list recent scenes, GET /api/v1/scenes/:id to retrieve scene JSON and SVG, and DELETE /api/v1/scenes/:id to delete a scene. Scene access is isolated by authenticated owner.

{
  "id": "scene_abc123",
  "prompt": "Create a simple diagram explaining photosynthesis",
  "sceneVersion": "0.1",
  "scene": {},
  "svg": "<svg ...></svg>",
  "status": "generated",
  "provider": "mock"
}

{
  "id": "job_abc123",
  "status": "queued",
  "pollUrl": "/api/v1/jobs/job_abc123"
}

Use jobs for slower generation flows. POST /api/v1/jobs returns 202 with a job id and polling URL. GET /api/v1/jobs/:id returns queued, running, succeeded, failed, or cancelled. Synchronous /generate remains available for fast requests.

Limits run before model calls. The initial plans enforce requests per minute, daily generation quota, monthly generation quota, maximum prompt length, maximum scene complexity, and allowed providers.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Request rate limit exceeded for this API key.",
    "requestId": "req_abc123",
    "details": {
      "limit": "requestsPerMinute",
      "retryAfterSeconds": 42
    }
  }
}

Checks scene JSON against the current schema without rendering it. This is useful before saving generated scenes or submitting edited JSON from an external UI.

{
  "scene": {
    "version": "0.1",
    "id": "simple-label",
    "title": "Simple Label",
    "canvas": { "width": 900, "height": 600, "background": "background", "padding": 40 },
    "theme": { "id": "clean-light" },
    "nodes": [
      {
        "id": "title",
        "type": "text",
        "text": "Simple Label",
        "x": 450,
        "y": 80,
        "align": "center",
        "fontSize": 28
      }
    ]
  }
}

{
  "valid": false,
  "errors": [
    {
      "path": "canvas.width",
      "code": "invalid_type",
      "message": "Required",
      "severity": "error"
    }
  ],
  "warnings": [],
  "metadata": { "requestId": "req_abc123" }
}