The REST API

The flowss REST API lets a script, a CI job, a docs build or your own back end do what the studios do, without a browser. Ten endpoints live under /api/v1/: one generates a diagram from a sentence with AI, and the other nine are deterministic tools that parse, compare, convert, critique and verify diagram source, assemble evidence graphs, and run the Science studio's checkers. Every endpoint authenticates with an account API key that starts with glyp_, answers in JSON, and describes itself when you send it a plain GET. This page is the complete reference: how to get and use a key, the daily allowances and AI points each call spends, every endpoint's request and response, every error you can receive and what to do about it, and ready-to-use recipes.

At a glance

Which plans can use it

Every signed-in account can create API keys. What a key can do depends on the plan of the account that owns it.

Free includes no AI at all: no hosted points and no own-key use. Starter includes no hosted AI points, but you may send your own provider key with each request (see Using your own AI key). Plus, Ultra and Enterprise spend the account's monthly AI points, and may also bring their own key. Plan prices and the full comparison are on Plans and what they include and the pricing page.

Getting an API key

API keys belong to your account, not to a project or a team. All of an account's keys share that account's allowances, so creating more keys does not create more allowance.

1. Sign in and open your account page at /account.
2. Scroll down to the API keys card. On a wide screen it sits to the right of the Bring-your-own key card; on a narrow one, below it.
3. Type a name in the field whose placeholder reads Key name (e.g. CI pipeline). The name is for you; anything past 80 characters is cut off. If you leave it empty the key is called Untitled.
4. Click Create key.
5. A highlighted box appears: New key — copy now, won't show again. Click Copy (you see "Copied to clipboard") and store the key somewhere safe, such as your CI system's secret store or a password manager.
6. Click Dismiss to hide the box.

Warning: The full key is shown exactly once. flowss stores only a one-way fingerprint of it, so nobody, including support, can show it to you again. If you lose it, create a new key and revoke the old one.

What the key list shows

Each key appears as a row under the create field, newest first:

If you have no keys yet, the list reads No API keys yet. Create one to call /api/render and the /api/v1 endpoints from CI — the render API needs a key. The same keys work for every /api/v1/ endpoint, the headless render API and the flowss MCP server. There is no limit on how many keys you can create.

Revoking a key

1. Click Revoke on the key's row.
2. Confirm the prompt: Revoke this key? Existing integrations using it will stop working immediately.
3. The row disappears and you see Key revoked.

Revocation takes effect on the next request: a revoked key is refused with HTTP 401 from that moment. Keys do not expire on their own; revoke a key when you no longer need it or when it may have been exposed.

Note: At the moment a revoked key can reappear in the list the next time you load your account page, still showing a Revoke button. It stays revoked and every request made with it is refused. Clicking Revoke on it again shows Key not found or already revoked.

Authentication

Send your key on every POST. Any of these forms is accepted by the /api/v1/ endpoints:

Authorization: Bearer glyp_YOUR_KEY
Authorization: glyp_YOUR_KEY
X-Api-Key: glyp_YOUR_KEY

The word Bearer is optional and is not case-sensitive. When a request carries both an Authorization header and X-Api-Key, only Authorization is read, so do not let a proxy add its own Authorization header in front of your key. A value that does not start with glyp_, a key that was revoked, or a key that does not exist are all answered the same way:

{ "error": "Invalid or missing API key. Send 'Authorization: Bearer glyp_<key>'." }

with HTTP status 401.

Note: The headless render API (POST /api/render) reads the key from either header too, and needs one (or a signed-in session): without a key it answers 401 sign-in-required, and a key it does not recognise gets 401 bad-api-key. On the Free plan it refuses the Lab's engine (glyphscript) with 402 engine-plan. See Embedding and the render API.

Keep the key on the server

A key spends your account's allowances and, on the AI endpoint, your AI points. Treat it like a password:

• Store it in your CI system's secrets (for example a repository secret), never in source control.
• Call the API from a server, a script or a CI job. The API sends no cross-origin (CORS) headers, so a web page on another site cannot call it from the browser, and you should never ship a key inside front-end code anyway.
• Use one key per integration, named after it, so you can revoke one without breaking the others and so last used tells you which integrations are alive.

