openapi: 3.0.3
servers:
  - url: https://api.dbdiagram.io/v1
    description: Production server
security:
  - APIToken: []
info:
  version: 1.0.0
  title: dbdiagram Public API
  contact:
    name: Support
    email: dbdiagram@holistics.io
  description: >
    # 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](https://docs.dbdiagram.io/embedding) 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](https://docs.dbdiagram.io/workspaces) 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

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


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


    <div class="api-docs-table">
      <table>
        <tr>
          <th>Level</th>
          <th>Quota</th>
          <th>Note</th>
        </tr>
        <tr>
          <td>Level 1</td>
          <td>120 requests / minute</td>
          <td>At least every API request is this level</td>
        </tr>
        <tr>
          <td>Level 2</td>
          <td>60 requests / minute</td>
          <td>Request requires a lot of resource</td>
        </tr>
        <tr>
          <td>Level 3</td>
          <td>20 requests / minute</td>
          <td>Request that heavily affect our server's resources</td>
        </tr>
      </table>
    </div>


    ## 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)*


    <SecurityDefinitions />
tags:
  - name: diagrams
    x-displayName: Diagram
    description: Operations to manage diagrams
  - name: embed_link
    x-displayName: Embed Link
    description: Operations to manage embed_link
  - name: diagram_model
    x-displayName: The Diagram Model
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Diagram" />
  - name: embed_link_model
    x-displayName: The Embed Link Model
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/EmbedLink" />
x-tagGroups:
  - name: Endpoints
    tags:
      - diagrams
      - embed_link
  - name: Models
    tags:
      - diagram_model
      - embed_link_model
