Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cloudeval.ai/llms.txt

Use this file to discover all available pages before exploring further.

Headless diagram downloads return the same GraphEditor-rendered image bytes used by browser exports. Use the CloudEval CLI when an agent needs a PNG, JPEG, or SVG file directly. Authenticate first with cloudeval login or cloudeval login --headless. Use --machine only when service-principal machine authentication is configured.
CloudEval dependency graph that can also be exported through headless diagram image downloads

​
Why it matters

AI agents and CI jobs need deterministic files, not screenshots from an interactive tab. The diagram image endpoint keeps the browser UI renderer for fidelity while enforcing strict auth boundaries for private project data.

​
Quick example

Download the private architecture and dependency diagrams for one project: 
export CLOUDEVAL_BASE_URL="${CLOUDEVAL_BASE_URL:-https://cloudeval.ai}"
export PROJECT_ID="<project-id>"

mkdir -p diagram-downloads

cloudeval projects export-diagram "$PROJECT_ID" \
  --layout architecture \
  --format png \
  --labels all \
  --output diagram-downloads/architecture.png \
  --headers-output diagram-downloads/architecture.headers \
  --base-url "$CLOUDEVAL_BASE_URL" \
  --non-interactive

cloudeval projects export-diagram "$PROJECT_ID" \
  --layout dependency \
  --format png \
  --labels all \
  --output diagram-downloads/dependency.png \
  --headers-output diagram-downloads/dependency.headers \
  --base-url "$CLOUDEVAL_BASE_URL" \
  --non-interactive
Expected result:
  • diagram-downloads/architecture.png
  • diagram-downloads/dependency.png
  • human output, --json data.output, data.headersOutput, and filesWritten report resolved absolute filesystem paths
  • response headers that include X-CloudEval-Diagram-Auth-Mode, X-CloudEval-Diagram-Graph-Private, node counts, edge counts, diagnostics, and label mode

​
CLI shape

cloudeval projects export-diagram <project-id> \
  --layout architecture|dependency \
  --format png|jpeg|svg \
  --labels all|viewport \
  --output <file> \
  [--headers-output <file>] \
  [--public] \
  [--sync-version <version>] \
  [--frontend-url <url>] \
  [--base-url <url>] \
  [--machine] \
  [--json] \
  [--non-interactive]
The CLI resolves the authenticated user id from cloudeval login, cloudeval login --headless, or --machine and sends it only for private downloads. The frontend defaults to https://cloudeval.ai; pass --frontend-url only for local/dev frontends. Use --public for public/share graph bytes; that mode does not send private auth.

​
Endpoint shape

GET /api/projects/<project-id>/diagram-image?layout=architecture|dependency&format=png|jpeg|svg&labels=all|viewport
Path and query fields:
​
project-id
string
required
The CloudEval project id to export.
​
layout
string
required
Diagram view to render. Supported values are architecture and dependency.
​
format
string
required
Image type to return. Supported values are png, jpeg, and svg.
​
labels
string
Label mode. Use all to force resource names and edge labels, or viewport for normal progressive visibility.
​
user_id
string
Backend user UUID. Required for private bearer-token exports.
​
sync_version
string
Graph snapshot id. Use it to pin a synced graph snapshot when one is available.
​
public
string
Use 1 to export the public/share graph only.

​
Private exports

Private CLI exports require cloudeval login, cloudeval login --headless, or --machine. Prefer stored login state for user workflows. PNG with all labels: 
cloudeval projects export-diagram "$PROJECT_ID" \
  --layout architecture \
  --format png \
  --labels all \
  --output diagram-downloads/private-architecture.png \
  --headers-output diagram-downloads/private-architecture-png.headers \
  --non-interactive
JPEG with viewport labels: 
cloudeval projects export-diagram "$PROJECT_ID" \
  --layout dependency \
  --format jpeg \
  --labels viewport \
  --output diagram-downloads/private-dependency.jpeg \
  --headers-output diagram-downloads/private-dependency-jpeg.headers \
  --non-interactive
SVG pinned to a sync snapshot: 
export SYNC_VERSION="<sync-version>"

cloudeval projects export-diagram "$PROJECT_ID" \
  --layout architecture \
  --format svg \
  --labels all \
  --sync-version "$SYNC_VERSION" \
  --output diagram-downloads/private-architecture.svg \
  --headers-output diagram-downloads/private-architecture-svg.headers \
  --non-interactive