Self-describing endpoints

Every endpoint answers a plain GET with its own documentation as JSON: a description, the body it accepts, options, limits and an example. No key is needed and nothing is counted.

curl -sS https://www.flowss.ai/api/v1/diff | jq .

GET /api/v1/science also lists every operation and every calculation method its results may cite; GET /api/v1/critique and GET /api/v1/verify include a ready-made GitHub Actions workflow in their action field.

Conventions

Requests and responses

• Send Content-Type: application/json and a JSON object as the body. Malformed JSON, or a body that is null, a number or a string, is refused with HTTP 400 and "Invalid JSON body" (or "Invalid JSON body." on critique and verify). A top-level array is refused the same way by convert; elsewhere it fails the endpoint's own field checks instead (for example Missing 'prompt').
• Every response is JSON. An error response always carries a human-readable error, and usually a machine-readable code.
• Engine ids are the short ids listed on the engine reference, for example mermaid, d2, graphviz, plantuml, dbml, sql. The Weave canvas's id is lucidflow.

Pass or fail endpoints

critique and verify exist to gate pull requests. They always answer HTTP 200 with pass: true or pass: false when the request was valid, so your pipeline can tell "the diagram did not meet the bar" (a 200 with pass: false) apart from "the request itself failed" (any 4xx or 5xx).

The science ok field

science answers every operation with an ok field. ok: false with HTTP 200 means the request was well formed and the answer is "no" or "declined": a figure with a failing claim, an unbalanceable equation, or a model operation that refused (with a named refusal). HTTP 400 with ok: false and an error means an argument was missing or could not be read, for example a unit the converter does not know, a formula it cannot parse, an unknown journal or guideline id, or an impossible randomisation. One operation answers 404: hazards for a chemical that is not in its reference table.

Findings

critique, verify and analyze return a findings array in one shared shape, the same objects the Studio underlines in its editor and the flowss Studio Agent reports at the end of a run:

Allowances, rate limits and AI points

The daily allowances

The deterministic allowance is the same on every plan: upgrading does not raise it. What a key gives you is an allowance of your own, counted per account, instead of one shared with everybody behind the same internet address.

The deterministic allowance is one counter per account, and several things draw on it:

• every call to the seven deterministic /api/v1/ endpoints above;
• every call to the headless render API (POST /api/render) made with your key;
• in the app, each drift Check on a living diagram, and some Evidence actions (rendering, exporting, causal analysis and building a review from a diagram).

detect and convert do not spend the deterministic allowance. When they need AI they spend AI points instead (see below).

Allowances reset at midnight UTC.

When a call is counted

• diagram and critique validate your request first, so a malformed request is refused without spending anything.
• generate, diff, verify, synthesize, analyze and science count any request that carries a valid key, before reading the body. A request refused for a missing field or a malformed body has still been counted. Validate locally before you loop over many files.
• generate and diff accept up to 100 files in one request, and a batch counts once. Batch whenever you can.
• On diagram, the daily request ceiling is counted before the AI points check, so a request later refused for lack of points has still used one of the day's requests.

What an AI call costs

A request that fails before or during the AI provider call costs no points. On diagram and detect, the point is spent once the provider answers, even if its answer turns out to be unusable; convert charges only for a conversion it actually delivers. Monthly points and top-up packs are explained on AI points and limits.

Using your own AI key

On Starter and up you can pay your AI provider directly instead of spending points. Send your provider key in a second header:

X-User-Api-Key: sk-ant-…
X-User-Ai-Provider: anthropic

If you leave out X-User-Ai-Provider, flowss guesses the provider from the key's shape (Anthropic, Google, Zhipu GLM, OpenAI and Mistral keys are recognisable; a key that matches none is sent to Anthropic). DeepSeek, Qwen and Moonshot keys look like OpenAI keys, so always send the provider header with those. A key whose shape matches no supported provider is refused with bad-key-shape before anything is sent.

Note: A key saved to your account on the Bring-your-own key card of your account page is used by the web app, where you are signed in. API calls carry no sign-in, so a saved key is not used by them: send X-User-Api-Key on every request that should run on your own key. More on Bring your own AI key.

