dbdiagram Public API | dbdiagram Docs
# 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
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)*