Cloudcraft API Documentation

Relevant source files

The following files were used as context for generating this wiki page:

• content/en/cloudcraft/api/_index.md
• content/en/cloudcraft/getting-started/generate-api-key.md
• content/en/cloudcraft/advanced/auto-layout-via-api.md
• content/en/cloudcraft/faq/_index.md
• assets/scripts/build-api-pages.js
• content/en/cloudcraft/advanced/add-aws-account-via-api.md
• content/en/cloudcraft/advanced/find-id-using-api.md

The Cloudcraft developer API provides programmatic access to create and render your cloud architecture diagrams. It enables the fully automated visualization of AWS and Azure accounts linked to your Cloudcraft account, delivering diagrams as ready-to-use images or as JSON data. This functionality is ideal for streamlining documentation processes, enhancing team collaboration, and automating infrastructure visualization workflows.

Access to the developer API is an exclusive feature for Cloudcraft Pro and Enterprise subscribers. All API interactions require authentication via a bearer token.

Sources: content/en/cloudcraft/getting-started/generate-api-key.md, content/en/cloudcraft/advanced/auto-layout-via-api.md

Getting Started

Authentication

To use the Cloudcraft API, you must first generate an API key. This requires a user account with either the Owner or Administrator role and an active Cloudcraft Pro subscription.

To create an API key:

1. Navigate to User > API keys in the Cloudcraft web interface.
2. Click Create API key.
3. Provide a descriptive name for the key (e.g., 'Automation Key').
4. Assign the appropriate permissions, adhering to the principle of least privilege.
5. Click Save key and store the generated key in a secure location.

Sources: content/en/cloudcraft/getting-started/generate-api-key.md:1-25

The following diagram illustrates the API key generation flow.

SDKs

Cloudcraft provides official SDKs to simplify interaction with the API. The documentation site shows examples in cURL by default, but also includes code examples for each supported SDK.

Language	Installation Command	Usage Example
Go	go get github.com/DataDog/cloudcraft-go	import ("github.com/DataDog/cloudcraft-go")
Python	pip3 install cloudcraftco	from cloudcraftco import Cloudcraft
Node.js	npm install cloudcraft	import { Cloudcraft } from 'cloudcraft';

Sources: content/en/cloudcraft/api/_index.md:14-43

Rate Limiting

The Cloudcraft API enforces rate limits. If you make too many requests in a short period, the API will respond with an HTTP 429 Too Many Requests error. If you encounter this error, you should reduce the frequency of your API calls.

Sources: content/en/cloudcraft/faq/_index.md:1-13

Core Workflows

Automating Snapshots and Blueprints

A primary use case for the API is to automate the creation of architecture diagrams from your live cloud environments. This process involves two main steps: taking a snapshot of a cloud account and then using that snapshot data to create a new blueprint.

The following sequence diagram shows the interaction between a user/script and the Cloudcraft API to automate diagram generation.

Step 1: Take a Snapshot of the Account

Use the "Snapshot Account" endpoint to get a JSON representation of your AWS or Azure infrastructure. This is equivalent to clicking the "Scan Now" button in the UI.

Example curl command:

curl \
  --url 'https://api.cloudcraft.co/PROVIDER/account/ACCOUNT_ID/REGION/json' \
  --header "Authorization: Bearer API_KEY" > '/tmp/account-infra.json'

• PROVIDER: aws or azure.
• ACCOUNT_ID: The ID of your cloud account in Cloudcraft.
• REGION: The cloud region to scan.
• API_KEY: Your generated API key.

Sources: content/en/cloudcraft/advanced/auto-layout-via-api.md:36-50

Step 2: Generate a New Blueprint

Use the "Create blueprint" endpoint with the JSON data saved from the previous step to create a new diagram in your Cloudcraft account.

Example curl command:

curl \
  --request 'POST' \
  --url 'https://api.cloudcraft.co/blueprint' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer API_KEY" \
  --data '@/tmp/account-infra.json'

Sources: content/en/cloudcraft/advanced/auto-layout-via-api.md:56-67

Key API Endpoints

The documentation highlights several key endpoints for programmatic interaction.

Method	Endpoint	Description
POST	/blueprint	Creates a new blueprint from a JSON data payload.
GET	/aws/account/{id}/{region}/json	Takes a snapshot of a specific AWS account and region, returning the infrastructure as JSON.
GET	/azure/account/{id}/{region}/json	Takes a snapshot of a specific Azure account and region, returning the infrastructure as JSON.
POST	/aws/account	Adds a new AWS account to Cloudcraft.

Sources: content/en/cloudcraft/advanced/auto-layout-via-api.md:23-62, content/en/cloudcraft/advanced/add-aws-account-via-api.md

API Documentation Build Process

The Cloudcraft API reference pages within the Datadog documentation are automatically generated from OpenAPI specification files. A Node.js script, build-api-pages.js, orchestrates this process.

The build process can be summarized as follows:

1. Parse Spec: The script reads and parses an OpenAPI spec file (e.g., full_spec.yaml).
2. Dereference: It resolves all $ref pointers in the spec to create a single, self-contained document.
3. Create Pages: For each tag in the spec, a corresponding markdown directory and _index.md file are created (e.g., /api/v2/blueprints/).
4. Generate Resources: The script processes each API operation, generating example JSON for requests and responses, and creating HTML tables for schema definitions. These are stored in an examples.json file within the page directory.
5. Update Menu: The site's navigation menu (menus/api.en.yaml) is updated with entries for the newly generated API sections and operations.

This diagram shows the flow of the API documentation generation.

Summary

The Cloudcraft API is a powerful tool for developers and cloud architects looking to automate the creation and management of their infrastructure diagrams. By leveraging API keys for authentication and using the provided SDKs, users can programmatically take snapshots of their AWS and Azure environments and generate up-to-date blueprints. This automation capability integrates seamlessly into CI/CD pipelines and infrastructure-as-code workflows, ensuring that documentation remains synchronized with the live environment.

Sources: content/en/cloudcraft/getting-started/generate-api-key.md, content/en/cloudcraft/advanced/auto-layout-via-api.md