The Dragon Cave API is an HTTPS interface for programmatically accessing a variety of data about users and dragons. The API should always be used over “scraping” the site’s HTML—scraping is forbidden, even for information that the API does not provide.
Use of the Dragon Cave API is subject to the API Terms and Conditions.
https://dragcave.net/api/v2/
Unless otherwise specified, endpoints expect GET requests, and return JSON. All requests must contain an Authorization: Bearer <privatekey> header, using either a private API key obtained from the Manage Applications page, or a user access token obtained via OAuth.
Other deprecated forms of access are covered in the legacy documentation.
OAuth 2.0 is a framework for allowing third party applications to identify who they are acting on behalf of. The Dragon Cave API uses OAuth to allow applications to fetch information on behalf of specific users, even if they have chosen to hide that information publicly.
Most developers will integrate OAuth2 via an existing library, but the details of the framework are in RFC 6749. Once you have an application, you’ll need to use your “public key” (client_id) and “private key” (client_secret).
https://dragcave.net/oauth_login
https://dragcave.net/api/oauth2/token
https://dragcave.net/api/oauth2/token/revoke
OAuth 2.0 Authorization Server Metadata is also available for interoperability with libraries that support discovering configuration automatically.
The following scopes are available for requesting during the authorization process. Scopes are associated with an access token; changing the scope of usage requires requesting a new access token.
| identify | Access the /me endpoint. Granted by default when using OAuth2 login. |
|---|---|
| dragons | Read a user’s dragon list, even if hidden to others. |
| groups | Access all of a user’s dragon groups, including private groups. |
All API responses contain an array with the key errors. For most requests, this array will be empty, but otherwise it will contain information about what went wrong.
Sites should not treat a non-empty value as a failed request. In certain cases, errors may be returned alongside a complete response in order to provide additional diagnostic information or warnings such as deprecation notices.
Entries in the errors array will be a tuple containing an error code along with a string describing the error. Error codes are as follows:
| 0 | Notice | The request likely completed successfully, but there is info for the API user (e.g. deprecated behavior). |
|---|---|---|
| 1 | Endpoint not found | The specified endpoint does not map to a known endpoint. |
| 2 | Missing/Invalid parameter | Required parameters were not given, or their value is not valid. Refer to each endpoint for a description of acceptable vlaues. |
| 3 | Resource not found | The ID of the dragon, user, or other entity specified in the request was not found. |
| 4 | User error | Something is "wrong" with the user's account. Either it is disabled, or they have no dragons. |
| 5 | Internal error | Something isn’t working on Dragon Cave’s side. Try again later. |
Returns dragon data for one egg, hatchling, or dragon.
| id | Dragon ID. |
|---|---|
| name | Dragon name. Mutually exclusive with ID. |
| id | Dragon's ID, may be up to 5 characters in length. |
|---|---|
| name | Dragon's name if it has one, otherwise null. |
| owner | Owner's username, only if they have set their account settings to reveal their username. |
| start | Stolen/Bred on date in YYYY/MM/DD. 0 if hidden. |
| hatch | Hatched on date in YYYY/MM/DD. 0 for eggs or hidden |
| grow | Date hatchling matured into adult in YYYY/MM/DD. 0 for eggs and hatchlings. |
| death | Date dragon was killed/died in YYYY/MM/DD. 0 if dragon is still alive. |
| views | Self-explanatory. |
| unique | Self-explanatory. |
| clicks | Self-explanatory. |
| gender | "Male" or "Female," empty if not yet revealed. |
| acceptaid | Whether or not the owner of the egg/hatchling is "accepting aid." That this value can change over time, so you should re-check periodically or rely on explicit permission from the dragon's owner by using OAuth. |
| hoursleft | Number of hours until egg dies. -1 if hidden, frozen, or adult, -2 if dead. |
| parent_f | Female parent/mother. |
| parent_m | Male parent/father. |
Returns dragon data for one dragon and its children and their children and so on. Limited to 5 generations or up to 200 dragons.
| id | Dragon ID. |
|---|---|
| name | Dragon name. Mutually exclusive with ID. |
| dragons | List of dragons (see the Get Dragon endpoint). |
|---|
Returns dragon data for one dragon and all of its parents and their parents and so on. Limited to 12 generations or up to 200 dragons.
| id | Dragon ID. |
|---|---|
| name | Dragon name. Mutually exclusive with ID. |
| dragons | List of dragons (see the Get Dragon endpoint). |
|---|
Returns dragon data for multiple eggs, hatchlings, or dragons. Fetching many dragons at once in a single request is much faster/more efficient than making many requests.
| ids | Comma-separated list of dragon IDs. Can be passed via the URL or as a application/x-www-form-urlencoded POST parameter. |
|---|
| dragons | List of dragons (see the Get Dragon endpoint). |
|---|
Returns information about a single dragon group. Private groups cannot be loaded unless the request is made with the owner's access token that has requested the groups scope.
| id | Group's ID. |
|---|
| id | Group's ID. |
|---|---|
| name | Groups's name. |
| visibility | One of HIGHLIGHTED, PUBLIC, or PRIVATE. |
| link | Fully-qualified URL to the group. |
Returns dragon data for all of the eggs, hatchlings, and dragons in a group. Private groups cannot be loaded unless the request is made with the owner's access token that has requested the groups scope.
| id | Group ID. |
|---|---|
| filter | Subset of dragons to return: ALL, GROWING, ADULTS_AND_FROZEN. |
| limit | How many dragons to return per-page. Default 500. There is no upper bound on this parameter, but requests that try to fetch too many dragons at once may fail. |
| after | The pagination cursor (where to resume paging). |
| dragons | List of dragons (see the Get Dragon endpoint). |
|---|---|
| data | Pagination info. |
Returns information about the currently logged-in user. Requires passing a user access token.
| user_id | ID of the currently logged-in user. |
|---|---|
| username | Name of the currently logged-in user. |
Returns dragon data for all of a user's eggs, hatchlings, or dragons.
| username | The target user's name. |
|---|---|
| filter | Subset of dragons to return: ALL, GROWING, ADULTS_AND_FROZEN. |
| limit | How many dragons to return per-page. Default 500. There is no upper bound on this parameter, but requests that try to fetch too many dragons at once may fail. |
| after | The pagination cursor (where to resume paging). |
| dragons | List of dragons (see the view endpoint). |
|---|---|
| data | Pagination info. |
Returns a list of all of a user's dragon groups. Only highlighted groups will be returned, unless the request is made with a user access token that has the groups scope.
| username | The target user's name. |
|---|---|
| limit | How many groups to return per-page. Default 50. |
| after | The pagination cursor (where to resume paging). |
| groups | List of groups. See the Get Group endpoint. |
|---|---|
| data | Pagination info. |