paths:
  /diagrams:
    get:
      summary: Retrieve a list of diagrams
      tags:
        - diagrams
      operationId: getDiagramList
      x-codeSamples:
        - lang: Shell
          source: |
            curl --location 'https://api.dbdiagram.io/v1/diagrams' \
            --header 'dbdiagram-access-token: YOUR_API_TOKEN'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Diagram'
    post:
      summary: Create a new diagram
      tags:
        - diagrams
      operationId: createNewDiagram
      requestBody:
        content:
          application/json:
            schema:
              required:
                - content
              properties:
                name:
                  $ref: '#/components/schemas/Diagram/properties/name'
                content:
                  $ref: '#/components/schemas/Diagram/properties/content'
      x-codeSamples:
        - lang: Shell
          source: >
            curl --location --request POST
            'https://api.dbdiagram.io/v1/diagrams' \

            --header 'dbdiagram-access-token: YOUR_API_TOKEN' \

            --header 'Content-Type: application/json' \

            --data '{
              "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"
            }'
      responses:
        '200':
          description: Diagram created successfully
          content:
            application/json:
              schema:
                required:
                  - _id
                  - name
                  - content
                  - detailLevel
                  - userid
                  - createdAt
                  - updatedAt
                properties:
                  _id:
                    $ref: '#/components/schemas/Diagram/properties/_id'
                  name:
                    $ref: '#/components/schemas/Diagram/properties/name'
                  content:
                    $ref: '#/components/schemas/Diagram/properties/content'
                  detailLevel:
                    $ref: '#/components/schemas/Diagram/properties/detailLevel'
                  userid:
                    $ref: '#/components/schemas/Diagram/properties/userid'
                  workspaceId:
                    $ref: '#/components/schemas/Diagram/properties/workspaceId'
                  createdAt:
                    $ref: '#/components/schemas/Diagram/properties/createdAt'
                  updatedAt:
                    $ref: '#/components/schemas/Diagram/properties/updatedAt'
              examples:
                personal:
                  summary: Personal workspace
                  description: Personal workspace does not have `workspaceId` field
                  value:
                    _id: 664447d8dc6e320126b7679f
                    name: Sample Diagram
                    content: |
                      // Use DBML to define your database structure
                      // Docs: https://dbml.dbdiagram.io/docs

                      Table follows {
                        following_user_id integer
                        followed_user_id integer
                        created_at timestamp
                      }

                      Table users [headercolor: #79AD51] {
                        id integer [primary key]
                        username varchar
                        role varchar
                        created_at timestamp
                      }

                      Table posts [headercolor: #DE65C3] {
                        id integer [primary key]
                        title varchar
                        body text [note: 'Content of the post']
                        user_id integer
                        status varchar
                        created_at timestamp
                      }

                      Ref: posts.user_id > users.id // many-to-one

                      Ref: users.id < follows.following_user_id

                      Ref: users.id < follows.followed_user_id
                    detailLevel: All
                    userid: 661601d0a5223d95b7f4aa53
                    createdAt: '2022-02-01T07:00:00.000Z'
                    updatedAt: '2022-02-01T07:00:00.000Z'
                team:
                  summary: Team workspace
                  description: Team workspace has `workspaceId` field
                  value:
                    _id: 664447d8dc6e320126b7679f
                    name: Sample Diagram
                    content: |
                      // Use DBML to define your database structure
                      // Docs: https://dbml.dbdiagram.io/docs

                      Table follows {
                        following_user_id integer
                        followed_user_id integer
                        created_at timestamp
                      }

                      Table users [headercolor: #79AD51] {
                        id integer [primary key]
                        username varchar
                        role varchar
                        created_at timestamp
                      }

                      Table posts [headercolor: #DE65C3] {
                        id integer [primary key]
                        title varchar
                        body text [note: 'Content of the post']
                        user_id integer
                        status varchar
                        created_at timestamp
                      }

                      Ref: posts.user_id > users.id // many-to-one

                      Ref: users.id < follows.following_user_id

                      Ref: users.id < follows.followed_user_id
                    detailLevel: All
                    userid: 661601d0a5223d95b7f4aa53
                    workspaceId: 6646cc0af8d989b3142b7f32
                    createdAt: '2022-02-01T07:00:00.000Z'
                    updatedAt: '2022-02-01T07:00:00.000Z'
  /diagrams/{diagramId}:
    get:
      summary: Retrieve a specific diagram by ID
      tags:
        - diagrams
      operationId: getDiagramById
      parameters:
        - $ref: '#/components/parameters/DiagramId'
      x-codeSamples:
        - lang: Shell
          source: |
            curl --location 'https://api.dbdiagram.io/v1/diagrams/:diagramId' \
            --header 'dbdiagram-access-token: YOUR_API_TOKEN'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Diagram'
    put:
      summary: Update a diagram by ID
      description: >
        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.
      tags:
        - diagrams
      operationId: updateDiagramById
      parameters:
        - $ref: '#/components/parameters/DiagramId'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                name:
                  $ref: '#/components/schemas/Diagram/properties/name'
                content:
                  $ref: '#/components/schemas/Diagram/properties/content'
      x-codeSamples:
        - lang: Shell
          source: >
            curl --location --request PUT
            'https://api.dbdiagram.io/v1/diagrams/:diagramId' \

            --header 'dbdiagram-access-token: YOUR_API_TOKEN' \

            --header 'Content-Type: application/json' \

            --data '{
              "name": "Updated 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"
            }'
      responses:
        '200':
          description: Diagram updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Diagram'
    delete:
      summary: Delete a diagram by ID
      tags:
        - diagrams
      operationId: deleteDiagramById
      parameters:
        - $ref: '#/components/parameters/DiagramId'
      x-codeSamples:
        - lang: Shell
          source: >
            curl --location --request DELETE
            'https://api.dbdiagram.io/v1/diagrams/:diagramId' \

            --header 'dbdiagram-access-token: YOUR_API_TOKEN'
      responses:
        '200':
          description: Diagram deleted successfully
          content:
            application/json:
              schema:
                type: string
              example: Diagram deleted successfully
  /embed_link/{diagramId}:
    get:
      summary: Retrieve a specific embed_link by diagramId
      tags:
        - embed_link
      operationId: getEmbedLinkByDiagramId
      parameters:
        - $ref: '#/components/parameters/DiagramId'
      x-codeSamples:
        - lang: Shell
          source: >
            curl --location 'https://api.dbdiagram.io/v1/embed_link/:diagramId'
            \

            --header 'dbdiagram-access-token: YOUR_API_TOKEN'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbedLink'
    post:
      summary: Create embed_link by diagramId
      tags:
        - embed_link
      operationId: createEmbedLinkByDiagramId
      parameters:
        - $ref: '#/components/parameters/DiagramId'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                detailLevel:
                  $ref: '#/components/schemas/EmbedLink/properties/detailLevel'
                darkMode:
                  $ref: '#/components/schemas/EmbedLink/properties/darkMode'
                highlight:
                  $ref: '#/components/schemas/EmbedLink/properties/highlight'
                enabled:
                  $ref: '#/components/schemas/EmbedLink/properties/enabled'
      x-codeSamples:
        - lang: Shell
          source: >
            curl --location --request POST
            'https://api.dbdiagram.io/v1/embed_link/:diagramId' \

            --header 'dbdiagram-access-token: YOUR_API_TOKEN' \

            --header 'Content-Type: application/json' \

            --data '{
              "detailLevel": "All",
              "darkMode": "false",
              "highlight": "false",
              "enabled": "true"
            }'
      responses:
        '200':
          description: Embed link created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbedLink'
    put:
      summary: Update an embed_link by diagramId
      tags:
        - embed_link
      operationId: updateEmbedLinkByDiagramId
      parameters:
        - $ref: '#/components/parameters/DiagramId'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                detailLevel:
                  $ref: '#/components/schemas/EmbedLink/properties/detailLevel'
                darkMode:
                  $ref: '#/components/schemas/EmbedLink/properties/darkMode'
                highlight:
                  $ref: '#/components/schemas/EmbedLink/properties/highlight'
                enabled:
                  $ref: '#/components/schemas/EmbedLink/properties/enabled'
      x-codeSamples:
        - lang: Shell
          source: >
            curl --location --request PUT
            'https://api.dbdiagram.io/v1/embed_link/:diagramId' \

            --header 'dbdiagram-access-token: YOUR_API_TOKEN' \

            --header 'Content-Type: application/json' \

            --data '{
              "detailLevel": "Keys",
              "darkMode": "true",
              "highlight": "true",
              "enabled": "true"
            }'
      responses:
        '200':
          description: Embed Link updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbedLink'
    delete:
      summary: Delete a embed_link by diagramId
      tags:
        - embed_link
      operationId: deleteEmbedLinkByDiagramId
      parameters:
        - $ref: '#/components/parameters/DiagramId'
      x-codeSamples:
        - lang: Shell
          source: >
            curl --location --request DELETE
            'https://api.dbdiagram.io/v1/embed_link/:diagramId' \

            --header 'dbdiagram-access-token: YOUR_API_TOKEN'
      responses:
        '200':
          description: Embed Link deleted successfully
          content:
            application/json:
              schema:
                type: string
              example: Embed Link deleted successfully
