# SayDiagram — Public API integration for AI agents

## Product

SayDiagram turns a plain-language idea or a diagram photo into editable Mermaid, saves a diagram in the user's account, and returns an editorUrl.

Website: https://saydiagram.com

## Prerequisites

1. User must be on Pro or Team (or inherit Pro quotas via Team membership).
2. User creates an API key at https://saydiagram.com/profile (shown once; format sd_live_…).
3. Store the secret only in a server-side secret store. Never expose it to end-user browsers.

## Auth

Header (pick one):
  Authorization: Bearer sd_live_YOUR_SECRET
  X-Api-Key: sd_live_YOUR_SECRET

Errors:
  401 { "error": "…", "code": "API_KEY_INVALID" }
  403 { "error": "…", "code": "API_KEY_PLAN_REQUIRED" }

## Discovery

- Short index: https://saydiagram.com/llms.txt
- This file: https://saydiagram.com/llms-full.txt
- OpenAPI 3.1: https://saydiagram.com/openapi.json
- Human docs: https://saydiagram.com/doc/public-api
- Agent docs: https://saydiagram.com/doc/agents

## Recommended agent workflow

1. Fetch https://saydiagram.com/openapi.json (or this file) to learn the contract.
2. Confirm the user has a key (or instruct them to create one in Profile).
3. GET /me to verify the key and remaining quotas.
4. POST from-idea or from-image.
5. Return editorUrl to the user so they can open Arrange / export.

## GET /me

curl -s https://saydiagram.com/api/v1/me \
  -H "Authorization: Bearer sd_live_YOUR_SECRET"

Returns plan, effectivePlan, viaTeamMembership, and entitlements.ideaGenerations / imageScans / aiLayouts (used, limit, remaining).

## POST /diagrams/from-idea

Body JSON:
  idea (string, required, max 2000)
  diagramType (optional): flowchart, sequence, er, state, class, mindmap, timeline, requirement, pie, gantt, gitgraph, c4, sankey
  folderId (optional): owned folder id

curl -s -X POST https://saydiagram.com/api/v1/diagrams/from-idea \
  -H "Authorization: Bearer sd_live_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"idea":"User signs up, verifies email, then lands on dashboard","diagramType":"flowchart"}'

Quota: Pro/Team 100 ideas / UTC day (same as web app).

## POST /diagrams/from-image

Formats: image/png, image/jpeg, image/webp. Max 4MB.

Multipart:
curl -s -X POST https://saydiagram.com/api/v1/diagrams/from-image \
  -H "Authorization: Bearer sd_live_YOUR_SECRET" \
  -F "file=@whiteboard.png"

JSON alternative:
  { "imageBase64": "<base64 or data URL>", "mimeType": "image/png", "filename": "whiteboard.png", "folderId": "…" }

Quota: Pro/Team 20 scans / UTC day.

## Success response (201)

{
  "id": "…",
  "title": "…",
  "slug": "…",
  "content": "flowchart LR\n  …",
  "layoutJson": "…" | null,
  "visibility": "PRIVATE",
  "folderId": null,
  "createdAt": "ISO-8601",
  "updatedAt": "ISO-8601",
  "editorUrl": "https://saydiagram.com/editor/…"
}

## Other errors

  403 IDEA_GENERATE_DAILY_LIMIT / IMAGE_SCAN_DAILY_LIMIT — daily quota exhausted
  429 AI_RATE_LIMIT — soft per-user AI rate limit (in-memory; may vary across instances)
  422 — validation / empty model / invalid image
  502 / 503 — upstream AI failure or missing server OpenAI config

## Out of scope (v1)

List/delete diagrams, regenerate-into-id, batch scan, Free-tier keys, MCP server.