Skip to content

Diagram Generation

Prompt briefs, design selection modes, options, and refinement.

Updated View as Markdown

Generate vector SVG diagrams using the POST /rest/v1/generations endpoint.


Endpoint Details

  • Method: POST
  • Path: /rest/v1/generations
  • Base URL: https://svgdiagram.ai

Request Body Parameters

{
  "prompt": "Sequence diagram of OAuth2 Authorization Code flow with PKCE",
  "design": "auto",
  "appearance": "light",
  "fontId": "inter",
  "colors": {
    "source": "automatic"
  },
  "options": {}
}
Field Type Description
prompt string Required. Natural language brief describing the diagram content, structure, steps, or components.
design string Optional. Selection mode or specific design ID: "auto" (default), "creative", or a published design ID (e.g. timeline-zigzag-icon-cards).
appearance string Optional. Neutral appearance mode: "light" or "dark".
fontId string Optional. Bundled font: "inter", "source-sans-3", "archivo", or "barlow-condensed".
colors object Optional. Selects automatic, brand, saved-palette, or custom-palette colors. Each source accepts a different object shape; see examples below.
options object Optional. Key-value option overrides for specific published designs.
callbackUrl string Optional. Generates asynchronously and POSTs the result to this URL. Must be HTTPS on an allowed automation host (currently hooks.zapier.com). See Asynchronous generation.

Valid colors examples:

{ "source": "automatic" }
{ "source": "custom", "palette": ["#6366f1", "#10b981"] }
{ "source": "brand", "name": "Product", "palette": ["#6366f1", "#10b981"], "fontId": "inter" }
{ "source": "palette", "paletteId": "<palette-uuid>" }
{ "source": "saved", "palette": ["#6366f1", "#10b981"], "name": "Product" }

brand accepts optional name, palette, and fontId; saved accepts optional name. custom and saved require a palette of 1–8 #rgb or #rrggbb values.


Design Selection Modes

svgdiagram.ai supports two distinct generation paths:

  1. Automatic (design: "auto"): The model evaluates published stable designs in the catalog. If a published design fits the request, it populates its structural parameters. If no published design fits, it seamlessly routes to the creative sandbox.
  2. Creative Sandbox (design: "creative"): The model generates custom, free-form vector JSX rendered in an isolated sandbox environment.
  3. Named Design ID (design: "<id>"): Explicitly names a published design (for example, timeline-zigzag-icon-cards). Use an ID returned by GET /rest/v1/designs.

Query available published catalog designs using GET /rest/v1/designs.


Asynchronous generation

Most diagrams finish in under 10 seconds, but some take over a minute. Automation platforms that stop waiting after about 30 seconds can pass callbackUrl instead of holding the request open.

  • The request is validated and funded first. Validation, plan, and credit errors still answer the request itself with their usual status codes.
  • Once the generation is admitted, the API answers 202 Accepted:
{ "status": "accepted", "item": { "id": "e8b21c40-3a52-4f81-8b09-1a052e690f12", "status": "pending" } }
  • When the generation finishes, the API POSTs the same body a synchronous request returns to callbackUrl:
{ "status": "ok", "item": { "id": "e8b21c40-...", "status": "completed", "svg": "<svg ...>", "...": "..." } }
  • When it fails, the credit is refunded and the API POSTs the error:
{ "status": "error", "error": "Generation timed out", "code": "generation_timeout", "generationId": "e8b21c40-..." }
  • A delivery that does not get a 2xx answer is retried with growing delays, up to 8 attempts.
  • Callback URLs must use HTTPS on an allowed host. hooks.zapier.com is allowed today; other hosts are rejected with 400.

Diagram Refinement & Iteration

Refine a completed creative diagram by passing its ID in from and a refine instruction:

{
  "from": "e8b21c40-3a52-4f81-8b09-1a052e690f12",
  "refine": {
    "instruction": "Add a Redis caching layer between the API gateway and microservices"
  }
}

Alternatively, adjust detail density relatively:

{
  "from": "e8b21c40-3a52-4f81-8b09-1a052e690f12",
  "refine": {
    "detail": "more"
  }
}
  • Refinements cost 1 credit.
  • Retries and refinements preserve parent context and produce child attempts linked by rootId.
Navigation

Type to search…

↑↓ navigate↵ selectEsc close