Calls on your own key spend no points but are not unlimited: every own-key AI request on the platform counts toward a ceiling of 1,000 a day per account.

Rate-limit responses

The number in a 429 message is your actual cap for that allowance, so on Plus the diagram message reads (200/day). A code of ip-cap on critique or verify means the call was counted against your internet address instead of your account, which happens only when account counting is briefly unavailable.

Endpoint reference

POST /api/v1/diagram

Generates a complete diagram from a natural-language prompt using AI, and returns its source plus a ready-to-embed link.

Request body:

curl -sS https://www.flowss.ai/api/v1/diagram \
  -H "Authorization: Bearer $FLOWSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A C4 container diagram for a food-delivery app","engine":"d2"}'

Response (200):

{
  "engine": "d2",
  "title": "Food delivery — containers",
  "code": "…complete d2 source…",
  "embed_url": "https://www.flowss.ai/embed?engine=d2&code=…&theme=dark",
  "links": {
    "embed": "https://www.flowss.ai/embed?engine=d2&code=…&theme=dark",
    "render": "https://www.flowss.ai/api/render"
  }
}

Errors specific to this endpoint:

POST /api/v1/generate

Turns a structural source (a schema, a spec, a graph) into a stable Mermaid overview. No AI and no network, so the same input always produces byte-identical output: ideal for regenerating a committed diagram in CI on every push.

