Skip to main content
API docs by Redocly

dbdiagram Public API (1.0.0)

Download OpenAPI specification:Download

Support: [email protected]

Introduction

API access is currently in Beta and only available if you have a paid plan.

Using these APIs, you are able to programmatically work with dbdiagram. For example:

  • You can programmatically CRUD the diagram.
  • Generate an embed link for a specific diagram. This is useful especially if you need to attach the diagram into your documents, blogs and websites.

Authorization

  • API tokens are managed at the workspace level, granting access to all diagrams within the workspace.
  • Workspace owners can generate new tokens via the "API Tokens" tab in the workspace window.
  • API tokens should be securely held within the user's environment to avoid leaking the key.

Errors

HTTP Code Description
200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable due to missing request parameter or wrong request structure.
401 - Unauthorized No valid API key provided.
403 - Forbidden The API Key owner does not have permission to perform the request.
404 - Not Found The requested resource does not exist or cannot found.
429 - Too Many Requests Too many requests were sent.
500 - Internal Error Something went wrong on dbdiagram side (rarely).

Rate-Limiting

Overview

To prevent DDoS attacks, every API request should go through our rate limit layer which will throttle the request if a user exceeds limit quotas. The rate limit is based on user and endpoint, quotas (per time frame) which maybe different for each endpoint are divided by levels as the table below:

Level Quota Note
Level 1 120 requests / minute At least every API request is this level
Level 2 60 requests / minute Request requires a lot of resource
Level 3 20 requests / minute Request that heavily affect our server's resources

Return Header And Status Code

If a request is blocked because of it exceed the limit quota, status code is set to 429: Too Many Requests.

Every API request's response header contains the following fields:

  • RateLimit-Limit: your_limit_quota_of_endpoint
  • RateLimit-Remaining: remaining_requests_until_reset
  • RateLimit-Reset: next_reset_time
  • Retry-After: next_reset_time(only available when status code is 429)

APIToken

Security Scheme Type: API Key
Header parameter name: dbdiagram-access-token

Diagram

Operations to manage diagrams

Retrieve a list of diagrams

Authorizations:
APIToken

Responses

Request samples 

curl --location 'https://api.dbdiagram.io/v1/diagrams' \
--header 'dbdiagram-access-token: YOUR_API_TOKEN'

Response samples

Content type
application/json
[
  • {
    }
]

Create a new diagram

Authorizations:
APIToken
Request Body schema: application/json
name
string

The diagram's name

content
required
string

The DBML content

Responses

Request samples

Content type
application/json
{
  • "name": "Sample Diagram",
  • "content": "// Use DBML to define your database structure\n// Docs: https://dbml.dbdiagram.io/docs\n\nTable follows {\n following_user_id integer\n followed_user_id integer\n created_at timestamp\n}\n\nTable users [headercolor: #79AD51] {\n id integer [primary key]\n username varchar\n role varchar\n created_at timestamp\n}\n\nTable posts [headercolor: #DE65C3] {\n id integer [primary key]\n title varchar\n body text [note: 'Content of the post']\n user_id integer\n status varchar\n created_at timestamp\n}\n\nRef: posts.user_id > users.id // many-to-one\n\nRef: users.id < follows.following_user_id\n\nRef: users.id < follows.followed_user_id\n"
}

Response samples

Content type
application/json
Example

Personal workspace does not have workspaceId field

{
  • "_id": "664447d8dc6e320126b7679f",
  • "name": "Sample Diagram",
  • "content": "// Use DBML to define your database structure\n// Docs: https://dbml.dbdiagram.io/docs\n\nTable follows {\n following_user_id integer\n followed_user_id integer\n created_at timestamp\n}\n\nTable users [headercolor: #79AD51] {\n id integer [primary key]\n username varchar\n role varchar\n created_at timestamp\n}\n\nTable posts [headercolor: #DE65C3] {\n id integer [primary key]\n title varchar\n body text [note: 'Content of the post']\n user_id integer\n status varchar\n created_at timestamp\n}\n\nRef: posts.user_id > users.id // many-to-one\n\nRef: users.id < follows.following_user_id\n\nRef: users.id < follows.followed_user_id\n",
  • "detailLevel": "All",
  • "userid": "661601d0a5223d95b7f4aa53",
  • "createdAt": "2022-02-01T07:00:00.000Z",
  • "updatedAt": "2022-02-01T07:00:00.000Z"
}

Retrieve a specific diagram by ID

Authorizations:
APIToken
path Parameters
diagramId
required
string <ObjectId>
Example: 664d69b5f994a43a6264b553

ID of the diagram

Responses

Request samples 

curl --location 'https://api.dbdiagram.io/v1/diagrams/:diagramId' \
--header 'dbdiagram-access-token: YOUR_API_TOKEN'

