# Introduction
This API allows resellers to manage their resources in a simple, programmatic way using HTTP requests.
# Conventions
## Requests
The API supports different methods depending on the required action.
| Method | Description
| --- | ---
| GET | Retrieve resources in a collection or get a single resource.
Getters will never have any effect on the queried resources.
| POST | Create a new resource in a collection.
| PUT | Update an existing resource with its new representation.
| DELETE | Delete an existing resource.
## HTTP status codes
The API will reply with different HTTP statuscodes:
| StatusCode | Description
| --- | ---
| 200 OK | The requests was processed and you receive data as a result.
| 201 CREATED | The resource has been created. Either the Location header contains a link to the created resource, or links are being returned in the response body. The applied method will be indicated in the documentation.
| 202 ACCEPTED | The request has been validated and accepted. Because we need to do some background processing prior to returning the result, we cannot send back a useful representation.
| 204 NOCONTENT | The request has been processed, but no details can be returned.
| 400 BADREQUEST | Your request is malformed.
| 401 UNAUTHORIZED | You are not authorized. Follow the instructions in the Authorization documentation.
| 403 FORBIDDEN | Access to the resource or operation is not allowed.
| 404 NOTFOUND | The resource cannot be found.
| 410 GONE | The resource is permanently no longer available.
| 429 TOOMANYREQUESTS | The ratelimit has been exceeded. Please refer to the documentation on rate limiting for more details.
| 500 INTERNALSERVERERROR | An error occurred during the processing of the request. The error is unexpected and most likely due to a bug in the api.
In the event of a problem, the body of the response will usually contain an errorcode and errormessage.
In rare cases additional details about the error are reported.
Errorcodes 400-499 are considered to be client errors and indicate that there was an issue with the request.
We will not take any action besides monitoring.
Errorcodes 500-599 are considered to be server errors. The errors are monitored AND action will be taken to resolve the error.
## Formatting
Snake casing is applied on resources and query parameters.
The API is strictly returning JSON. No other formats are supported.
Datetimes are returned in ISO-8601 format.
## Pagination
Pagination is on by default on collections and is controlled by specifying *skip* and *take* parameters.
**Skip** indicates the number of results to skip and where to start the new take.
**Take** indicates the number of records to return. The returned number of items can be smaller than the requested take.
Paged results will have headers with useful information regarding the paging.
| Header | Description
| --- | ---
| X-Paging-Skipped | The number of results that have been skipped.
| X-Paging-Take | The number of items in the current take. The number might differ from the requested take. It represents the actual number of items returned in the response.
| X-Paging-TotalResults | The total number of results regardless of paging.
## Rate limiting
The number of requests per interval is limited. Detailed information on the rate limiting can be found in specific headers which will be sent on each request.
| Header | Description
| --- | ---
| X-RateLimit-Limit | The number of requests that can be made in a specific time interval.
| X-RateLimit-Usage | The number of requests already made in the current time interval.
| X-RateLimit-Remaining | The number of requests remaining until the reset.
| X-RateLimit-Reset | The number of seconds until the reset.
After the reset you are allowed to make as many requests as specified by the X-RateLimit-Limit header.
| Retry-After | The number of seconds you have to wait until you can make new requests.
This header is only present when the rate limit has been reached. It is identical to X-RateLimit-Reset.
When the ratelimit has been reached, all requests will return with a HTTP statuscode 429 and ReasonPhrase '*Too many requests, retry later.*'.
# Authentication
The Api uses HMAC authentication.
Hash-based message authentication code (HMAC) is a mechanism for calculating a message authentication code involving a hash function in combination with a secret key.
Both the integrity and the authenticity of the message are verified this way.
## Steps to generate the HMAC
1. Get your api key and secret from your controlpanel.
It is absolutely vital that the secret is never exposed. Once the secret is out, anyone would be able to generate hmacs to impersonate you.
In case your secret is compromised, you can generate a new api key and secret on your controlpanel.
2. Construct the input value for generating the hmac.
Concatenate:apikey, request method, path and querystring information, unix timestamp, nonce and content.
| | Description
| --- | ---
| apikey | The key that is linked to your user.
| request method | lowercased (eg: get, post, delete,...)
| path and querystring information | urlencoding of the lowercased relative path and querystring.
The path **MUST start with the api version (/v2)**.
The hexadecimal codes (percent encoding) MUST be uppercased.
| unix timestamp | the unix timestamp in **seconds**.
| nonce | a unique string for each request. It should be a random string, not related to the request. The nonce (in combination with the unix timestamp) protects you from replay attacks in case anyone was able to intercept a request.
| content | When the request body is not empty, this should be the Base64 encoded Md5 hash of the request body.
An empty body should not be encoded.
3. Hash the concatenated string using your api secret and the SHA-256 algorithm.
4. Base64 encode the result of the hash function. This is the hmac signature you will need to send an authorized request.
## Sending an authorized request
An authorized request can be made by sending the generated HMAC in the authorization header.
A correct authorizationheader uses the hmac authorization scheme and a correctly formatted authorization parameter.
Create the authorization parameter by concatenating:
* apikey
* colon ':'
* generated HMAC signature (see above)
* colon ':'
* nonce (the one used to generate the signature)
* colon ':'
* unix timestamp (the one used to generate the signature)
A sample (illustrated):
* The first line is the string you create to feed to the hashing algorithm.
* The second line is the authorization header that should be sent in the request.
## IP whitelisting
Access is by default restricted for all IP addresses. You need to explicitly whitelist an IP or an IP range in your controlpanel.
# Versioning
Because of breaking contract changes compared to v1, we released v2 of the API.
V1 will still be available, but you are strongly encouraged to migrate to the latest version.
New features will only be available on v2.
# Policy
### Fair use policy
Please respect the rate limits and do not use the api for any purposes of abuse.
All requests are being monitored and logged.
Intentional abuse might result in api key revocation.
# Errors
The API attempts to return appropriate HTTP status codes for every request.
When the status code indicates failure, the API will also provide an error message in most cases.
An error message contains a machine-parseable error code accompanied by a descriptive error text.
The text for an error message might change over time, but codes will stay the same.
[An overview of error codes can be found here](/v2/documentation/errorcodes).
# Change log
[An overview of new changes can be found here](/v2/documentation/changelog).
# Provisioning information
## Terminology
| Term | Definition |
| --- | --- |
| Servicepack | Defines a set of assets that belong together. An example is a hosting package which offers Linux hosting, a domain name, a couple of mailboxes and databases.
It also limits the size of individual assets within the same account. |
| Account | Represents an instance of the servicepack. It contains one or more assets. The number and size of assets is defined by the servicepack. |
| Asset | A manageable service. For example: a mysql database, a linux hosting, a mailbox,...
Some assets are created at the moment when the account is created. Other assets can be created afterwards.
## Common provisioning scenario
**Provisioning of an account with Linux hosting with one MySql database**
*Without a pre-existing account:*
1. Create a new account.
Perform a POST on the accounts route and provide the desired servicepack id and identifier (domain name).
2. Read the Location header from the response and perform a GET of the provided resource (a provisioning job).
3. When the response returns 200(OK), you should repeat the GET operation after a certain interval (Repeat this step).
When the response returns 201(Created), you should read the response body. This will contain links to the created resources.
This will usually hold only one link, but to be futureproof, this has been designed to return a collection.
4. The created resource will point to an account. You now know the account's Id and can continue with the provisioning of a MySql database on this account.
5. Perform a POST on the mysqldatabases route and provide the account id along with other requested information.
6. Read the Location header from the response and perform a GET of the provided resource (a provisioning job).
7. When the response returns 200(OK), you should repeat the GET operation after a certain interval (Repeat this step).
When the response returns 201(Created), you should read the response body. This will contain links to the created resources.
This will usually hold only one link, but to be futureproof, this has been designed to return a collection.
8. The created resource will point to a MySql database resource.
## SSL certificate requests
**Requesting an SSL certificate causes the purchase of a paying product.**
1. A certificate is created by adding an ssl certificate request.
2. Upon statuscode 201 you should query for certificate completion on the resource provided in the location response header.
3. The resource request can respond with different statuscodes:
- 200: the certificate request is ongoing.
Check the validations collection for validation values that are not auto_validated. Those should be set by you system.
Call verify domain validations once all validation values are in place. It might take some time for verification to take place. It is not necessary to call this method more than once. - 303: the certificate request is complete; there is no more certificate request resource available. Check the location header value to retrieve the representation of the resulting ssl certificate.
- 410: the certificate request does not exist anymore, there is no certificate created as a result of the request.
# Introduction The DigitalOcean API allows you to manage Droplets and resources within the DigitalOcean cloud in a simple, programmatic way using conventional HTTP requests. All of the functionality that you are familiar with in the DigitalOcean control panel is also available through the API, allowing you to script the complex actions that your situation requires. The API documentation will start with a general overview about the design and technology that has been implemented, followed by reference information about specific endpoints. ## Requests Any tool that is fluent in HTTP can communicate with the API simply by requesting the correct URI. Requests should be made using the HTTPS protocol so that traffic is encrypted. The interface responds to different methods depending on the action required. |Method|Usage| |--- |--- | |GET|For simple retrieval of information about your account, Droplets, or environment, you should use the GET method. The information you request will be returned to you as a JSON object. The attributes defined by the JSON object can be used to form additional requests. Any request using the GET method is read-only and will not affect any of the objects you are querying.| |DELETE|To destroy a resource and remove it from your account and environment, the DELETE method should be used. This will remove the specified object if it is found. If it is not found, the operation will return a response indicating that the object was not found. This idempotency means that you do not have to check for a resource's availability prior to issuing a delete command, the final state will be the same regardless of its existence.| |PUT|To update the information about a resource in your account, the PUT method is available. Like the DELETE Method, the PUT method is idempotent. It sets the state of the target using the provided values, regardless of their current values. Requests using the PUT method do not need to check the current attributes of the object.| |PATCH|Some resources support partial modification. In these cases, the PATCH method is available. Unlike PUT which generally requires a complete representation of a resource, a PATCH request is is a set of instructions on how to modify a resource updating only specific attributes.| |POST|To create a new object, your request should specify the POST method. The POST request includes all of the attributes necessary to create a new object. When you wish to create a new object, send a POST request to the target endpoint.| |HEAD|Finally, to retrieve metadata information, you should use the HEAD method to get the headers. This returns only the header of what would be returned with an associated GET request. Response headers contain some useful information about your API access and the results that are available for your request. For instance, the headers contain your current rate-limit value and the amount of time available until the limit resets. It also contains metrics about the total number of objects found, pagination information, and the total content length.| ## HTTP Statuses Along with the HTTP methods that the API responds to, it will also return standard HTTP statuses, including error codes. In the event of a problem, the status will contain the error code, while the body of the response will usually contain additional information about the problem that was encountered. In general, if the status returned is in the 200 range, it indicates that the request was fulfilled successfully and that no error was encountered. Return codes in the 400 range typically indicate that there was an issue with the request that was sent. Among other things, this could mean that you did not authenticate correctly, that you are requesting an action that you do not have authorization for, that the object you are requesting does not exist, or that your request is malformed. If you receive a status in the 500 range, this generally indicates a server-side problem. This means that we are having an issue on our end and cannot fulfill your request currently. 400 and 500 level error responses will include a JSON object in their body, including the following attributes: |Name|Type|Description| |--- |--- |--- | |id|string|A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."| |message|string|A message providing additional information about the error, including details to help resolve it when possible.| |request_id|string|Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.| ### Example Error Response ``` HTTP/1.1 403 Forbidden { "id": "forbidden", "message": "You do not have access for the attempted action." } ``` ## Responses When a request is successful, a response body will typically be sent back in the form of a JSON object. An exception to this is when a DELETE request is processed, which will result in a successful HTTP 204 status and an empty response body. Inside of this JSON object, the resource root that was the target of the request will be set as the key. This will be the singular form of the word if the request operated on a single object, and the plural form of the word if a collection was processed. For example, if you send a GET request to `/v2/droplets/$DROPLET_ID` you will get back an object with a key called "`droplet`". However, if you send the GET request to the general collection at `/v2/droplets`, you will get back an object with a key called "`droplets`". The value of these keys will generally be a JSON object for a request on a single object and an array of objects for a request on a collection of objects. ### Response for a Single Object ``` { "droplet": { "name": "example.com" . . . } } ``` ### Response for an Object Collection ``` { "droplets": [ { "name": "example.com" . . . }, { "name": "second.com" . . . } ] } ``` ## Meta In addition to the main resource root, the response may also contain a `meta` object. This object contains information about the response itself. The `meta` object contains a `total` key that is set to the total number of objects returned by the request. This has implications on the `links` object and pagination. The `meta` object will only be displayed when it has a value. Currently, the `meta` object will have a value when a request is made on a collection (like `droplets` or `domains`). ### Sample Meta Object ``` { . . . "meta": { "total": 43 } . . . } ``` ## Links & Pagination The `links` object is returned as part of the response body when pagination is enabled. By default, 20 objects are returned per page. If the response contains 20 objects or fewer, no `links` object will be returned. If the response contains more than 20 objects, the first 20 will be returned along with the `links` object. You can request a different pagination limit or force pagination by appending `?per_page=` to the request with the number of items you would like per page. For instance, to show only two results per page, you could add `?per_page=2` to the end of your query. The maximum number of results per page is 200. The `links` object contains a `pages` object. The `pages` object, in turn, contains keys indicating the relationship of additional pages. The values of these are the URLs of the associated pages. The keys will be one of the following: * **first**: The URI of the first page of results. * **prev**: The URI of the previous sequential page of results. * **next**: The URI of the next sequential page of results. * **last**: The URI of the last page of results. The `pages` object will only include the links that make sense. So for the first page of results, no `first` or `prev` links will ever be set. This convention holds true in other situations where a link would not make sense. ### Sample Links Object ``` { . . . "links": { "pages": { "last": "https://api.digitalocean.com/v2/images?page=2", "next": "https://api.digitalocean.com/v2/images?page=2" } } . . . } ``` ## Rate Limit Requests through the API are rate limited per OAuth token. Current rate limits: * 5,000 requests per hour * 250 requests per minute (5% of the hourly total) Once you exceed either limit, you will be rate limited until the next cycle starts. Space out any requests that you would otherwise issue in bursts for the best results. The rate limiting information is contained within the response headers of each request. The relevant headers are: * **ratelimit-limit**: The number of requests that can be made per hour. * **ratelimit-remaining**: The number of requests that remain before you hit your request limit. See the information below for how the request limits expire. * **ratelimit-reset**: This represents the time when the oldest request will expire. The value is given in [Unix epoch time](http://en.wikipedia.org/wiki/Unix_time). See below for more information about how request limits expire. As long as the `ratelimit-remaining` count is above zero, you will be able to make additional requests. The way that a request expires and is removed from the current limit count is important to understand. Rather than counting all of the requests for an hour and resetting the `ratelimit-remaining` value at the end of the hour, each request instead has its own timer. This means that each request contributes toward the `ratelimit-remaining` count for one complete hour after the request is made. When that request's timer runs out, it is no longer counted towards the request limit. This has implications on the meaning of the `ratelimit-reset` header as well. Because the entire rate limit is not reset at one time, the value of this header is set to the time when the _oldest_ request will expire. Keep this in mind if you see your `ratelimit-reset` value change, but not move an entire hour into the future. If the `ratelimit-remaining` reaches zero, subsequent requests will receive a 429 error code until the request reset has been reached. You can see the format of the response in the examples. **Note:** The following endpoints have special rate limit requirements that are independent of the limits defined above. * Only 12 `POST` requests to the `/v2/floating_ips` endpoint to create Floating IPs can be made per 60 seconds. * Only 10 `GET` requests to the `/v2/account/keys` endpoint to list SSH keys can be made per 60 seconds. * Only 5 requests to any and all `v2/cdn/endpoints` can be made per 10 seconds. This includes `v2/cdn/endpoints`, `v2/cdn/endpoints/$ENDPOINT_ID`, and `v2/cdn/endpoints/$ENDPOINT_ID/cache`. * Only 50 strings within the `files` json struct in the `v2/cdn/endpoints/$ENDPOINT_ID/cache` [payload](https://docs.digitalocean.com/reference/api/api-reference/#operation/cdn_purge_cache) can be requested every 20 seconds. ### Sample Rate Limit Headers ``` . . . ratelimit-limit: 1200 ratelimit-remaining: 1193 rateLimit-reset: 1402425459 . . . ``` ### Sample Rate Exceeded Response ``` 429 Too Many Requests { id: "too_many_requests", message: "API Rate limit exceeded." } ``` ## Curl Examples Throughout this document, some example API requests will be given using the `curl` command. This will allow us to demonstrate the various endpoints in a simple, textual format. These examples assume that you are using a Linux or macOS command line. To run these commands on a Windows machine, you can either use cmd.exe, PowerShell, or WSL: * For cmd.exe, use the `set VAR=VALUE` [syntax](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) to define environment variables, call them with `%VAR%`, then replace all backslashes (`\`) in the examples with carets (`^`). * For PowerShell, use the `$Env:VAR = "VALUE"` [syntax](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7.2) to define environment variables, call them with `$Env:VAR`, then replace `curl` with `curl.exe` and all backslashes (`\`) in the examples with backticks (`` ` ``). * WSL is a compatibility layer that allows you to emulate a Linux terminal on a Windows machine. Install WSL with our [community tutorial](https://www.digitalocean.com/community/tutorials/how-to-install-the-windows-subsystem-for-linux-2-on-microsoft-windows-10), then follow this API documentation normally. The names of account-specific references (like Droplet IDs, for instance) will be represented by variables. For instance, a Droplet ID may be represented by a variable called `$DROPLET_ID`. You can set the associated variables in your environment if you wish to use the examples without modification. The first variable that you should set to get started is your OAuth authorization token. The next section will go over the details of this, but you can set an environmental variable for it now. Generate a token by going to the [Apps & API](https://cloud.digitalocean.com/settings/applications) section of the DigitalOcean control panel. Use an existing token if you have saved one, or generate a new token with the "Generate new token" button. Copy the generated token and use it to set and export the TOKEN variable in your environment as the example shows. You may also wish to set some other variables now or as you go along. For example, you may wish to set the `DROPLET_ID` variable to one of your Droplet IDs since this will be used frequently in the API. If you are following along, make sure you use a Droplet ID that you control so that your commands will execute correctly. If you need access to the headers of a response through `curl`, you can pass the `-i` flag to display the header information along with the body. If you are only interested in the header, you can instead pass the `-I` flag, which will exclude the response body entirely. ### Set and Export your OAuth Token ``` export DIGITALOCEAN_TOKEN=your_token_here ``` ### Set and Export a Variable ``` export DROPLET_ID=1111111 ``` ## Parameters There are two different ways to pass parameters in a request with the API. When passing parameters to create or update an object, parameters should be passed as a JSON object containing the appropriate attribute names and values as key-value pairs. When you use this format, you should specify that you are sending a JSON object in the header. This is done by setting the `Content-Type` header to `application/json`. This ensures that your request is interpreted correctly. When passing parameters to filter a response on GET requests, parameters can be passed using standard query attributes. In this case, the parameters would be embedded into the URI itself by appending a `?` to the end of the URI and then setting each attribute with an equal sign. Attributes can be separated with a `&`. Tools like `curl` can create the appropriate URI when given parameters and values; this can also be done using the `-F` flag and then passing the key and value as an argument. The argument should take the form of a quoted string with the attribute being set to a value with an equal sign. ### Pass Parameters as a JSON Object ``` curl -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "example.com", "ip_address": "127.0.0.1"}' \ -X POST "https://api.digitalocean.com/v2/domains" ``` ### Pass Filter Parameters as a Query String ``` curl -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -X GET \ "https://api.digitalocean.com/v2/images?private=true" ``` ## Cross Origin Resource Sharing In order to make requests to the API from other domains, the API implements Cross Origin Resource Sharing (CORS) support. CORS support is generally used to create AJAX requests outside of the domain that the request originated from. This is necessary to implement projects like control panels utilizing the API. This tells the browser that it can send requests to an outside domain. The procedure that the browser initiates in order to perform these actions (other than GET requests) begins by sending a "preflight" request. This sets the `Origin` header and uses the `OPTIONS` method. The server will reply back with the methods it allows and some of the limits it imposes. The client then sends the actual request if it falls within the allowed constraints. This process is usually done in the background by the browser, but you can use curl to emulate this process using the example provided. The headers that will be set to show the constraints are: * **Access-Control-Allow-Origin**: This is the domain that is sent by the client or browser as the origin of the request. It is set through an `Origin` header. * **Access-Control-Allow-Methods**: This specifies the allowed options for requests from that domain. This will generally be all available methods. * **Access-Control-Expose-Headers**: This will contain the headers that will be available to requests from the origin domain. * **Access-Control-Max-Age**: This is the length of time that the access is considered valid. After this expires, a new preflight should be sent. * **Access-Control-Allow-Credentials**: This will be set to `true`. It basically allows you to send your OAuth token for authentication. You should not need to be concerned with the details of these headers, because the browser will typically do all of the work for you.
Domains-Index database powered API
This is the official API documentation for the Public Hetzner Cloud.
## Introduction
The Hetzner Cloud API operates over HTTPS and uses JSON as its data format. The API is a RESTful API and utilizes HTTP methods and HTTP status codes to specify requests and responses.
As an alternative to working directly with our API you may also consider to use:
* Our CLI program [hcloud](https://github.com/hetznercloud/cli)
* Our [library for Go](https://github.com/hetznercloud/hcloud-go)
* Our [library for Python](https://github.com/hetznercloud/hcloud-python)
Also you can find a [list of libraries, tools, and integrations on GitHub](https://github.com/hetznercloud/awesome-hcloud).
If you are developing integrations based on our API and your product is Open Source you may be eligible for a free one time €50 (excl. VAT) credit on your account. Please contact us via the the support page on your Cloud Console and let us know the following:
* The type of integration you would like to develop
* Link to the GitHub repo you will use for the Project
* Link to some other Open Source work you have already done (if you have done so)
## Getting Started
To get started using the API you first need an API token. Sign in into the [Hetzner Cloud Console](https://console.hetzner.cloud/) choose a Project, go to `Security` → `API Tokens`, and generate a new token. Make sure to copy the token because it won’t be shown to you again. A token is bound to a Project, to interact with the API of another Project you have to create a new token inside the Project. Let’s say your new token is `jEheVytlAoFl7F8MqUQ7jAo2hOXASztX`.
You’re now ready to do your first request against the API. To get a list of all Servers in your Project, issue the example request on the right side using [curl](https://curl.haxx.se/).
Make sure to replace the token in the example command with the token you have just created. Since your Project probably does not contain any Servers yet, the example response will look like the response on the right side. We will almost always provide a resource root like `servers` inside the example response. A response can also contain a `meta` object with information like [Pagination](https://docs.hetzner.cloud/#overview-pagination).
**Example Request**
```bash
curl -H "Authorization: Bearer jEheVytlAoFl7F8MqUQ7jAo2hOXASztX" \
https://api.hetzner.cloud/v1/servers
```
**Example Response**
```json
{
"servers": [],
"meta": {
"pagination": {
"page": 1,
"per_page": 25,
"previous_page": null,
"next_page": null,
"last_page": 1,
"total_entries": 0
}
}
}
```
## Authentication
All requests to the Hetzner Cloud API must be authenticated via a API token. Include your secret API token in every request you send to the API with the `Authorization` HTTP header.
To create a new API token for your Project, switch into the [Hetzner Cloud Console](https://console.hetzner.cloud/) choose a Project, go to `Security` → `API Tokens`, and generate a new token.
**Example Authorization header**
```html
Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj
```
## Errors
Errors are indicated by HTTP status codes. Further, the response of the request which generated the error contains an error code, an error message, and, optionally, error details. The schema of the error details object depends on the error code.
The error response contains the following keys:
| Keys | Meaning |
|-----------|-----------------------------------------------------------------------|
| `code` | Short string indicating the type of error (machine-parsable) |
| `message` | Textual description on what has gone wrong |
| `details` | An object providing for details on the error (schema depends on code) |
**Example response**
```json
{
"error": {
"code": "invalid_input",
"message": "invalid input in field 'broken_field': is too long",
"details": {
"fields": [
{
"name": "broken_field",
"messages": ["is too long"]
}
]
}
}
}
```
### Error Codes
| Code | Description |
|---------------------------|----------------------------------------------------------------------------------|
| `forbidden` | Insufficient permissions for this request |
| `invalid_input` | Error while parsing or processing the input |
| `json_error` | Invalid JSON input in your request |
| `locked` | The item you are trying to access is locked (there is already an Action running) |
| `not_found` | Entity not found |
| `rate_limit_exceeded` | Error when sending too many requests |
| `resource_limit_exceeded` | Error when exceeding the maximum quantity of a resource for an account |
| `resource_unavailable` | The requested resource is currently unavailable |
| `service_error` | Error within a service |
| `uniqueness_error` | One or more of the objects fields must be unique |
| `protected` | The Action you are trying to start is protected for this resource |
| `maintenance` | Cannot perform operation due to maintenance |
| `conflict` | The resource has changed during the request, please retry |
| `unsupported_error` | The corresponding resource does not support the Action |
| `token_readonly` | The token is only allowed to perform GET requests |
| `unavailable` | A service or product is currently not available |
**invalid_input**
```json
{
"error": {
"code": "invalid_input",
"message": "invalid input in field 'broken_field': is too long",
"details": {
"fields": [
{
"name": "broken_field",
"messages": ["is too long"]
}
]
}
}
}
```
**uniqueness_error**
```json
{
"error": {
"code": "uniqueness_error",
"message": "SSH key with the same fingerprint already exists",
"details": {
"fields": [
{
"name": "public_key"
}
]
}
}
}
```
**resource_limit_exceeded**
```json
{
"error": {
"code": "resource_limit_exceeded",
"message": "project limit exceeded",
"details": {
"limits": [
{
"name": "project_limit"
}
]
}
}
}
```
## Labels
Labels are `key/value` pairs that can be attached to all resources.
Valid label keys have two segments: an optional prefix and name, separated by a slash (`/`). The name segment is required and must be a string of 63 characters or less, beginning and ending with an alphanumeric character (`[a-z0-9A-Z]`) with dashes (`-`), underscores (`_`), dots (`.`), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (`.`), not longer than 253 characters in total, followed by a slash (`/`).
Valid label values must be a string of 63 characters or less and must be empty or begin and end with an alphanumeric character (`[a-z0-9A-Z]`) with dashes (`-`), underscores (`_`), dots (`.`), and alphanumerics between.
The `hetzner.cloud/` prefix is reserved and cannot be used.
**Example Labels**
```json
{
"labels": {
"environment":"development",
"service":"backend",
"example.com/my":"label",
"just-a-key":""
}
}
```
## Label Selector
For resources with labels, you can filter resources by their labels using the label selector query language.
| Expression | Meaning |
|----------------------|---------------------------------------------------------------------|
| `k==v` / `k=v` | Value of key `k` does equal value `v` |
| `k!=v` | Value of key `k` does not equal value `v` |
| `k` | Key `k` is present |
| `!k` | Key `k` is not present |
| `k in (v1,v2,v3)` | Value of key `k` is `v1`, `v2`, or `v3` |
| `k notin (v1,v2,v3)` | Value of key `k` is neither `v1`, nor `v2`, nor `v3` |
| `k1==v,!k2` | Value of key `k1` is `v` and key `k2` is not present |
### Examples
* Returns all resources that have a `env=production` label and that don't have a `type=database` label:
`env=production,type!=database`
* Returns all resources that have a `env=testing` or `env=staging` label:
`env in (testing,staging)`
* Returns all resources that don't have a `type` label:
`!type`
## Pagination
Responses which return multiple items support pagination. If they do support pagination, it can be controlled with following query string parameters:
* A `page` parameter specifies the page to fetch. The number of the first page is 1.
* A `per_page` parameter specifies the number of items returned per page. The default value is 25, the maximum value is 50 except otherwise specified in the documentation.
Responses contain a `Link` header with pagination information.
Additionally, if the response body is JSON and the root object is an object, that object has a `pagination` object inside the `meta` object with pagination information:
**Example Pagination**
```json
{
"servers": [...],
"meta": {
"pagination": {
"page": 2,
"per_page": 25,
"previous_page": 1,
"next_page": 3,
"last_page": 4,
"total_entries": 100
}
}
}
```
The keys `previous_page`, `next_page`, `last_page`, and `total_entries` may be `null` when on the first page, last page, or when the total number of entries is unknown.
**Example Pagination Link header**
```bash
Link:
GoDaddy Abuse API Terms of Use:
GoDaddy’s Abuse API is provided to simplify and standardize the abuse reporting experience. To help us streamline the review of abuse reports, you acknowledge and agree that your use of GoDaddy’s Abuse API is subject to the following quality metrics and terms of use.
GoDaddy may, in its sole and absolute discretion, change or modify these terms, and such changes or modifications shall be effective immediately upon notice to you. Your use of GoDaddy’s Abuse API after such changes or modifications shall constitute your acceptance of these terms as last revised. If you do not agree to be bound by these terms as last revised, do not use (or continue to use) our Abuse API.
As an Abuse API user, you must only submit abuse reports via the API portal and cease all email submissions, including but not limited, to phishing@godaddy.com, netabuse@godaddy.com, malware@godaddy.com, or spam@godaddy.com, etc. Any additional or duplicate submission outside of the API portal will be deprioritized for review. Submissions related to trademark, copyright or content issues may still be sent to trademarkclaims@godaddy.com, coyprightclaims@godaddy.com, and contentcomplaints@godaddy.com, respectively. Our [Front of Site](https://supportcenter.godaddy.com/AbuseReport) also describes other scenarios not covered by the API.
When you submit abuse reports via GoDaddy’s Abuse API, you must ensure that you accurately categorize the abuse type of each report to match our definitions in the API documentations provided to you. Any submission that fails to match our definitions or is miscategorized will be marked as a false positive. Examples include, but are not limited to, submissions of trademark complaints marked as phishing or malware, or submissions of copyright complaints marked as phishing or malware, etc.
If, at any time, the false positive rate of submissions exceeds 40% of your total submissions, as determined by GoDaddy, GoDaddy may in its sole discretion deprioritize any subsequent reports submitted by you and/or your organization.
You acknowledge and agree that submitting every URL for a single domain is not necessary and will not expedite the review process. If your submissions exceed five (5) URLs for a single domain, your report will be marked as a duplicate submission taking into account that the final outcome of such submissions would yield the same result as the original report. GoDaddy may in its sole discretion deprioritize reports submitted by you and/or your organization in the event more than 20% of your submissions are classified as duplicate submissions.
You further acknowledge and agree that our Customer Support lines are not intended to address abuse reporting matters or your use of GoDaddy’s Abuse API. Contacting Customer Support will not expedite the review process and may result in abuse reports being deprioritized, to be determined in our sole discretion.
Should you have any questions about GoDaddy’s Abuse API or any of the terms and conditions set forth above, please contact abuseapisupport@godaddy.com.
API documentation for redirection.io
Sheerseo API has 2 stages:
First stage - initiating the task: You fill in your task and receive in return the task id.
Second stage - collecting the results: send a request containing the task ids you got at the first stage and collecting the results.
Vercel combines the best developer experience with an obsessive focus on end-user performance. Our platform enables frontend teams to do their best work.
Discover the hosting provider for any web site
