Two Minute Toolkit TwoMinuteEcomap
Slide Deck Quality Ecomaps in 2 minutes or less

Ecomap HTTP API

POST a small JSON description and get back a deck-ready PNG (or SVG). The endpoint is open and CORS-enabled, so it works from browsers, scripts, CI and anywhere else you can make an HTTP call. The same JSON opens in the builder.

POST https://www.twominutetoolkit.com/api/render/ecomap
Fair use: rate-limited to 20 requests a minute per IP (bursts capped at 5 a second), shared across every Two Minute tool, with a 64 KB body cap. No key or sign-up needed.

Try it

Open in builder

Code samples


        

        

      

    


    

      

        
Live preview

        
Click Render to call the API.

      

      

        
Request body

        

            
FieldTypeDescription

            
titlestringHeading shown top-left of the chart at 22px bold. Every chart has one title row; an empty string hides it.
max 140 chars · default "Ecomap"

            
centerrequiredobjectThe client or household in the middle: a solid circle in the first palette colour with the name in bold white and the members listed under it, e.g. { "name": "Lopez household", "members": ["Maria, 34", "Leo, 9"] }. Use first names, roles or ages only.

            
systemsrequiredobject[]The systems around the centre (2–12), placed clockwise from 12 o'clock: people, groups and services such as School, Work, Extended family, Church, Health care, Friends, Probation, Benefits. One system still renders but is reported as a warning; more than 12 are dropped.
max 12 items

            
legendbooleanShow the legend under the map explaining the four line styles and the arrows. Default true; set false when the audience already knows the notation.
default true

            
widthintegerChart width in pixels (640–2400). Omit it (recommended) and the chart sizes itself to its content with comfortable margins, between 880 and 1280px wide. PNG output renders at 2x.
640–2400

            
palettestring[]Hex colours applied in order to items that have no colour of their own. Pass the user's brand colours here when they name them. Default: indigo, sky, emerald, amber, red, gray.
max 12 items · default ["#4f46e5","#0ea5e9","#10b981","#f59e0b","#ef4444","#6b7280"]

          

      

      

        
center

        

            
FieldTypeDescription

            
namerequiredstringName of the client or household, e.g. "Lopez household" or "Sam". Bold white text, wrapped to up to 2 lines.
max 40 chars

            
membersstring[]Optional household members listed small inside the centre circle, one per line (0–8), e.g. ["Maria, 34", "Leo, 9"]. A first name or role with an age reads best; the circle grows to fit.
max 8 items · default []

            
colorstringOptional hex colour of the centre circle. Default: the first palette colour (indigo #4f46e5); the systems take the following palette colours.
max 40 chars

          

      

      

        
systems[] item

        

            
FieldTypeDescription

            
namerequiredstringSystem label inside its circle, 1–3 words reads best (e.g. "Extended family"). Long names shrink and wrap to up to 3 lines.
max 40 chars

            
detailstringOptional short note shown outside the circle, on the side away from the centre, wrapped to up to 3 lines (about 10 words), e.g. "Weekly visits from grandma".
max 120 chars

            
strengthstringQuality of the relationship, drawn as the connecting line's style (Hartman's ecomap convention): "strong" (thick solid line), "moderate" (plain solid line, the default), "tenuous" (dashed line) or "stressful" (red line crossed by short hatch marks, -/-/-).
"strong", "moderate", "tenuous", "stressful" · default "moderate"

            
flowstringDirection of energy, support or resources along the line: "none" (default, no arrowheads), "to" (from the client to this system), "from" (from this system to the client) or "both" (a two-way exchange).
"none", "to", "from", "both" · default "none"

            
colorstringHex colour of this system's circle, e.g. "#10b981". Optional: systems without one take the next palette colour.
max 40 chars

          

      

      

        
Endpoints

        
    
          
  • POST /api/render/ecomap returns image/png; add ?format=svg for SVG.
    • 
          
  • GET /ecomap.png?d=<payload> and /ecomap.svg?d=<payload> render a chart from a link. The payload is the JSON body, raw-deflated and base64url-encoded. Nothing is stored: links are permanent and cached for a year.
    • 
          
  • /ecomap#d=<payload> opens the same chart in the builder for editing.
    • 
          
  • GET /api/render/ecomap?demo=1 returns the demo chart.
    • 
          
  • GET /api/schema/ecomap returns the JSON Schema, for code generators and AIs.
    • 
        

      

      

        
Errors and adjustments

        
Input is lenient where the intent is clear: numeric strings become numbers, out-of-range values are clamped, and unknown fields are ignored. Adjustments are listed in the X-Render-Warnings header. Anything unclear returns a 400 that says how to fix it:

        
{
  "error": "Invalid payload",
  "issues": [{ "path": "tasks", "message": "must be an array" }],
  "example": { … }
}

      

      

        
Calling from an AI assistant?

        
Use the hosted MCP server instead. It gives Claude, Cursor and other MCP clients a create_ecomap tool that returns the image plus image, SVG and edit links. See the MCP page →