nodeslate

REST API

API reference

Create, read and add to diagrams, and get repository files, over HTTPS with JSON.

Base URL https://nodeslate.io/api/public/v1. Send your API key as Authorization: Bearer ns_… and JSON bodies with Content-Type: application/json. Diagrams made by the API are drawn the first time they're opened.

Create a diagram

POST /diagrams

Body
source stringrequired
The diagram, up to 200,000 characters.
format string
lines, mermaid or sql. Default lines. See Diagram source.
type string
auto (default), flowchart, mind_map, architecture, entity_relationship, org_chart, journey or sequence. Set it whenever you know it: with lines, auto draws a flowchart.
title string
Its name. Guessed from the first line or the type when left out.
folder string
A folder's name or id where the key works.
curl https://nodeslate.io/api/public/v1/diagrams \
  -H "Authorization: Bearer $NODESLATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Sign up", "format": "mermaid", "source": "flowchart TD\n  A[Sign up] --> B{Email valid?}\n  B -->|Yes| C[Create account]\n  B -->|No| D[Show error]"}'
201 Created
{
  "id": "6f1c…",
  "title": "Sign up",
  "type": "auto",
  "url": "https://nodeslate.io/d/6f1c…",
  "updated_at": "2026-11-20T09:12:44+00:00",
  "place": "Acme → Platform"
}

List diagrams

GET /diagrams

Query
q string
Words to match in titles and box text.
limit integer
1 to 100, default 30.

Returns an array of {id, title, type, url, updated_at}, newest first.

Read a diagram

GET /diagrams/:id

200 OK
{
  "id": "6f1c…", "title": "Shop", "type": "flowchart", "url": "…", "updated_at": "…",
  "diagrams": ["Checkout", "Database"],
  "boxes": [
    { "id": "n1", "text": "Paid?", "kind": "decision", "diagram": "Checkout" },
    { "id": "t1", "text": "orders", "kind": "table", "diagram": "Database", "columns": ["id uuid pk", "total bigint"] }
  ],
  "connections": [{ "from": "Paid?", "to": "Order placed", "label": "Yes" }],
  "groups": [{ "name": "Payments", "boxes": ["Billing API", "Stripe"] }],
  "waiting_to_build": []
}

Add to a diagram

POST /diagrams/:id/additions

Body
source stringrequired
The diagram to add beside what's there.
format string
lines, mermaid or sql. Default lines. See Diagram source.
type string
auto (default), flowchart, mind_map, architecture, entity_relationship, org_chart, journey or sequence. Set it whenever you know it: with lines, auto draws a flowchart.
title string
Its name on the canvas, up to 80 characters.

Returns the diagram's summary. On a protected main, people who can't edit it get a change request instead, with change_request and change_request_url in the response.

Repository files

GET /diagrams/:id/mirror

Query
name string
The diagram's title in .nodeslate/config.json, for the file names. Defaults to its title.
200 OK
{
  "id": "6f1c…", "title": "Checkout flow", "revision": 45, …,
  "files": {
    ".nodeslate/checkout-flow.json": "{\n  \"document\": …",
    ".nodeslate/checkout-flow.md": "<!-- Generated by Nodeslate … -->\n# Checkout flow …"
  }
}

GET /diagrams/:id/file

Query
format string
json (default) or md.

Returns the file itself as text, with its revision in the X-Nodeslate-Revision header. See Diagrams in your repo.

Stuck, or missing something? Contact us.