Engines it can read: mermaid (flowcharts only), d2, graphviz, dbml, structurizr, sql, erd, openapi, and Weave boards (lucidflow, the board's JSON). The endpoint's own GET lists the first eight; Weave boards are read too. A SQL or DBML schema with columns becomes a Mermaid erDiagram with column types and PK/FK markers (direction does not apply); everything else becomes a Mermaid flowchart whose nodes are numbered n0, n1, … in sorted order, so the output never changes unless the source does.

Single request body:

curl -sS https://www.flowss.ai/api/v1/generate \
  -H "Authorization: Bearer $FLOWSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"engine":"sql","code":"CREATE TABLE users (id INT PRIMARY KEY, email TEXT);"}'

Response (200):

{
  "engine": "sql",
  "ok": true,
  "mermaid": "erDiagram\n  users {\n    INT id PK\n    TEXT email\n  }\n",
  "nodes": 1,
  "edges": 0
}

A flowchart example: {"engine":"d2","code":"web -> api\napi -> db","direction":"TD","title":"Overview"} returns a mermaid value of %% Overview, then flowchart TD, then one line per node and per edge.

If the source cannot be parsed, the answer is HTTP 422 with ok: false:

{ "engine": "sql", "parseable_engine": true, "ok": false, "error": "Could not parse this source structurally." }

For an engine with no structural reader, parseable_engine is false and error reads Engine 'pikchr' has no structural parser. (with your engine's id). A Mermaid source that is not a flowchart (a sequence or class diagram, for example) cannot be parsed structurally either.

Batch mode

Send { "files": [ … ] } instead, with up to 100 entries of { path?, engine, code, direction?, title? }. The whole batch counts as one call. In a batch only the 4 MB total is enforced; there is no separate per-file limit.

{
  "files": [
    { "path": "db/schema.sql", "engine": "sql", "code": "CREATE TABLE …" },
    { "path": "infra/arch.d2", "engine": "d2", "code": "web -> api", "direction": "TD" }
  ]
}

Response (200): { "results": [ { "path": "db/schema.sql", "engine": "sql", "ok": true, "mermaid": "…", "nodes": 2, "edges": 1 }, … ], "total": 2, "generated": 2 }. Each result has the same shape as a single response, plus the path you sent. A file that fails to parse is a result with ok: false; it does not fail the batch.

POST /api/v1/diff

Compares two versions of a diagram by meaning, not by text: which nodes and edges were added, removed, renamed or relabelled, and for schemas which columns changed. Formatting and whitespace changes are ignored. Built for pull-request comments and merge gates.

Structural comparison covers mermaid (flowcharts), d2, graphviz, dbml, structurizr, sql, erd, openapi and Weave boards (lucidflow). Any other engine, a side that does not parse, an empty side, or a pair whose two engines differ falls back to a plain text comparison that ignores only leading and trailing whitespace: you learn whether it changed, but not what.

Single request body:

curl -sS https://www.flowss.ai/api/v1/diff \
  -H "Authorization: Bearer $FLOWSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"engine":"d2","before":"a -> b","after":"a -> b\nb -> c"}'

Response (200):

{
  "engine": "d2",
  "structured": true,
  "parseable_engine": true,
  "changed": true,
  "textChanged": true,
  "summary": "Added 1 node (c); added 1 edge (b→c).",
  "diff": {
    "addedNodes": [{ "id": "c" }],
    "removedNodes": [],
    "renamedNodes": [],
    "addedEdges": [{ "from": "b", "to": "c" }],
    "removedEdges": [],
    "relabeledEdges": [],
    "changedAttributes": [],
    "changed": true
  }
}

For a schema the summary reads like a column changelog. Changing users (id INT PRIMARY KEY, age INT) to users (id BIGINT PRIMARY KEY, phone TEXT) summarises as Columns users: +phone, −age, ~id. Long lists in a summary are shortened with +N more (after four nodes or edges, six columns of a table, or three tables); the full lists are always in diff.

With format: "markdown", a single comparison adds a markdown heading (Diagram changed or No structural change) followed by the summary; a batch adds a heading such as 2 of 5 diagrams changed and a table with one row per file (file, engine, change).

Batch mode

Send { "files": [ { path?, engine, before, after, afterEngine? }, … ] } with up to 100 entries. The response is { "results": [ … ], "changed": <number of files that changed>, "total": <number of files> }, each result carrying the path you sent. Add "format": "markdown" to get one markdown table summarising every file, ready to post as a pull-request comment.

POST /api/v1/convert

Converts a diagram from one engine to another. Where flowss has a built-in converter for the pair, the result is instant, free and deterministic; otherwise AI rewrites the diagram.

Built-in converters:

A built-in converter only runs on a source it can read: a Mermaid sequence diagram, for example, is not a flowchart, so converting it goes to AI.

Request body:

curl -sS https://www.flowss.ai/api/v1/convert \
  -H "Authorization: Bearer $FLOWSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sourceEngine":"mermaid","targetEngine":"d2","code":"graph LR\n  A[API] --> B[(DB)]"}'

Response (200):

{
  "engine": "d2",
  "code": "direction: right\n\nA: \"API\"\nB: \"DB\" { shape: cylinder }\n\nA -> B",
  "notes": "Converted with the built-in mermaid → d2 transpiler (lossless: every node, connection and label carried over).",
  "method": "transpiler"
}

When the built-in converter would lose structure (a node, a connection, a label), flowss tries AI first, since AI is asked to keep everything. If AI is not available to you (no points, Free plan, a refused or malformed own key, a daily limit, a provider failure), you get the lossy built-in result instead of an error, with method: "transpiler-lossy". When the built-in converter loses only styling, its result is returned straight away as transpiler-lossy without trying AI; notes names what was dropped and suggests converting with AI instead only when structure was lost.

The errors below therefore reach you only when there is no built-in result to fall back on:

POST /api/v1/detect

Identifies which engine a snippet of diagram source is written for.

Request body: { "code": "…" }.

curl -sS https://www.flowss.ai/api/v1/detect \
  -H "Authorization: Bearer $FLOWSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"graph LR\n  A --> B"}'

Response (200):

{ "engine": "mermaid", "confidence": "high", "source": "heuristic" }

detect is designed never to block you. If AI would be needed but is not available (no points, the daily limit reached, a provider failure, or an unusable AI answer), it returns its best low-confidence guess, source: "heuristic" and confidence: "low", falling back to mermaid if it has no guess at all. Treat any low answer as a suggestion to confirm.

It returns an error only in these cases: Invalid JSON body (400), Missing 'code' field (400), Code is too long (>100 KB) (400, more than 100,000 characters), and problems with your own AI key that only you can fix: byok-upgrade-required (402, a Free account sent X-User-Api-Key), bad-key-shape (400), bad-key (401, the provider rejected your key) and plan-unavailable (503, your plan could not be read for a moment while you sent your own key; retry). Reaching the daily own-key limit does not produce an error here: you get the low-confidence guess.

POST /api/v1/critique

The full quality read the Studio shows in its status bar, as an API: is the diagram broken, and how good is it across seven dimensions, with the concrete edit that would improve each. No AI, nothing stored, nothing fetched, so the answer is reproducible and costs only one deterministic call.

Request body:

The readiness levels, lowest to highest:

The seven dimensions: fidelity (is this what was asked for?), completeness (the whole thing, or a sketch?), structure (is the shape sound?), legibility (can a reader take it in?), rigour (do the numbers carry their weight?), accessibility (can everyone read it? every colour pair is simulated under three kinds of colour-vision deficiency and in greyscale) and portability (will it survive leaving flowss?).

curl -sS https://www.flowss.ai/api/v1/critique \
  -H "Authorization: Bearer $FLOWSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"engine":"mermaid","code":"flowchart TD\n  A[Records identified] --> B[Screened]","request":"PRISMA flow: 1,284 records identified","gate":"sound"}'

Response (200), shortened:

{
  "pass": true,
  "gate": "sound",
  "findings": [
    { "id": "m626ai", "source": "critique", "level": "warning", "code": "critique/fidelity",
      "message": "The request reads as PRISMA 2020 flow, and this is drawn in Mermaid.",
      "detail": ["Either re-express it in PRISMA 2020 flow, or say in the caption why Mermaid is the better notation here."] }
  ],
  "readiness": {
    "level": "sound",
    "label": "Sound",
    "score": 0.6913,
    "reason": "Every mechanical check passes (1 advisory). Quality read: 77% …",
    "blocking": [
      "Only 2 nodes — this is a stub rather than a model.",
      "The request names a figure the diagram never states: 1284."
    ],
    "toAdvance": "Take a quality read and act on the top findings — sound is not the same as good."
  },
  "verification": { "ok": true, "summary": "Not fully checked — mermaid was not rendered", "defects": [ … ] },
  "critique": {
    "score": 0.7652,
    "band": "solid",
    "summary": "77% across 6 dimensions; weakest is fidelity. 1 dimension could not be judged and is left out of the score.",
    "unassessed": ["accessibility"],
    "dimensions": [
      { "id": "fidelity", "title": "Fidelity", "question": "…", "assessed": true, "score": 0.4, "findings": [ { "message": "…", "fix": "…" } ] }
    ],
    "moves": [
      { "label": "Add the entities the subject actually has; a real system usually has 8 or more.", "why": "Only 2 nodes — this is a stub rather than a model.", "dimension": "completeness" }
    ]
  },
  "next": [
    { "capabilityId": "critique-work", "title": "Critique it", "phase": "critique", "why": "…" }
  ]
}

Nothing in critique can fail pass on its own at the default gate: only broken mechanics drop a diagram below sound. Raise gate to reviewed or publishable to hold diagrams to the quality read too. A gate value that is not one of the four levels is treated as sound.

Where an engine has a checker of its own (for example a dependency loop that makes a schedule impossible, or two rules of a decision table that can both fire), its verdict is folded into the read as well.

Note: Some engines are drawn by your browser and cannot be drawn on the server. For those, verification.summary says the diagram was not fully checked, and a warning finding explains which checks did run. The diagram is not treated as broken.

POST /api/v1/verify

An architecture test for CI: checks that a diagram still matches the thing it describes. You send the diagram (inline, or a reference to a figure stored in one of your cloud projects) and the source of truth (a compose file, a SQL schema, an OpenAPI spec or another diagram), and get a deterministic pass or fail.

The body takes one of two shapes.

Stateless, everything inline:

{
  "diagram": { "engine": "mermaid", "code": "flowchart LR\n  api --> db\n  api --> cache[Redis]" },
  "truth": {
    "kind": "compose",
    "content": "services:\n  api:\n    depends_on: [db, worker]\n  db:\n    image: postgres:16\n  worker:\n    image: acme/worker"
  }
}

A stored figure, with optional inline truth:

{ "projectId": "<project id>", "figureId": "<figure id>", "truth": { "kind": "sql", "content": "CREATE TABLE …" } }

If you send diagram and projectId/figureId together, the inline diagram is used.

With a stored figure and no truth, flowss re-fetches the figure's own bound source on the server: the source you attached on the Live dashboard (see Integrations and extensions). The Live dashboard's CI button produces exactly this request with your ids filled in.

Response (200) to the inline example above, where the diagram is missing the worker service and still shows a Redis cache the compose file no longer has:

{
  "pass": false,
  "summary": "Drift — missing from diagram: worker; no longer in source: Redis.",
  "coverage": 0.667,
  "truth": "inline compose",
  "drift": {
    "missingFromDiagram": ["worker"],
    "staleInDiagram": ["Redis"],
    "missingEdges": [],
    "staleEdges": []
  },
  "findings": [
    { "id": "…", "source": "drift", "level": "error", "code": "drift/missing-entity",
      "message": "\"worker\" is in the source of truth but not in the diagram.",
      "where": { "subject": "worker" }, "detail": ["Compared against inline compose."] }
  ]
}

How entities are matched: by name, not by internal id. Each node's label (or its id, if it has no label) is lower-cased, parenthetical notes are removed, everything that is not a letter or a digit (spaces included) is dropped, and the affixes service, svc, server and the are removed from the start or end of the name (never from a name only a few characters longer than the affix). So API service matches a compose service called api, and DB matches db. A node labelled Postgres does not match a service called db: name your diagram's nodes after the things in the source.

How relations are matched: a relation is compared only when both of its ends matched, because an edge to a missing entity is already reported as that entity. A relation drawn in the opposite direction from the truth is not reported as stale, but a relation in the truth still counts as missing unless the diagram draws it in the same direction.

Note: Because extra relations do not fail pass, a passing response can still carry drift/stale-edge findings. If your gate must reject those too, also fail the job when drift.staleEdges is not empty.

POST /api/v1/synthesize

The Evidence studio's graph engine, without AI. You bring the claims (each a subject, a relation, an object and ideally a supporting quote); flowss assembles the concept graph, finds contradictions and gaps, rates certainty, checks quotes against source text if you supply it, and renders a view.

Request body:

Relations: increases, decreases, causes, prevents, treats, correlates, associated, no_effect, moderates, supports, contradicts, part_of. A claim may also carry arm-level data, data: { kind: "binary", events, total, controlEvents, controlTotal } (or continuous or rate), so its effect is computed rather than read from text. GET /api/v1/synthesize lists the exact domain keys each risk-of-bias tool accepts.

curl -sS https://www.flowss.ai/api/v1/synthesize \
  -H "Authorization: Bearer $FLOWSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"claims":[
    {"sourceId":"s1","subject":"sleep deprivation","relation":"decreases","object":"working memory","quote":"sleep deprivation decreases working memory"},
    {"sourceId":"s2","subject":"sleep deprivation","relation":"no effect","object":"working memory","quote":"no significant effect on working memory"}]}'

