# REST API

Read your team's schemas, create private diagrams, and propose changes that you can review and apply in DrawSQL. Available on paid plans.

## Quick start

Get the schema JSON for any of your diagrams in three steps: create a token, find the diagram's `uuid`, read its schema. You need a team on a paid plan.

### 1. Create a token

Go to [Account → API tokens](/user/api-tokens), pick the team you want to work with, and create a token. The token is shown once. Copy it into an environment variable so the rest of these commands paste as-is:

```bash
export DRAWSQL_TOKEN="<your-token>"
```

### 2. Find a diagram

List the diagrams your token can see. Every diagram has a `uuid`, which is how the rest of the API refers to it.

```bash
curl https://api.drawsql.app/v1/diagrams \
  -H "Authorization: Bearer $DRAWSQL_TOKEN"
```

```json
{
  "data": [
    {
      "uuid": "ee49b61f-5425-4013-ade7-3c83fd43be3f",
      "name": "Orders service",
      "table_count": 12
    }
  ]
}
```

### 3. Read its schema

Take a `uuid` from that response and ask for the schema. Piping through `jq` shows you the table names straight away:

```bash
curl https://api.drawsql.app/v1/diagrams/ee49b61f-5425-4013-ade7-3c83fd43be3f/schema \
  -H "Authorization: Bearer $DRAWSQL_TOKEN" | jq '.data.tables[].name'
```

```text
"orders"
"order_items"
"users"
```

This page covers the common workflows. Every endpoint, field, and response is in the [API reference](/reference/api).

## Authentication

Every request needs a personal access token. You may create one under [Account → API tokens](/user/api-tokens). Each token belongs to one team and can read the diagrams you can already see in that team, so there is nothing extra to configure. You may choose an expiry of 30 days, 90 days, 1 year, or 2 years; if you are unsure, the default of 1 year is a sensible choice. The token stops working if you leave the team or the team's plan lapses.

```bash
curl https://api.drawsql.app/v1/diagrams \
  -H "Authorization: Bearer <your-token>"
```

Session cookies are not supported. Send the token as a bearer token on every request. Treat it like a password: anyone with it can use the access it grants. You can revoke a token at any time from the same settings page.

## Base URL & responses

```text
https://api.drawsql.app/v1
```

Responses with a body use JSON. Successful responses use a top-level `data` field; errors use a top-level `error` field. We may add fields within v1, so ignore unknown fields. Don't worry about your integration breaking: we will not rename or remove an existing field without shipping a new version (`/v2`) and giving at least six months' notice.

## Workflows

<span id="list-diagrams"></span><span id="get-a-diagram"></span><span id="get-a-diagrams-schema"></span><span id="markdown-for-an-llm"></span><span id="get-the-full-diagram-document"></span>

### Read a schema

