API reference

POST /drawing

Uploads the migration files and queues the drawing. Answers 202 Accepted with the job id. The request is multipart/form-data; every field other than files may be sent as a form field or as a query parameter.

Headers

Form fields

Example

curl -X POST https://schemadrawer.com/api/v1/drawing \
  -H "Request-Id: $(uuidgen)" \
  -F "userId=5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f" \
  -F "migrationType=FLYWAY" \
  -F "databaseType=POSTGRESQL" \
  -F "version=18" \
  -F "files=@db/migration/V1__create_owners_and_pets.sql" \
  -F "files=@db/migration/V2__create_vets.sql" \
  -F "files=@db/migration/V3__create_visits.sql"
# {"jobId":"0b6e2f4c-8d1a-4c3e-9f7a-2a5b6c7d8e9f"}

Responses

{"jobId": "0b6e2f4c-8d1a-4c3e-9f7a-2a5b6c7d8e9f"}

GET /drawing/{jobId}

The job as it stands. Poll it every two or three seconds until status is SUCCESS or ERROR.

Examples

curl https://schemadrawer.com/api/v1/drawing/0b6e2f4c-8d1a-4c3e-9f7a-2a5b6c7d8e9f

{
  "jobId": "0b6e2f4c-8d1a-4c3e-9f7a-2a5b6c7d8e9f",
  "status": "PENDING",
  "createdAt": "2026-09-25T08:00:00Z",
  "errorMessage": null,
  "diagramUrl": null
}

{
  "jobId": "0b6e2f4c-8d1a-4c3e-9f7a-2a5b6c7d8e9f",
  "status": "SUCCESS",
  "createdAt": "2026-09-25T08:00:00Z",
  "errorMessage": null,
  "diagramUrl": "https://.../0b6e2f4c-8d1a-4c3e-9f7a-2a5b6c7d8e9f/diagram.svg?X-Amz-Expires=3600&..."
}

{
  "jobId": "7d2e9a10-4c6b-4f1e-9b3a-5e8d1c2f3a4b",
  "status": "ERROR",
  "createdAt": "2026-09-25T08:03:12Z",
  "errorMessage": "Flyway migration failed (exit code 1).\nOutput:\nFlyway OSS Edition 13.7.0 by Redgate\n...\nMigrating schema \"public\" to version \"1 - create owners\"\nErrors:\nERROR: Migration of schema \"public\" to version \"1 - create owners\" failed! Changes successfully rolled back.\nERROR: Failed to execute script V1__create_owners.sql\n----------------------------------------------\nSQL State  : 42601\nMessage    : ERROR: syntax error at or near \"last_name\"\n  Position: 100\nLocation   : /flyway/sql/V1__create_owners.sql\nLine       : 1",
  "diagramUrl": null
}

404 is answered for an unknown job id.

Error format

Every error is answered in one JSON shape, with a message written for the person calling:

{
  "timestamp": "2026-09-25T08:00:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Unsupported POSTGRESQL version: 9. Supported versions: 10, 11, 12, 13, 14, 15, 16, 17, 18",
  "path": "/api/v1/drawing"
}

{
  "timestamp": "2026-09-25T08:00:00Z",
  "status": 413,
  "error": "Content Too Large",
  "message": "Uploaded files exceed the maximum allowed size of 100MB.",
  "path": "/api/v1/drawing"
}

MigrationType

Django is offered from PostgreSQL 15, MySQL 8.4 and MariaDB 11.4 upwards.

DatabaseType and versions

Limits

• 100 MB per upload, 2000 parts (files and form fields together).
• 120 seconds per drawing; 10 minutes maximum wait in the queue.
• Diagram links expire after one hour.
• The service is free and unauthenticated while in early access; please poll no more often than every two seconds and keep one userId per project.

Idempotency and retries

The Request-Id header makes POST /drawing idempotent: the same id always maps to the same job, whatever else the request holds. Derive it from something stable, such as a CI run id, when you want a retried pipeline step to pick up the drawing it already queued. Use a fresh UUID when you want a new drawing of changed files.