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