components:
  schemas:
    Diagram:
      type: object
      required:
        - _id
        - content
        - name
        - detailLevel
        - userid
        - createdAt
        - updatedAt
      properties:
        _id:
          type: string
          format: ObjectId
          description: The diagram's id
          example: 664447d8dc6e320126b7679f
        name:
          type: string
          description: The diagram's name
          example: Sample Diagram
        content:
          type: string
          description: The DBML content
          example: |
            // Use DBML to define your database structure
            // Docs: https://dbml.dbdiagram.io/docs

            Table follows {
              following_user_id integer
              followed_user_id integer
              created_at timestamp
            }

            Table users [headercolor: #79AD51] {
              id integer [primary key]
              username varchar
              role varchar
              created_at timestamp
            }

            Table posts [headercolor: #DE65C3] {
              id integer [primary key]
              title varchar
              body text [note: 'Content of the post']
              user_id integer
              status varchar
              created_at timestamp
            }

            Ref: posts.user_id > users.id // many-to-one

            Ref: users.id < follows.following_user_id

            Ref: users.id < follows.followed_user_id
        detailLevel:
          type: string
          description: Define the diagram detail level
          default: All
          enum:
            - All
            - Keys
            - Tables
        userid:
          type: string
          format: ObjectId
          description: id of the diagram's owner
          example: 661601d0a5223d95b7f4aa53
        workspaceId:
          type: string
          format: ObjectId
          description: >-
            id of the diagram's team workspace (team plan). Personal workspace
            does not have this field.
          x-nullable: true
          example: 6646cc0af8d989b3142b7f32
        diagram:
          type: object
          description: Tables's position
          x-nullable: true
          example:
            tables: &ref_3
              - name: follows
                schemaName: public
                x: -394
                'y': -385
              - name: users
                schemaName: public
                x: -394
                'y': -136
              - name: posts
                schemaName: public
                x: 439.80029296875
                'y': -440
              - name: test
                schemaName: public
                x: -419
                'y': 193
        tableGroups:
          type: object
          description: Table groups's collapse state
          x-nullable: true
          example: &ref_2
            - name: people
              isCollapsed: false
        stickyNoteLayouts:
          type: object
          description: Sticky notes's size and position
          x-nullable: true
          example: &ref_0
            - name: sticky_notes
              x: 249.8002929687508
              'y': 193
              width: 399.5151367187492
              height: 160
        referencePaths:
          type: object
          description: Relationships's custom path
          x-nullable: true
          example: &ref_1
            - firstFieldNames:
                - user_id
              firstTableName: posts
              firstSchemaName: public
              firstRelation: '*'
              secondFieldNames:
                - id
              secondTableName: users
              secondSchemaName: public
              secondRelation: '1'
              firstEndpointSide: null
              secondEndpointSide: null
              checkPoints: []
            - firstFieldNames:
                - id
              firstTableName: users
              firstSchemaName: public
              firstRelation: '1'
              secondFieldNames:
                - following_user_id
              secondTableName: follows
              secondSchemaName: public
              secondRelation: '*'
              firstEndpointSide: null
              secondEndpointSide: null
              checkPoints: []
            - firstFieldNames:
                - id
              firstTableName: users
              firstSchemaName: public
              firstRelation: '1'
              secondFieldNames:
                - followed_user_id
              secondTableName: follows
              secondSchemaName: public
              secondRelation: '*'
              firstEndpointSide: null
              secondEndpointSide: null
              checkPoints: []
            - firstFieldNames:
                - id
              firstTableName: users
              firstSchemaName: public
              firstRelation: '1'
              secondFieldNames:
                - user_id
              secondTableName: test
              secondSchemaName: public
              secondRelation: '*'
              firstEndpointSide: null
              secondEndpointSide: null
              checkPoints: []
        lastPublishedDbdocsProject:
          type: object
          description: The last published dbdocs project
          x-nullable: true
        createdAt:
          type: string
          format: date-time
          description: Created time
        updatedAt:
          type: string
          format: date-time
          description: Last updated time
      additionalProperties: false
    EmbedLink:
      type: object
      required:
        - _id
        - diagramId
        - url
        - darkMode
        - highlight
        - detailLevel
        - enabled
        - createdAt
        - updatedAt
      properties:
        _id:
          type: string
          format: ObjectId
          description: The embed link's id
          example: 664d89ff25ea4653266055f5
        diagramId:
          type: string
          format: ObjectId
          description: id of the embed link's diagram
          example: 664447d8dc6e320126b7679f
        url:
          type: string
          format: url
          description: The embed link's url value
          example: https://dbdiagram.io/e/:diagramId/:embedLinkId
        darkMode:
          type: boolean
          default: false
          description: Set to `true` to enable dark mode
        highlight:
          type: boolean
          default: false
          description: Set to `true` to highlight relationships
        detailLevel:
          $ref: '#/components/schemas/Diagram/properties/detailLevel'
        enabled:
          type: boolean
          default: false
          description: Set to `true` to enable the embed link
        lastView:
          type: string
          format: date-time
          x-nullable: true
          description: Last time the embed link is viewed
        createdAt:
          type: string
          format: date-time
          description: Created time
        updatedAt:
          type: string
          format: date-time
          description: Last updated time
      additionalProperties: false
  parameters:
    DiagramId:
      name: diagramId
      in: path
      required: true
      description: ID of the diagram
      schema:
        type: string
        format: ObjectId
        example: 664d69b5f994a43a6264b553
  examples:
    personalPostDiagramRes:
      _id: 664447d8dc6e320126b7679f
      name: Sample Diagram
      content: |
        // Use DBML to define your database structure
        // Docs: https://dbml.dbdiagram.io/docs

        Table follows {
          following_user_id integer
          followed_user_id integer
          created_at timestamp
        }

        Table users [headercolor: #79AD51] {
          id integer [primary key]
          username varchar
          role varchar
          created_at timestamp
        }

        Table posts [headercolor: #DE65C3] {
          id integer [primary key]
          title varchar
          body text [note: 'Content of the post']
          user_id integer
          status varchar
          created_at timestamp
        }

        Ref: posts.user_id > users.id // many-to-one

        Ref: users.id < follows.following_user_id

        Ref: users.id < follows.followed_user_id
      detailLevel: All
      userid: 661601d0a5223d95b7f4aa53
      createdAt: '2022-02-01T07:00:00.000Z'
      updatedAt: '2022-02-01T07:00:00.000Z'
    teamPostDiagramRes:
      _id: 664447d8dc6e320126b7679f
      name: Sample Diagram
      content: |
        // Use DBML to define your database structure
        // Docs: https://dbml.dbdiagram.io/docs

        Table follows {
          following_user_id integer
          followed_user_id integer
          created_at timestamp
        }

        Table users [headercolor: #79AD51] {
          id integer [primary key]
          username varchar
          role varchar
          created_at timestamp
        }

        Table posts [headercolor: #DE65C3] {
          id integer [primary key]
          title varchar
          body text [note: 'Content of the post']
          user_id integer
          status varchar
          created_at timestamp
        }

        Ref: posts.user_id > users.id // many-to-one

        Ref: users.id < follows.following_user_id

        Ref: users.id < follows.followed_user_id
      detailLevel: All
      userid: 661601d0a5223d95b7f4aa53
      workspaceId: 6646cc0af8d989b3142b7f32
      createdAt: '2022-02-01T07:00:00.000Z'
      updatedAt: '2022-02-01T07:00:00.000Z'
    DBML: |
      // Use DBML to define your database structure
      // Docs: https://dbml.dbdiagram.io/docs

      Table follows {
        following_user_id integer
        followed_user_id integer
        created_at timestamp
      }

      Table users [headercolor: #79AD51] {
        id integer [primary key]
        username varchar
        role varchar
        created_at timestamp
      }

      Table posts [headercolor: #DE65C3] {
        id integer [primary key]
        title varchar
        body text [note: 'Content of the post']
        user_id integer
        status varchar
        created_at timestamp
      }

      Ref: posts.user_id > users.id // many-to-one

      Ref: users.id < follows.following_user_id

      Ref: users.id < follows.followed_user_id
    StickyNotesLayouts: *ref_0
    ReferencePaths: *ref_1
    TableGroups: *ref_2
    Tables:
      tables: *ref_3
  securitySchemes:
    APIToken:
      name: dbdiagram-access-token
      type: apiKey
      in: header