The Cloudcraft API provides programmatic access and remote rendering of your architecture diagrams. The API also provides fully automated visualization of AWS and Azure accounts that are linked to your Cloudcraft account, either as ready to use images or as JSON data.

Use case examples:

• Snapshot and visually compare your live AWS environment state before and after a deployment from the command line or as part of your automated CI pipeline.
• Download an inventory of all your AWS resources from a linked account as JSON.
• Write a converter from a third-party data format to Cloudcraft diagrams.
• Backup, export, and import your Cloudcraft data.

Access to the Cloudcraft API requires a Cloudcraft user account.

Authentication

To authenticate your Cloudcraft account for the API, you must include your secret key in the requests. You can create API keys in the Manage API keys > Create API Key section of the Cloudcraft application.

The API key provides access to your diagrams and linked AWS accounts in either read or read-write mode. Do not share your secret API keys in publicly accessible areas such as GitHub or client-side code.

Authentication to the API is performed via the Bearer Authorization header over HTTPS. For example, using cURL an authorized request looks like this:

curl -X GET \
  -H 'Authorization: Bearer bear3vFUUkgfzoBK+UKyPmZw1NsdfrFzdvZoyFJwe8=' \
  https://api.cloudcraft.co/user/me

Endpoints

The Cloudcraft API endpoint is https://api.cloudcraft.co. For access to the Cloudcraft US GovCloud API, contact Cloudcraft Support.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Request rate limiting

Cloudcraft throttles the number of API request that can be made per API key. This is to help the performance of the service, and to ensure fair usage for all Cloudcraft customers. The current API limits are 20 requests / 10 seconds (120 req / minute).

When the request submissions exceeds the rate limit, clients receive a 429 Too Many Requests error response with a Retry-After header that indicates how long (in seconds) the user agent should wait before making a follow-up request. Clients should catch this exception, and retry based on the hint from Retry-After header until successful.

Access control lists

Blueprints and AWS Accounts support the following access control properties:

{
 ...
 readAccess: [],
 writeAccess: []
}

Where an ACL is a string of the form:

• team/TEAM_ID
• customer/CUSTOMER_ID

For example, to share a blueprint with two teams:

 "readAccess": ["team/512184ee-e683-45c1-948a-f588b8c833ca", "team/aab74437-ff4c-4a6d-b366-1311821905b1"]

To unshare a blueprint, set the list to [];

Note: The APIs validate both read and write access separately. In the UI, only the readAccess is reflected.