> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anonalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Draw

> Ask for a chart or a diagram in plain language and get it drawn from a space's memories, with copyable Mermaid source.

> [!NOTE]
>
> The route is `/graph` for historical reasons. It is not the [entity graph](/api-reference/graph.md), which lists the entities a space has extracted. In the dashboard this is the `/draw` command; see [Charts, diagrams and artifacts](/guides/charts-diagrams-artifacts.md).

Ask for a chart in plain language and get back a validated chart spec, the same chart
as [Mermaid](https://mermaid.js.org) source, and any short note the model added. Ask
about a process or a structure instead ("how does signup work", "flow chart of our
release process") and you get a Mermaid diagram rather than a chart. Either one is drawn from this space's memories and its curated summaries ([memory models](/api-reference/models.md)) only: every number in it has to come from
what the space holds. When the memories do not contain the numbers, you get no chart
and a sentence saying so, rather than a plausible guess.

## Request

```http theme={null}
POST /v1/spaces/{space_id}/graph
Authorization: Bearer anona_live_YOUR_KEY
Content-Type: application/json
```

```json theme={null}
{
  "request": "Deploys per week this month"
}
```

| Parameter | Type | Required | Description |
| - | - | - | - |
| `request` | string | Yes | What to chart, 1 to 2,000 characters. |
| `model` | string | No | Which LLM draws the chart: a tier name (`fast`, `balanced`) or a model id. Defaults to the space's chat default, then to the platform default. See [model selection](/api-reference/model-selection.md). |
| `conversation` | object\[] | No | Earlier turns, oldest first, so a follow-up such as "now by month" has context. Up to 40, each `{"role": "user" or "assistant", "content": string}`. |

Unknown fields are rejected with `422 validation_error`.

**Response** `200 OK`

```json theme={null}
{
  "chart": {
    "type": "bar",
    "title": "Deploys per week",
    "x": "week",
    "y": ["deploys"],
    "data": [
      { "week": "Oct 5", "deploys": 3 },
      { "week": "Oct 12", "deploys": 5 }
    ]
  },
  "mermaid": "xychart-beta\n    title \"Deploys per week\"\n    x-axis [\"Oct 5\", \"Oct 12\"]\n    y-axis \"deploys\"\n    bar [3, 5]",
  "text": "Deploys per week, from the release notes in this space.",
  "model": "us.amazon.nova-pro-v1:0"
}
```

| Field | Type | Description |
| - | - | - |
| `chart` | object or null | The chart spec described below. Null when the answer is a diagram, when the memories hold no numbers for the request, when the model's chart did not validate, or when the chart was too large to finish (then `text` asks for fewer categories or a shorter time range). |
| `diagram` | string or null | Mermaid source for a process or structure answer, validated as described under [Diagrams](#diagrams). Null for a chart, and when the model's diagram was refused. Never set together with `chart`. |
| `mermaid` | string or null | Copyable Mermaid source. For a chart, its Mermaid export (null for scatter charts and for a pie chart with a negative value). For a diagram, the same text as `diagram`. Null when neither was drawn. |
| `text` | string | The model's prose, without the chart or diagram block. When both are null this is the explanation. |
| `model` | string | The model that answered. |

```bash cURL theme={null}
curl -X POST https://api.anonalabs.com/v1/spaces/release-notes/graph \
  -H "Authorization: Bearer anona_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request": "Deploys per week this month"}'
```

```python Python theme={null}
import httpx

resp = httpx.post(
    "https://api.anonalabs.com/v1/spaces/release-notes/graph",
    headers={"Authorization": "Bearer anona_live_YOUR_KEY"},
    json={"request": "Deploys per week this month"},
    timeout=120,
)
body = resp.json()
if body["chart"] is None and body["diagram"] is None:
    print(body["text"])
else:
    print(body["mermaid"])
```

```typescript TypeScript theme={null}
const resp = await fetch(
  "https://api.anonalabs.com/v1/spaces/release-notes/graph",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer anona_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ request: "Deploys per week this month" }),
  },
);
const body = await resp.json();
console.log(body.chart || body.diagram ? body.mermaid : body.text);
```

## The chart spec

| Field | Type | Description |
| - | - | - |
| `type` | string | One of `bar`, `line`, `area`, `pie`, `scatter`. |
| `title` | string | Chart title. May be empty. |
| `x` | string | The key in each row that holds the category or x value. Its values are strings or numbers. |
| `y` | string\[] | The keys in each row that hold the plotted values, one series each. Every value is a finite number. A pie chart uses only the first. |
| `data` | object\[] | The rows, 1 to 500. A row may carry keys beyond `x` and `y`; they are returned as they came. |
| `unit` | string | Optional label for the value axis. |

The same spec is what the dashboard's Ask tab draws for `/draw`, so a chart looks the
same wherever it was asked for.

## Mermaid mapping

| Chart type | Mermaid |
| - | - |
| `bar` | `xychart-beta` with one `bar` series per `y` key |
| `line` | `xychart-beta` with one `line` series per `y` key |
| `area` | `xychart-beta`, drawn as `line` series (Mermaid has no area series) |
| `pie` | `pie`, one slice per row from the first `y` key. Null if any value is negative. |
| `scatter` | None. Mermaid has no scatter chart, so `mermaid` is null. |

The value axis is labelled with `unit`, or with the first `y` key when `unit` is absent
or empty. An empty title leaves the title line out. Labels are quoted; a double quote
inside one becomes a single quote, and runs of whitespace become one space, because
Mermaid has no escape inside a quoted label.

## Diagrams

A diagram is Mermaid source written by the model from this space's memories. Every
node, step and label has to come from what the space holds; when the memories do not
describe what you asked for, you get no diagram and a sentence saying so.

The first line must name one of these diagram types, spelled exactly as Mermaid
spells it: `flowchart`, `graph`, `sequenceDiagram`, `stateDiagram`, `stateDiagram-v2`,
`mindmap`, `timeline`.

A diagram is refused whole, never edited, when it (node shapes in mind maps and label quoting in flowcharts are normalised, so labels are neither clipped nor rejected for containing parentheses; nothing else is ever edited):

* uses any other diagram type
* is longer than 8,000 characters or 200 lines
* contains a `%%{` init or directive block
* has a line starting with `click`
* contains `href`, `javascript:`, `<script`, `<iframe`, `url(` or `@import` (in any letter case)
* contains a `call` callback such as `call doThing()`

A refused diagram comes back as `diagram: null` and `mermaid: null`, with `text`
holding the model's note, or "The diagram could not be drawn from that answer." when
it wrote none.

```json theme={null}
{
  "chart": null,
  "diagram": "flowchart TD\n    A[Sign up] --> B[Verify email]\n    B --> C[Account usable]",
  "mermaid": "flowchart TD\n    A[Sign up] --> B[Verify email]\n    B --> C[Account usable]",
  "text": "How signup works, from the onboarding notes in this space.",
  "model": "us.amazon.nova-pro-v1:0"
}
```

## What it costs

A chart or diagram is billed as one chat turn on the model that drew it, to the organization
making the request (on a shared space, that is you, not the space's owner). Nothing is
written back into the space, so a read-only member of a space can ask for charts and diagrams too.

## Errors

| Status | Code | Cause |
| - | - | - |
| 400 | `unsupported_model` | `model` is not one this deployment serves. |
| 400 | `invalid_model` | The provider rejected a model this deployment serves. |
| 401 | `missing_auth` / `invalid_api_key` | Missing or invalid credentials. |
| 403 | `space_access_denied` | You are not a member of this space. |
| 404 | `space_not_found` | The space does not exist. It is not created, and you are not charged. |
| 422 | `validation_error` | The body fails validation, including unknown fields. |
| 429 | `rate_limited` / `credits_exhausted` | Rate limit reached, or the credit allowance is spent. |
| 503 | `llm_error` / `llm_unreachable` | The model provider failed. Safe to retry. |

## Next steps

> **[Charts, diagrams and artifacts](/guides/charts-diagrams-artifacts.md)**
>
> Use `/draw` and `/artifact` in the dashboard.

> **[Artifacts API](/api-reference/artifacts.md)**
>
> Build a shareable page about a space.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.