1. [List diagrams](/reference/api#tag/diagrams/GET/diagrams) (`GET /diagrams`) to find the `uuid`.
2. [Get the schema](/reference/api#tag/diagrams/GET/diagrams/{uuid}/schema) (`GET /diagrams/{uuid}/schema`): tables, columns, indexes, and relationships. Columns name their type by `driver_data_type_name`; resolve it with the [data-type catalog](/reference/api#tag/data-types/GET/data-types).
3. Need the canvas too? [Get the full document](/reference/api#tag/diagrams/GET/diagrams/{uuid}/schema-full) (`GET /diagrams/{uuid}/schema-full`), which adds positions, colors, groups, and sticky notes and can be imported back into DrawSQL.

To paste a schema into an LLM, ask for Markdown instead of JSON. Add `?format=ai`, or send `Accept: text/markdown`. Add `?level=simple` for column names only.

```bash
curl "https://api.drawsql.app/v1/diagrams/<uuid>/schema?format=ai" \
  -H "Authorization: Bearer $DRAWSQL_TOKEN"
```

This is the same text DrawSQL's **Take to your AI** puts on your clipboard, and the same text the MCP `get_schema` tool returns.

### Create a diagram

Choose **Read and write** under **Access** when you create the token. New diagrams are created, private, in the token's team.

[Create a diagram](/reference/api#tag/diagrams/POST/diagrams) (`POST /diagrams`) from SQL DDL or from a schema patch:

```bash
curl https://api.drawsql.app/v1/diagrams \
  -H "Authorization: Bearer $DRAWSQL_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name": "Orders service", "driver": "pgsql", "ddl": "CREATE TABLE users (id BIGINT PRIMARY KEY);"}'
```

A schema patch returns `201` with the finished diagram. SQL DDL may take longer: a `202` means the import is still running, so poll [the diagram](/reference/api#tag/diagrams/GET/diagrams/{uuid}) every `poll_after_seconds` until `status` is `ready` or `failed`. If a request times out, send it again: an identical retry within two minutes returns the same diagram instead of a second one.

<span id="writes"></span><span id="proposal-status"></span>

### Propose changes

Changes to an existing diagram are saved as proposals. An editor reviews each one in DrawSQL before anything changes. Applying a proposal updates the diagram; it does not run a database migration.

1. [Read the schema](/reference/api#tag/diagrams/GET/diagrams/{uuid}/schema) so the patch starts from what is there.
2. Read the [data types](/reference/api#tag/data-types/GET/data-types) for its driver and the [schema patch format](/reference/schema-patch).
3. [Propose the patch](/reference/api#tag/proposals/POST/diagrams/{uuid}/proposals) (`POST /diagrams/{uuid}/proposals`) with a `title` and a `message` that says why.
4. Hand the returned `review_url` to someone who can edit the diagram. It opens the editor, where the change shows as **Proposed changes**: a diff they apply or decline.
5. [Poll the status](/reference/api#tag/proposals/GET/proposals/{uuid}) (`GET /proposals/{uuid}`) until it is `applied`, `declined`, or `expired`. Send `If-None-Match` to get a cheap `304` while nothing changes.

```bash
curl https://api.drawsql.app/v1/diagrams/<uuid>/proposals \
  -H "Authorization: Bearer $DRAWSQL_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title": "Add order notes", "message": "Support needs free-text notes on orders.", "schema": {"strategy": "merge", "tables": [{"name": "orders", "columns": [{"name": "notes", "type": "text", "is_nullable": true}]}]}}'
```

A proposal expires after 30 days; an editor can reopen it. Proposals are never deduplicated, so retry only a request that returned no `uuid`. A declined proposal is closed: read its `decline_reason` and send a new one.

### Using write access with AI agents

Review the proposed changes before applying them. Schema names and comments can contain instructions that influence an AI agent. Before applying, DrawSQL highlights destructive changes to the diagram, such as removing tables or columns.

DrawSQL also limits how submitted content appears in responses and during review. Proposal responses include counts rather than names or values from the patch. Reviewers see proposal titles and messages as plain text, with no markup or links. Review URLs contain only an opaque proposal ID. These safeguards do not replace your review of the proposed changes.

## Pagination

`GET /diagrams` returns 25 diagrams per page by default; pass `?limit=` (1–100) for more. When `meta.has_more` is true, pass `meta.next_cursor` back as `?cursor=` to fetch the next page.

```bash
curl "https://api.drawsql.app/v1/diagrams?limit=50&cursor=<next-cursor>" \
  -H "Authorization: Bearer <your-token>"
```

<span id="conditional-requests"></span>

## Caching with ETags

The schema endpoints, data types, and the patch contract return an `ETag`. Send it back as `If-None-Match`; if nothing changed, you get a `304 Not Modified` with no body, which is cheap to poll.

```bash
curl -i "https://api.drawsql.app/v1/diagrams/<uuid>/schema" \
  -H "Authorization: Bearer <your-token>" \
  -H 'If-None-Match: "19b90083562ef66e0e0d9562fc4f4abbb8740b54"'
# → HTTP/1.1 304 Not Modified
```

| Endpoint | ETag changes when |
| --- | --- |
| `/diagrams/{uuid}/schema` | The schema content changes, including table or column comments. Canvas-only edits, such as moving or recoloring a table, still return `304`. |
| `/diagrams/{uuid}/schema-full` | Any schema or canvas edit represented in the full document. |

## Rate limits

| Operation | Limit |
| --- | --- |
| Listing or reading a diagram, data types, or the patch contract | 60 / minute, per token |
| Reading a proposal's status | Counts toward the 60 / minute read limit above |
| Reading `/schema` or `/schema-full` | 30 / minute, per token |
| Creating a diagram or proposing changes | 10 / minute, per token, one limit shared by both |
| Any request | 60 / minute, per IP |

Authenticated responses carry `X-RateLimit-Limit` and `X-RateLimit-Remaining`. Over a limit, you get a `429` with a `Retry-After` header that says how many seconds to wait.

<span id="errors"></span><span id="retries"></span>

## Common mistakes

Errors look like `{"error": {"code": "plan_required", "message": "..."}}`. The `code` is stable, so branch on it rather than on the message. These are the ones people hit most; the full list is in the [API reference](/reference/api).

| Code | What happened | Fix |
| --- | --- | --- |
| `401 unauthenticated` | The token is missing, expired, or revoked. | Check the `Authorization: Bearer` header, then create a new token. |
| `401 invalid_token` | The token's team was deleted, or you left it. | Create a token in a team you belong to. |
| `403 plan_required` | The token's team is not on a paid plan. | Upgrade the team, or use a token from a paid team. |
| `404 not_found` | The diagram does not exist, or your token cannot see it. | List diagrams to get a `uuid` the token can see. |
| `409 diagram_not_ready` | The diagram is still importing. | Poll the diagram until `status` is `ready`. |
| `403 insufficient_scope` | The token has read access only. | Create a token with **Read and write** access. |
| `403 editor_required` | The token's user can view the diagram but not edit it. | Ask for edit access, or use another user's token. |
| `422 invalid_schema` | The schema patch failed validation. | Read `errors` (up to 15 problems) and check the [patch format](/reference/schema-patch). |
| `429 rate_limited` | Too many requests. | Wait for the seconds in `Retry-After`. |

<span id="openapi"></span><span id="data-types"></span><span id="schema-patch-contract"></span>

## Reference

Every endpoint, field, and response is in the interactive [API reference](/reference/api). The contract is also published as an OpenAPI 3.1 document at [drawsql.app/openapi.yaml](/openapi.yaml); point a client generator at it to get typed models.