Response (200), shortened:

{
  "graph": { "concepts": [ … ], "edges": [ … ] },
  "claims": [ … ],
  "stats": { "concepts": 2, "edges": 2, "claims": 2, "sources": 0, "contradictions": 1 },
  "summary": "2 concepts, 2 links, 2 claims, 0 sources; 1 contradiction.",
  "contradictions": [ … ],
  "contradictionSummary": "1 contradiction: sleep deprivation→working memory (decreases vs no effect on).",
  "gaps": [ … ],
  "certainty": { "high": 0, "moderate": 0, "low": 0, "very_low": 2, "total": 2 },
  "riskOfBias": { "tools": [], "appraised": 0, "total": 2, "unmatched": [] },
  "view": { "name": "concept-map", "engine": "mermaid", "code": "…" },
  "warnings": []
}

A claim without an id is numbered claim-0, claim-1, … by its position; a claim without a sourceId is grouped with every other unattributed claim under one source, source-unattributed, so unattributed claims never count as independent studies. A claim with no subject or object, or with a relation flowss does not recognise, is dropped and named in warnings (for example claims[3] (…→…): unrecognized relation "…"). warnings also reports retracted sources, records still awaiting a screening decision, several sources that report one study (linked by a shared DOI or trial registration and counted once), and a claim whose quoted effect disagrees with its own arm-level counts.

