Developer quickstart
Create once. Patch. Validate.
Use a personal key and one disposable diagram to learn the portable model. No private infrastructure or customer data is included.
Before you begin
You need an active account, a personal key from your profile, curl and jq. Legacy personal keys inherit the account's access. When the scoped-agent preview is enabled, /connect-agent issues resource-limited MCP credentials; those credentials do not authorize this REST quickstart. Use a dedicated limited-permission account for automation and never give an agent the platform-wide server key.
Core OpenAPI 3.1 contract · Portable JSON schema v1 · Download these commands · All route discovery
Run the workflow
# Use a personal key from /profile, never a platform-wide server key.
# Keep it in an environment variable supplied by your secret manager.
# Run against a disposable development account first.
export FLOWBOARD_URL=${FLOWBOARD_URL:-https://flowboard.studio}
# Download a public, portable fixture.
curl --fail --silent --show-error "$FLOWBOARD_URL/api/examples/api-database" > example.json
# Create one private diagram. Keep its ID and reuse it.
curl --fail --silent --show-error "$FLOWBOARD_URL/api/diagrams" \
-H "Authorization: Bearer $FLOWBOARD_PERSONAL_KEY" \
-H 'Content-Type: application/json' --data-binary @example.json > created.json
diagram_id=$(jq -r .id created.json)
# Patch through MCP. REST supports PUT replacement, not PATCH.
jq -n --arg id "$diagram_id" '{jsonrpc:"2.0",id:1,method:"tools/call",params:{name:"patch_diagram",arguments:{id:$id,operations:[{op:"set_title",title:"My request path"}]}}}' |
curl --fail --silent --show-error "$FLOWBOARD_URL/mcp" \
-H "Authorization: Bearer $FLOWBOARD_PERSONAL_KEY" \
-H 'Content-Type: application/json' --data-binary @- > patched.json
# MCP tool failures can have HTTP 200. Check result.isError, too.
jq -e '.error == null and .result.isError != true' patched.json
# Read and validate the result; expect the title My request path.
curl --fail --silent --show-error "$FLOWBOARD_URL/api/diagrams/$diagram_id" \
-H "Authorization: Bearer $FLOWBOARD_PERSONAL_KEY" > current.json
jq -e '.title == "My request path"' current.json
curl --fail --silent --show-error "$FLOWBOARD_URL/api/diagrams/$diagram_id/validate" \
-H "Authorization: Bearer $FLOWBOARD_PERSONAL_KEY"
# Export Markdown and YAML without exposing the private model publicly.
curl --fail --silent --show-error "$FLOWBOARD_URL/api/diagrams/$diagram_id/markdown" \
-H "Authorization: Bearer $FLOWBOARD_PERSONAL_KEY" > model.md
curl --fail --silent --show-error "$FLOWBOARD_URL/api/diagrams/$diagram_id/yaml" \
-H "Authorization: Bearer $FLOWBOARD_PERSONAL_KEY" > model.yaml
# Optional cleanup: DELETE this exact disposable diagram ID only after review.
Expected result and round trip
You have one private diagram with the title My request path, three nodes, two flows and the same IDs in JSON, Markdown and YAML. Import an exported file into a separate example draft to check its visual form. Validation findings are data: HTTP 200 does not by itself mean there are no findings.
Limits and failures
Each diagram accepts at most 500 nodes, 1,000 flows, and 200 notes. These are storage validation limits, not a guarantee of smooth rendering at the maximum. These limits apply to standalone diagrams. The separately gated workspace model supports up to 5,000 entities and 10,000 relationships, with the same per-view diagram limits; it is not an automatic migration of standalone diagrams.
- Diagram mutations and MCP requests: 1 MiB. Unsaved validation wrapper: 2 MiB.
- Personal diagram lists have no cursor pagination. The trusted server-key list is capped at 200; do not use it as a customer listing API.
- REST failures return an error message with an appropriate status. MCP may return result.isError at HTTP 200, or a JSON-RPC error. Inspect both layers.
- For REST PUT, send the last updatedAt as If-Match. On conflict, reread and review; never retry a stale replacement blindly.
- Personal MCP patches refuse a concurrent version change. Re-read, review, then retry a focused patch. Full replacement still requires deliberate coordination.
Keys and organization scope
Rotate by creating a replacement key at /profile, updating the authorized client and revoking the previous key. Verify the old key fails. Organization creation uses X-Flowboard-Organization only for an already-provisioned company and an authorized member. Personal sign-in does not create a paid company.
Compatibility
The public portable format uses flows, not the editor's internal connections field. Preserve stable object IDs when editing labels. A schema describes shape, while server validation checks references, cycles and supported types. Changes that remove fields or change semantics require a new schema version and migration notes. Review tools/list on connection; gated tools may be absent.