Response samples

Content type
application/json
{
  • "_id": "664447d8dc6e320126b7679f",
  • "name": "Sample Diagram",
  • "content": "// Use DBML to define your database structure\n// Docs: https://dbml.dbdiagram.io/docs\n\nTable follows {\n following_user_id integer\n followed_user_id integer\n created_at timestamp\n}\n\nTable users [headercolor: #79AD51] {\n id integer [primary key]\n username varchar\n role varchar\n created_at timestamp\n}\n\nTable posts [headercolor: #DE65C3] {\n id integer [primary key]\n title varchar\n body text [note: 'Content of the post']\n user_id integer\n status varchar\n created_at timestamp\n}\n\nRef: posts.user_id > users.id // many-to-one\n\nRef: users.id < follows.following_user_id\n\nRef: users.id < follows.followed_user_id\n",
  • "detailLevel": "All",
  • "userid": "661601d0a5223d95b7f4aa53",
  • "workspaceId": "6646cc0af8d989b3142b7f32",
  • "diagram": {
    },
  • "tableGroups": [
    ],
  • "stickyNoteLayouts": [
    ],
  • "referencePaths": [
    ],
  • "lastPublishedDbdocsProject": { },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update a diagram by ID

Simply provide the name or content (DBML - JSON escaped) when updating the diagram. The omitted visualization data & settings (such as table positions, sticky note layouts, etc.) will be retained.

Authorizations:
APIToken
path Parameters
diagramId
required
string <ObjectId>
Example: 664d69b5f994a43a6264b553

ID of the diagram

Request Body schema: application/json
name
string

The diagram's name

content
string

The DBML content

Responses

Request samples

Content type
application/json
{
  • "name": "Sample Diagram",
  • "content": "// Use DBML to define your database structure\n// Docs: https://dbml.dbdiagram.io/docs\n\nTable follows {\n following_user_id integer\n followed_user_id integer\n created_at timestamp\n}\n\nTable users [headercolor: #79AD51] {\n id integer [primary key]\n username varchar\n role varchar\n created_at timestamp\n}\n\nTable posts [headercolor: #DE65C3] {\n id integer [primary key]\n title varchar\n body text [note: 'Content of the post']\n user_id integer\n status varchar\n created_at timestamp\n}\n\nRef: posts.user_id > users.id // many-to-one\n\nRef: users.id < follows.following_user_id\n\nRef: users.id < follows.followed_user_id\n"
}

Response samples

Content type
application/json
{
  • "_id": "664447d8dc6e320126b7679f",
  • "name": "Sample Diagram",
  • "content": "// Use DBML to define your database structure\n// Docs: https://dbml.dbdiagram.io/docs\n\nTable follows {\n following_user_id integer\n followed_user_id integer\n created_at timestamp\n}\n\nTable users [headercolor: #79AD51] {\n id integer [primary key]\n username varchar\n role varchar\n created_at timestamp\n}\n\nTable posts [headercolor: #DE65C3] {\n id integer [primary key]\n title varchar\n body text [note: 'Content of the post']\n user_id integer\n status varchar\n created_at timestamp\n}\n\nRef: posts.user_id > users.id // many-to-one\n\nRef: users.id < follows.following_user_id\n\nRef: users.id < follows.followed_user_id\n",
  • "detailLevel": "All",
  • "userid": "661601d0a5223d95b7f4aa53",
  • "workspaceId": "6646cc0af8d989b3142b7f32",
  • "diagram": {
    },
  • "tableGroups": [
    ],
  • "stickyNoteLayouts": [
    ],
  • "referencePaths": [
    ],
  • "lastPublishedDbdocsProject": { },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Delete a diagram by ID

Authorizations:
APIToken
path Parameters
diagramId
required
string <ObjectId>
Example: 664d69b5f994a43a6264b553

ID of the diagram

Responses

Request samples 

curl --location --request DELETE 'https://api.dbdiagram.io/v1/diagrams/:diagramId' \
--header 'dbdiagram-access-token: YOUR_API_TOKEN'

Response samples

Content type
application/json
"Diagram deleted successfully"

Retrieve a specific embed_link by diagramId

Authorizations:
APIToken
path Parameters
diagramId
required
string <ObjectId>
Example: 664d69b5f994a43a6264b553

ID of the diagram

Responses

Request samples 

curl --location 'https://api.dbdiagram.io/v1/embed_link/:diagramId' \
--header 'dbdiagram-access-token: YOUR_API_TOKEN'

Response samples

Content type
application/json
{
  • "_id": "664d89ff25ea4653266055f5",
  • "diagramId": "664447d8dc6e320126b7679f",
  • "url": "https://dbdiagram.io/e/:diagramId/:embedLinkId",
  • "darkMode": false,
  • "highlight": false,
  • "detailLevel": "All",
  • "enabled": false,
  • "lastView": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Create embed_link by diagramId

Authorizations:
APIToken
path Parameters
diagramId
required
string <ObjectId>
Example: 664d69b5f994a43a6264b553

ID of the diagram

Request Body schema: application/json
detailLevel
string
Default: "All"
Enum: "All" "Keys" "Tables"

Define the diagram detail level

darkMode
boolean
Default: false

Set to true to enable dark mode

highlight
boolean
Default: false

Set to true to highlight relationships

enabled
boolean
Default: false

Set to true to enable the embed link

Responses

Request samples

Content type
application/json
{
  • "detailLevel": "All",
  • "darkMode": false,
  • "highlight": false,
  • "enabled": false
}

Response samples

Content type
application/json
{
  • "_id": "664d89ff25ea4653266055f5",
  • "diagramId": "664447d8dc6e320126b7679f",
  • "url": "https://dbdiagram.io/e/:diagramId/:embedLinkId",
  • "darkMode": false,
  • "highlight": false,
  • "detailLevel": "All",
  • "enabled": false,
  • "lastView": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update an embed_link by diagramId

Authorizations:
APIToken
path Parameters
diagramId
required
string <ObjectId>
Example: 664d69b5f994a43a6264b553

ID of the diagram

Request Body schema: application/json
detailLevel
string
Default: "All"
Enum: "All" "Keys" "Tables"

Define the diagram detail level

darkMode
boolean
Default: false

Set to true to enable dark mode

highlight
boolean
Default: false

Set to true to highlight relationships

enabled
boolean
Default: false

Set to true to enable the embed link

Responses

Request samples

Content type
application/json
{
  • "detailLevel": "All",
  • "darkMode": false,
  • "highlight": false,
  • "enabled": false
}

Response samples

Content type
application/json
{
  • "_id": "664d89ff25ea4653266055f5",
  • "diagramId": "664447d8dc6e320126b7679f",
  • "url": "https://dbdiagram.io/e/:diagramId/:embedLinkId",
  • "darkMode": false,
  • "highlight": false,
  • "detailLevel": "All",
  • "enabled": false,
  • "lastView": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Delete a embed_link by diagramId

Authorizations:
APIToken
path Parameters
diagramId
required
string <ObjectId>
Example: 664d69b5f994a43a6264b553

ID of the diagram

Responses

Request samples 

curl --location --request DELETE 'https://api.dbdiagram.io/v1/embed_link/:diagramId' \
--header 'dbdiagram-access-token: YOUR_API_TOKEN'

Response samples

Content type
application/json
"Embed Link deleted successfully"

The Diagram Model

_id
required
string <ObjectId>

The diagram's id

name
required
string

The diagram's name

content
required
string

The DBML content

detailLevel
required
string
Default: "All"
Enum: "All" "Keys" "Tables"

Define the diagram detail level

userid
required
string <ObjectId>

id of the diagram's owner

workspaceId
string or null <ObjectId>

id of the diagram's team workspace (team plan). Personal workspace does not have this field.

diagram
object or null

Tables's position

tableGroups
object or null

Table groups's collapse state

stickyNoteLayouts
object or null

Sticky notes's size and position

referencePaths
object or null

Relationships's custom path

lastPublishedDbdocsProject
object or null

The last published dbdocs project

createdAt
required
string <date-time>

Created time

updatedAt
required
string <date-time>

Last updated time

{
  • "_id": "664447d8dc6e320126b7679f",
  • "name": "Sample Diagram",
  • "content": "// Use DBML to define your database structure\n// Docs: https://dbml.dbdiagram.io/docs\n\nTable follows {\n following_user_id integer\n followed_user_id integer\n created_at timestamp\n}\n\nTable users [headercolor: #79AD51] {\n id integer [primary key]\n username varchar\n role varchar\n created_at timestamp\n}\n\nTable posts [headercolor: #DE65C3] {\n id integer [primary key]\n title varchar\n body text [note: 'Content of the post']\n user_id integer\n status varchar\n created_at timestamp\n}\n\nRef: posts.user_id > users.id // many-to-one\n\nRef: users.id < follows.following_user_id\n\nRef: users.id < follows.followed_user_id\n",
  • "detailLevel": "All",
  • "userid": "661601d0a5223d95b7f4aa53",
  • "workspaceId": "6646cc0af8d989b3142b7f32",
  • "diagram": {
    },
  • "tableGroups": [
    ],
  • "stickyNoteLayouts": [
    ],
  • "referencePaths": [
    ],
  • "lastPublishedDbdocsProject": { },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}