---
title: "Generate or edit and save an owned native diagram"
method: POST
path: "/generations"
---

# Generate or edit and save an owned native diagram

`POST /generations`

## Request

- Base URL: `https://flowchartai.org/api/v1`
- URL: `https://flowchartai.org/api/v1/generations`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

## Headers

- `Idempotency-Key` string, required

## Request body

- Generation
  - `prompt` string, required
  - `max_credits` integer, required: Upper limit. A cap below the full-context estimate returns 409 max_credits_too_low with required_credits before generation. Never raise it without owner authorization. The accepted reservation may be lower; actual full-task provider usage is capped at that reservation.
  - `image` string: Optional PNG/JPEG/WebP base64 data URI, at most 2 MB decoded. Arbitrary URLs are not fetched.
  - `diagram_id` string: Existing owned native file to edit; omit to create. Edits also require diagrams:read in addition to diagrams:write and diagrams:generate.
  - `expected_version` string: Required when diagram_id is set. Read the latest file first.

## Response `200`

Successful response

- Task
  - `id` string, uuid, required
  - `state` 'running' | 'prepared' | 'succeeded' | 'failed', required
  - `operation` 'generate' | 'edit' | 'save', required
  - `diagram_id` string, required
  - `budget_credits` integer, required: Accepted task estimate, retained after settlement.
  - `reserved_credits` integer, required
  - `charged_credits` integer, required
  - `diagram` Diagram
    - `id` string, required
    - `title` string, required
    - `version` string, required: Digest of the saved title and content, including website changes.
    - `format` 'drawio' | 'legacy'
    - `document` object: Included on reads; native document or original legacy JSON.
    - `open_url` string, uri, required
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `error` object
    - `code` string
    - `message` string
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `400`: Invalid request, credentials, ownership, allowance, conflict, budget, or unavailable upstream. A 429 response includes Retry-After.
- `401`: Invalid request, credentials, ownership, allowance, conflict, budget, or unavailable upstream. A 429 response includes Retry-After.
- `402`: Invalid request, credentials, ownership, allowance, conflict, budget, or unavailable upstream. A 429 response includes Retry-After.
- `403`: Invalid request, credentials, ownership, allowance, conflict, budget, or unavailable upstream. A 429 response includes Retry-After.
- `404`: Invalid request, credentials, ownership, allowance, conflict, budget, or unavailable upstream. A 429 response includes Retry-After.
- `409`: Invalid request, credentials, ownership, allowance, conflict, budget, or unavailable upstream. A 429 response includes Retry-After.
- `413`: Invalid request, credentials, ownership, allowance, conflict, budget, or unavailable upstream. A 429 response includes Retry-After.
- `422`: Invalid request, credentials, ownership, allowance, conflict, budget, or unavailable upstream. A 429 response includes Retry-After.
- `429`: Invalid request, credentials, ownership, allowance, conflict, budget, or unavailable upstream. A 429 response includes Retry-After.
- `502`: Invalid request, credentials, ownership, allowance, conflict, budget, or unavailable upstream. A 429 response includes Retry-After.
- `503`: Invalid request, credentials, ownership, allowance, conflict, budget, or unavailable upstream. A 429 response includes Retry-After.

---

[API](https://skmtc.dev/flowchartai/apis/flowchartai-developer-api.md) · [All operations](https://skmtc.dev/flowchartai/apis/flowchartai-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flowchartai/apis/flowchartai-developer-api/revisions/914d81b5d394?raw)