API

gcportrait renders Google Cloud-style architecture diagrams. It is an independent open-source project and is not affiliated with, endorsed by, or sponsored by Google. Google Cloud and the Google Cloud product icons are trademarks of Google and are used under Google's icon usage terms.

Every route an instance serves under /api, for scripts: health and settings, the scope search and permission check, the live pull and export read the app streams from, and POST /api/render, which draws a view as SVG, PNG or a draw.io file on the server, byte for byte what pnpm render and the app's export draw. A demo-only instance has none of the routes that need a token.

Authentication

The routes that read Google Cloud take your own Google access token and nothing else; the instance stores it nowhere and logs it never. Send it in X-Gcportrait-Token (the app's header, which Identity-Aware Proxy leaves alone), or in Authorization: Bearer when there is no X-Gcportrait-Token (ADR 0031). A token from gcloud auth print-access-token works; reading a scope needs the permissions of permissions.md. Behind Identity-Aware Proxy, IAP takes Authorization for its own sign-in, so use X-Gcportrait-Token there.

curl -s https://YOUR_INSTANCE/api/healthz
curl -s -H 'X-Gcportrait-Token: YOUR_ACCESS_TOKEN' --json '{"query":"demo"}' https://YOUR_INSTANCE/api/scopes/search

Every request is JSON (curl --json, curl 7.82 or later, sets both content headers), except a render's upload. Answers carry cache-control: no-store and x-request-id; quote the id when you report a problem.

Routes

A scope is organizations/YOUR_ORG_ID, folders/YOUR_FOLDER_ID or projects/YOUR_PROJECT_ID. In user mode a pull reads with your token and charges quotaProject, a project of yours; in sa mode the instance's service account reads, where its operator turned that on, after its gate checked you may see the scope (modes.md). A pull and an export read, each saved as a file the app (and the render API) can read:

curl -s -H 'X-Gcportrait-Token: YOUR_ACCESS_TOKEN' -o pull.ndjson \
  --json '{"scope":"organizations/YOUR_ORG_ID","contentType":"RESOURCE","mode":"user","quotaProject":"YOUR_QUOTA_PROJECT"}' \
  https://YOUR_INSTANCE/api/assets/stream
curl -s -H 'X-Gcportrait-Token: YOUR_ACCESS_TOKEN' -o export.ndjson \
  --json '{"gcsUri":"gs://YOUR_BUCKET/export/"}' https://YOUR_INSTANCE/api/export/read

The two streams answer 200 once they start; what Google says after that arrives as an error frame ({"t":"error","message":…,"status":403,"code":"PERMISSION_DENIED","reason":…}) on the last line.

POST /api/render

Draws one view of one snapshot, with the code pnpm render runs: the same view gives the same bytes, a PNG is the app's export (2× by default, a 24 px margin, the theme's canvas colour), and a draw.io file is the same drawing as cells diagrams.net can edit (below). The request is one JSON document:

scope and demo send the document as the JSON body. ndjson and bundle send multipart/form-data: the document as the field request, first, then the file as the part file (curl -F):

curl -s -H 'X-Gcportrait-Token: YOUR_ACCESS_TOKEN' -OJ \
  --json '{"source":{"kind":"scope","scope":"folders/YOUR_FOLDER_ID","mode":"user","quotaProject":"YOUR_QUOTA_PROJECT"},"view":{"lens":"networking"}}' \
  https://YOUR_INSTANCE/api/render
curl -s -H 'X-Gcportrait-Token: YOUR_ACCESS_TOKEN' -o demo-m.svg \
  --json '{"source":{"kind":"demo","size":"M"},"view":{"hash":"lens=networking&detail=networks"},"format":"svg","theme":"dark"}' \
  https://YOUR_INSTANCE/api/render
curl -s -H 'X-Gcportrait-Token: YOUR_ACCESS_TOKEN' -OJ \
  -F 'request={"source":{"kind":"ndjson"},"scale":3}' -F 'file=@export.ndjson' https://YOUR_INSTANCE/api/render
curl -s -H 'X-Gcportrait-Token: YOUR_ACCESS_TOKEN' -OJ \
  -F 'request={"source":{"kind":"bundle"},"format":"svg"}' -F 'file=@snapshot.gcportrait.json' \
  https://YOUR_INSTANCE/api/render
curl -s -H 'X-Gcportrait-Token: YOUR_ACCESS_TOKEN' -OJ \
  --json '{"source":{"kind":"demo","size":"M"},"format":"drawio"}' https://YOUR_INSTANCE/api/render

-OJ saves the image under the name the instance gives it, the app's export name. A 200 answer's headers:

The drawing is the app's: its title block holds the scope, the lens with the read time (written in UTC) and the tagline. Renders run one at a time per instance, so a script retries a 429 RENDER_BUSY after its Retry-After, as it does every answer marked retryable.

draw.io files

"format": "drawio" answers a .drawio file (gcportrait_<scope>_<lens>_<readTime>.drawio) that diagrams.net (draw.io) opens as an editable diagram looking like the PNG and the SVG. It is not drawn a second time: the SVG of the view is translated into draw.io's cells, so every zone, card, line and label is where the picture has it, in the same colours, strokes, dashes and fonts:

• zones are containers, nested as in the drawing, each with its title as its label, so moving a zone moves what it holds; cards, chips and collapsed zones are groups of their body, their icon (Google's icon as an embedded SVG image, unaltered) and one text cell of their lines;
• lines connect their two nodes, with the drawing's bends as waypoints and their heads and dashes;
• three layers: "Diagram" (zones and nodes), "Connections" (the lines) and "Title and legend" (the title block's three lines and the legend);
• the page's background is the theme's canvas colour, and the file turns off diagrams.net's adaptive colours (adaptiveColors="none"), so it looks the same in diagrams.net's light or dark interface; the file's modified is the data's read time, and the same view gives the same bytes.

The diagram is compressed as diagrams.net saves it (the XML URI-encoded, deflated, base64); "compressed": false (or pnpm render --drawio-plain) writes the XML itself. With fontSource (the default) each label names Google Fonts' stylesheet of Roboto and Roboto Mono: the instance fetches nothing, it is your diagrams.net that loads the faces from Google Fonts when it opens the file.

To open a file in diagrams.net, use File, Open from, Device, or give it a public URL of the file: https://app.diagrams.net/?url= followed by the URL-encoded address of a .drawio file anyone can read (a public bucket's object, a raw file in a public repository).

Errors

Every error is JSON, sent before any byte of an image: { statusCode, error, message, requestId, code, retryable?, reason?, upstream? }. message is for people and names a field, never the value sent; code is for scripts; reason is Google's ErrorInfo reason when Google refused (such as SERVICE_DISABLED). Every 429 and every error with retryable: true carries Retry-After, in seconds: wait that long, then send the same request again.

The streaming routes answer the 400 to 501 rows before they start; the code field is the render route's.

Limits

A render keeps the instance's CPU busy and needs memory for its PNG: demo XL at detail: all and scale 3 needs about 1.4 GiB and minutes of CPU even on a fast machine, so on Cloud Run's one vCPU a large render can approach RENDER_TIMEOUT_MS, and x-gcportrait-scale says when the scale was lowered to fit RENDER_MAX_PIXELS. RENDER_API=false (deploy.sh --no-render-api) turns the route off where nobody needs it. Any Google account's token passes the render route's token check for the demo, ndjson and bundle sources: on a public instance, keep --max-instances low or put Identity-Aware Proxy in front (self-host-options.md). An upload must pass Cloud Run's 32 MiB request limit and arrive within 30 s (else 408); read larger scopes with scope.