grounding ({ total, verified, rejected: [{ id, reason }] }) is added when you send sourceText. riskOfBias.appraised: 0 is the honest reading of a synthesis nobody appraised: certainty ratings then state that the study-limitations domain was not assessed. riskOfBias.unmatched names appraisals whose sourceId matches no source. The view.code is diagram source you can render with the render API or open in the Studio.

POST /api/v1/analyze

Everything synthesize returns, plus the Evidence studio's full analytical layer: the evidence base by study design, leave-one-out robustness, trends over time, a GRADE Summary of Findings and a prioritised research agenda. No AI.

Request body: claims (required; each { subject, relation, object, quote?, method?, n?, effect? }), sources (optional; include year for trends over time), sourceText and requireGrounding (as for synthesize). Add method, n and effect to claims for GRADE certainty and effect synthesis.

The response carries every synthesize field plus:

The errors are the same as for synthesize.

POST /api/v1/science

Every checker and calculator the Science studio runs, one operation per request, chosen by the op field. No AI, no network and nothing stored: the same body always gives the same answer, so you can cache results indefinitely.

Every response includes ok. Send { "op": "…", …arguments }; the op is matched without regard to case or surrounding spaces.

curl -sS https://www.flowss.ai/api/v1/science \
  -H "Authorization: Bearer $FLOWSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"op":"balance","equation":"CH4 + O2 -> CO2 + H2O"}'

