API Usage

CloudArch provides a REST API for programmatic script management. You can create architecture diagrams from any LLM, CI/CD pipeline, or automation tool using API keys.

This API is live in production. All endpoints below work today at https://api.cloud-arch.ru.

Authentication

Get an API key

Sign in at web.cloud-arch.ru
Go to Dashboard > API Keys
Enter a name and click Create
Copy the key (starts with ca_) — it won’t be shown again

Use the key in requests

Pass the key in the Authorization header:

Authorization: Bearer ca_your_key_here

Or use the X-API-Key header:

X-API-Key: ca_your_key_here

Create a script

curl -X POST https://api.cloud-arch.ru/v1/scripts \
  -H "Authorization: Bearer ca_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Architecture",
    "slug": "my-arch",
    "description": "Three-tier web app",
    "type": "topology",
    "code": "const t = new TopologyBuilder(false);\n\nconst web = t.createGroup(\"web\", { label: \"Web Tier\" }, { x: 80, y: 40 });\nweb.addProcess({ id: \"nginx\", label: \"Nginx\", state: \"running\" }).autoResize();\n\nconst app = t.createGroup(\"app\", { label: \"App Tier\" }, { x: 80, y: 300 });\napp.addProcess({ id: \"api\", label: \"API Server\", state: \"running\" }).autoResize();\n\nconst db = t.createGroup(\"db\", { label: \"Data Tier\" }, { x: 80, y: 560 });\ndb.addProcess({ id: \"pg\", label: \"PostgreSQL\", state: \"running\", shape: \"cylinder\" }).autoResize();\n\nt.connect(\"nginx\", \"api\", { type: \"http\", label: \"proxy\" });\nt.connect(\"api\", \"pg\", { type: \"tcp\", protocol: \"postgresql\", label: \"queries\" });\n\nawait t.apply();\n\nconst flow = new FlowBuilder();\nflow.from(\"nginx\").showMessage(\"[REQUEST] Client request\").to(\"api\").showMessage(\"[PROCESS] Handle request\").to(\"pg\").showMessage(\"[QUERY] Fetch data\");\nreturn flow;",
    "tags": ["api-created"],
    "isPublic": true,
    "readme": "",
    "engineVersion": "1.0"
  }'

Response (200)

{
  "item": {
    "id": "c67ee7b4-d090-4f31-8fa5-be3fe60697bd",
    "slug": "my-arch",
    "name": "My Architecture",
    ...
  }
}

Your diagram is live at: https://web.cloud-arch.ru/v/my-arch

Server-side validation

The API validates topology scripts before saving. Invalid scripts return 422 with detailed errors:

# Missing .apply() call
curl -X POST https://api.cloud-arch.ru/v1/scripts \
  -H "Authorization: Bearer ca_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Bad","slug":"bad","type":"topology","code":"console.log(1)","tags":[],"isPublic":false,"readme":"","engineVersion":"1.0"}'

Response (422)

{
  "error": "Script validation failed",
  "details": "[ERROR] Errors found:\n  - No nodes or groups found\n  - Missing .apply() call",
  "errors": [
    { "type": "missing", "message": "No nodes or groups found in the script", "fix": "Add at least one node" },
    { "type": "missing", "message": "Missing .apply() call", "fix": "Add await topology.apply();" }
  ]
}

Validation rules

Rule	Required
Script must use `TopologyBuilder`	Yes
Script must call `.apply()`	Yes
Node IDs must be unique	Warning
Connections must reference existing nodes	Error
At least one node or group	Error

Script code structure

Every topology script follows this pattern:

// 1. Create topology
const topology = new TopologyBuilder(false);
 
// 2. Create groups with positions
const group = topology.createGroup('group-id', {
  label: 'Group Name',
  description: 'Optional description'
}, { x: 80, y: 40 });
 
// 3. Add processes to groups
group
  .addProcess({ id: 'node-1', label: 'Node 1', state: 'running' })
  .addProcess({ id: 'node-2', label: 'Node 2', state: 'running' })
  .autoResize();
 
// 4. Connect nodes
topology.connect('node-1', 'node-2', {
  type: 'tcp',           // tcp, http, monitoring, replication, discovery
  protocol: 'kafka',     // kafka, redis, postgresql, http, etc.
  label: 'Connection',
  port: 9092,            // optional port number
});
 
// 5. Apply topology (REQUIRED)
await topology.apply();
 
// 6. Create animation (optional)
const flow = new FlowBuilder();
flow
  .from('node-1')
  .showMessage('[STEP] Description of what happens')
  .to('node-2')
  .showMessage('[DONE] Result');
 
return flow;

Other endpoints

List public scripts

GET /v1/scripts/public?limit=20&offset=0

Get script by slug

GET /v1/scripts/{slug}

Update script

PATCH /v1/scripts/{id}
-H "Authorization: Bearer ca_YOUR_KEY"
-d '{"name": "Updated Name", "code": "..."}'

Delete script

DELETE /v1/scripts/{id}
-H "Authorization: Bearer ca_YOUR_KEY"

Using with LLMs

Claude / ChatGPT

Tell the LLM:

“Create a CloudArch topology script for [your system]. Use TopologyBuilder to create groups and nodes. Connect them with topology.connect(). Add animation with FlowBuilder. Call await topology.apply() at the end. Return the flow.”

Then send the generated code via API:

curl -X POST https://api.cloud-arch.ru/v1/scripts \
  -H "Authorization: Bearer ca_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"Generated\",\"slug\":\"gen-$(date +%s)\",\"type\":\"topology\",\"code\":\"$LLM_OUTPUT\",\"tags\":[\"llm\"],\"isPublic\":true,\"readme\":\"\",\"engineVersion\":\"1.0\"}"

MCP Server

The @cloud-arch/mcp-server npm package lets AI assistants create and manage diagrams directly:

{
  "mcpServers": {
    "cloudarch": {
      "command": "npx",
      "args": ["-y", "@cloud-arch/mcp-server"],
      "env": { "CLOUDARCH_API_KEY": "ca_your_key_here" }
    }
  }
}

Available tools: create_diagram, update_diagram, delete_diagram, list_diagrams, get_script_template.

See MCP Tool Specification for full parameter details.

Rate limits

Plan	Scripts/hour	API calls/hour
Free	10	100
Pro (coming)	100	1000

⚠️

API keys are tied to your account. Do not share them publicly. Revoke compromised keys immediately from Dashboard > API Keys.

Overview MCP Tool Specification