Machine-auth variant: 
cloudeval projects export-diagram "$PROJECT_ID" \
  --layout architecture \
  --format png \
  --labels all \
  --output diagram-downloads/private-architecture.png \
  --headers-output diagram-downloads/private-architecture-png.headers \
  --machine \
  --non-interactive

​
Public or shared exports

Use public=1 only when you intentionally want public/share graph data. It is a scope reduction: CloudEval ignores session and bearer identity, uses only public graph data, and never falls back to private data. 
cloudeval projects export-diagram "$PROJECT_ID" \
  --public \
  --layout dependency \
  --format svg \
  --labels viewport \
  --output diagram-downloads/public-dependency.svg \
  --headers-output diagram-downloads/public-dependency-svg.headers \
  --non-interactive
Do not mix public mode with private user scope. The CLI avoids that mix; raw endpoint calls with public=1&user_id=... return 400 PROJECT_DIAGRAM_SCOPE_CONFLICT.

​
Validate headers

Check headers before trusting a downloaded file in automation: 
grep -i '^x-cloudeval-diagram-' diagram-downloads/architecture.headers
Important headers:
​
X-CloudEval-Diagram-Auth-Mode
header
Returns session, bearer, or public.
​
X-CloudEval-Diagram-Graph-Private
header
Returns 1 for private graph data or 0 for public/share graph data.
​
X-CloudEval-Diagram-Graph-Nodes
header
Rendered node count.
​
X-CloudEval-Diagram-Graph-Edges
header
Rendered edge count.
​
X-CloudEval-Diagram-Diagnostics-*
header
Raw, direct-input, and result graph counts for debugging filtered diagrams.
​
X-CloudEval-Diagram-Labels
header
Returns all or viewport.

​
MCP tool

The CloudEval MCP server exposes the same workflow as projects.exportDiagram. It writes the image to outputPath and can optionally write response headers to headersOutputPath. 
{
  "projectId": "<project-id>",
  "layout": "architecture",
  "format": "png",
  "labels": "all",
  "outputPath": "diagram-downloads/architecture.png",
  "headersOutputPath": "diagram-downloads/architecture.headers"
}

​
Security checks

These commands should fail unless the request is intentionally public: 
# No auth and no public=1 -> 401 PROJECT_DIAGRAM_AUTH_REQUIRED
curl --include --show-error --silent \
  "$CLOUDEVAL_BASE_URL/api/projects/$PROJECT_ID/diagram-image?layout=architecture&format=png&labels=all"

# user_id without auth -> 401 PROJECT_DIAGRAM_AUTH_REQUIRED
curl --include --show-error --silent \
  "$CLOUDEVAL_BASE_URL/api/projects/$PROJECT_ID/diagram-image?layout=architecture&format=png&labels=all&user_id=$USER_ID"

# Auth without user_id -> 400 PROJECT_DIAGRAM_USER_ID_REQUIRED
curl --include --show-error --silent \
  -H "Authorization: Bearer $CLOUDEVAL_BEARER_TOKEN" \
  "$CLOUDEVAL_BASE_URL/api/projects/$PROJECT_ID/diagram-image?layout=architecture&format=png&labels=all"

# public=1 mixed with user_id -> 400 PROJECT_DIAGRAM_SCOPE_CONFLICT
curl --include --show-error --silent \
  -H "Authorization: Bearer $CLOUDEVAL_BEARER_TOKEN" \
  "$CLOUDEVAL_BASE_URL/api/projects/$PROJECT_ID/diagram-image?layout=dependency&format=png&labels=all&public=1&user_id=$USER_ID"

​
Common mistakes

MistakeWhat happens
Passing user_id without authRejected. user_id is not proof of identity.
Forgetting user_id with bearer authRejected because the frontend route cannot infer the backend user scope.
Adding public=1 to a private exportYou get the public/share graph only. Remove public=1 for private data.
Trusting only the file extensionCheck Content-Type and X-CloudEval-Diagram-* headers.
Comparing public and private diagrams without headersPublic/share payloads may contain fewer renderable resources. Use diagnostics headers to explain count differences.

​
Tips

  • Prefer labels=all for agent-readable diagrams.
  • Save headers next to each image so agents can verify provenance later.
  • Use --fail-with-body in scripts so error codes remain visible.
  • Use the web app for visual review when humans need to inspect layout details.
Last modified on May 8, 2026