{
  "ok": true,
  "outcome": "balanced",
  "coefficients": [1, 2, 1, 2],
  "equation": "CH4 + 2O2 -> CO2 + 2H2O",
  "message": "Balanced: CH4 + 2O2 -> CO2 + 2H2O",
  "species": [ { "formula": "CH4", "writtenCoefficient": 1, "side": "left", "counts": { "C": 1, "H": 4 }, "charge": 0 }, … ]
}

Checking figures and text

Journal specs available to figure-standards: nature, science, cell, pnas, plos, elife, elsevier, springer, wiley, ieee, acs, rsc, aps, bmj, lancet, frontiers, mdpi, thesis, poster-a0, slide-16x9.

Chemistry and physics

Study design and reporting

Models drawn on a figure, and data

These operations read the models drawn on a Science figure (send the figure's JSON as figure: { nodes, edges, ledger? }), or work on pasted data (tab-separated text with a header row). Every computed number is recorded in a provenance ledger entry that names the method and its version; GET /api/v1/science lists every method in methods.

Server budgets for these operations: 20,000 integration steps, 20,000 fit evaluations and 500 Monte Carlo runs per request. An operation that hits a budget, lacks a seed or cannot identify a fit answers HTTP 200 with ok: false and a named refusal.

Related endpoints

These also accept your API key and are documented on their own pages.

The web app also calls other internal endpoints. Only the endpoints on this page and the ones above are the public API; anything else may change without notice.

Error reference

Errors shared by several endpoints:

Errors from AI calls (diagram, and convert or detect when they need AI). Remember that convert answers with its lossy built-in result instead of most of these when it has one, and detect answers with a low-confidence guess instead of every one except the key problems marked below:

Recipes

A shell script for CI

Fail the build if any architecture diagram is broken, and print why. Requires curl and jq.

#!/usr/bin/env bash
set -euo pipefail
: "${FLOWSS_API_KEY:?Set FLOWSS_API_KEY}"
API="https://www.flowss.ai/api/v1/critique"
status=0
for f in docs/diagrams/*.mmd; do
  body=$(jq -n --arg c "$(cat "$f")" '{engine:"mermaid", code:$c, gate:"sound"}')
  res=$(curl -sS -X POST "$API" \
    -H "Authorization: Bearer $FLOWSS_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$body")
  if [ "$(echo "$res" | jq -r '.pass // empty')" = "true" ]; then
    echo "ok    $f: $(echo "$res" | jq -r .readiness.level)"
  else
    echo "FAIL  $f: $(echo "$res" | jq -r '.readiness.blocking[0] // .readiness.reason // .error')"
    status=1
  fi
done
exit $status

Each file is one deterministic call. With more than a few dozen diagrams, run this only on the files a pull request changed.

Diff every changed diagram in one call (Node.js 18 or later)

const res = await fetch("https://www.flowss.ai/api/v1/diff?format=markdown", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FLOWSS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    files: [
      { path: "docs/arch.d2", engine: "d2", before: oldArch, after: newArch },
      { path: "db/schema.sql", engine: "sql", before: oldSchema, after: newSchema },
    ],
  }),
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const { results, changed, total, markdown } = await res.json();
console.log(`${changed} of ${total} diagrams changed`);
console.log(markdown); // paste into a pull-request comment

Generate a diagram and save it as SVG (Python)

import os, requests

KEY = os.environ["FLOWSS_API_KEY"]
H = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

gen = requests.post("https://www.flowss.ai/api/v1/diagram", headers=H, timeout=60,
                    json={"prompt": "Order-to-cash process with credit check", "engine": "mermaid"})
gen.raise_for_status()
d = gen.json()
print(d["title"], d["embed_url"])

# Rasterise on the server where the engine allows it (see the render API page).
img = requests.post("https://www.flowss.ai/api/render", headers=H, timeout=60,
                    json={"engine": d["engine"], "code": d["code"], "format": "svg"})
if img.ok:
    open("diagram.svg", "wb").write(img.content)
else:
    print("Render not available here:", img.json().get("error"))

Retrying safely

• Retry 502 and 503 responses with exponential backoff, and honour Retry-After when it is present.
• Do not retry 400, 401, 402, 404, 413 or 422 unchanged: they will fail the same way.
• Do not retry a 429 before midnight UTC; it will fail the same way until the allowance resets.

Tips

• Start every new integration with a GET on the endpoint: it costs nothing and shows the exact body it accepts today.
• Batch generate and diff calls. A pull request touching 40 diagrams costs one call in batch mode and 40 otherwise.
• Always send sourceEngine to convert. Without it the built-in converters cannot run and every conversion uses AI.
• Pin direction and title on generate so a committed artifact never changes for reasons other than its source.
• Send request to critique when the diagram was made from a written brief: it is the only way the fidelity dimension is judged.
• Name verified diagram nodes after the services, tables or endpoints they stand for, so verify can match them.
• Keep one key per pipeline and check last used on your account page to find keys you can revoke.

Limits and known constraints

• The deterministic allowance is 60 calls a day per account on every plan, and it is shared with the render API, living-diagram drift checks and some Evidence actions. Upgrading does not raise it.
• Several endpoints count a request before reading its body, so a malformed request still spends one call.
• generate, diff and verify understand eight structural notations plus Weave boards, and read Mermaid flowcharts only. Other engines get a text-only comparison on diff and are refused by generate (as an ok: false result) and verify.
• verify matches entities by normalised name; differently named nodes for the same thing are reported as drift. Extra relations drawn in the diagram are reported but do not fail pass.
• detect and convert are not counted against the 60-a-day deterministic allowance, but their AI path is limited by your points and your daily own-key ceiling.
• critique cannot draw browser-rendered engines on the server, so for those the render check is reported as not run.
• detect sends at most the first 4,000 characters of a snippet to AI.
• The diagram endpoint returns an embed_url that encodes the whole source in the address. Very large diagrams make very long links; for those, save the source and use the embed script instead.
• The API sends no CORS headers and is meant for servers, scripts and CI, not for browser code on other sites.
• Keys cannot be scoped to particular endpoints or projects and do not expire; revoke unused keys.
• A key saved to your account for the web app is not used by API calls; send X-User-Api-Key with each request instead.

Troubleshooting

Related pages

• Integrations and extensions
• Embedding and the render API
• The flowss MCP server
• AI points and limits
• Bring your own AI key
• Plans and what they include
• Choosing an engine and the engine reference
• Evidence and Science
• Account settings and your data
• Security at flowss