Try DrawSQL

REST API

.md

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

On this page

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, 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:

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.

curl https://api.drawsql.app/v1/diagrams \
  -H "Authorization: Bearer $DRAWSQL_TOKEN"
{
  "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:

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

This page covers the common workflows. Every endpoint, field, and response is in the API reference.

Authentication

Every request needs a personal access token. You may create one under Account → 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.

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

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

Read a schema

  1. List diagrams (GET /diagrams) to find the uuid.
  2. Get the 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.
  3. Need the canvas too? Get the full document (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.

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 (POST /diagrams) from SQL DDL or from a schema patch:

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 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.

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 so the patch starts from what is there.
  2. Read the data types for its driver and the schema patch format.
  3. Propose the patch (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 (GET /proposals/{uuid}) until it is applied, declined, or expired. Send If-None-Match to get a cheap 304 while nothing changes.
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.

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

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.

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.

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.

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.
429 rate_limited Too many requests. Wait for the seconds in Retry-After.

Reference

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

Still have a question? We'd love to help!