# Run an API server

Source: https://zshot-cli.com/examples/api-server/
Markdown: https://zshot-cli.com/examples/api-server/index.md
Section: [Examples](https://zshot-cli.com/examples/)
License: [Pro](https://zshot-cli.com/support/licenses/pro)

`--server` runs ZShot as an HTTP API that keeps a browser warm between requests. Put it behind a bearer token: pass a shared secret and every request must carry `Authorization: Bearer <token>`, or it gets a `401`.

Start it on port `3000` with a token, locally or from the [Docker image](https://hub.docker.com/r/scaleassembly/zshot-server) — the image reads the same token from `ZSHOT_SERVER_TOKEN_AUTH`:

**Local** — `zshot --server`

```sh
zshot --server \
  --server-bind-port 3000 \
  --server-token-auth s3cr3t
```

**Docker** — `scaleassembly/zshot-server`

```sh
docker run --rm -p 3000:3000 \
  -e ZSHOT_LICENSE="MY-ZSHOT-LICENSE-KEY" \
  -e ZSHOT_SERVER_TOKEN_AUTH="s3cr3t" \
  scaleassembly/zshot-server:latest
```

A client sends the capture request as JSON and reads the response body. This Node script asks the server to render the [Gazette](https://zshot-cli.com/example_assets/gazette/) as Markdown and writes it to `gazette.md`:

```js
// gazette.js — render the Gazette as Markdown through the token-protected server.
import { writeFile } from "node:fs/promises";

const res = await fetch("http://localhost:3000/", {
  method: "POST",
  headers: {
    Authorization: "Bearer s3cr3t",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://zshot-cli.com/example_assets/gazette/",
    output_type: "markdown",
  }),
});
if (!res.ok) throw new Error(`zshot ${res.status}: ${await res.text()}`);
await writeFile("gazette.md", await res.text());
```

Run it with `node gazette.js` on Node 18 or newer. The server returns the page as Markdown, written to [`gazette.md`](/example-renders/api-server.md).

Expected output: [api-server.md](/example-renders/api-server.md)

```
# The ZShot Gazette

Daily Edition · No. 1 Thursday, June 18, 2026 Price: one (1) free license

![](https://zshot-cli.com/example_assets/gazette/zshot-mark.svg)

# The ZShot Gazette

All The Markup That's Fit To Render · zshot-cli.com

[Sports](https://zshot-cli.com/example_assets/gazette/#) [Weather](https://zshot-cli.com/example_assets/gazette/#) [Lifestyle](https://zshot-cli.com/example_assets/gazette/#) [Food](https://zshot-cli.com/example_assets/gazette/#) [Technology](https://zshot-cli.com/example_assets/gazette/#) [Politics](https://zshot-cli.com/example_assets/gazette/#)

Politics

## [Mayor Blamed For Bandwidth Deficit](https://zshot-cli.com/example_assets/gazette/#)

![A rack of network switches with a tangle of blue Ethernet cables](https://zshot-cli.com/example_assets/gazette/img/bandwidth.jpg)

City uplink, pictured Tuesday, allegedly leaking egress that officials insist is not real.

The mayor remains tangled in the city's long-running bandwidth controversy after a hot-mic moment caught him insisting that _"egress isn't real."_ Aides spent the afternoon explaining that the packets are, in fact, leaving. Opposition leaders demanded an immediate uplink and a public traceroute.

By Ada O'Verflow · City Desk

[![A historic theater marquee lit up over a city street at night](https://zshot-cli.com/example_assets/gazette/img/marquee.jpg)](https://zshot-cli.com/example_assets/gazette/#)

Technology

… 53 more lines
```

## Related

Flags:

- [`--server`](https://zshot-cli.com/reference/flags/server/server/)
- [`--server-token-auth`](https://zshot-cli.com/reference/flags/server/server-token-auth/)
- [`--server-bind-port`](https://zshot-cli.com/reference/flags/server/server-bind-port/)

Topics:

- [API](https://zshot-cli.com/reference/server/api/)
- [Docker](https://zshot-cli.com/reference/docker/)

## Navigation

- [Examples](https://zshot-cli.com/examples/)
  - [Webpage as PNG](https://zshot-cli.com/examples/hello-from-zshot/)
  - [Full-page phone screenshot](https://zshot-cli.com/examples/full-page-phone/)
  - [Wait for a JavaScript event](https://zshot-cli.com/examples/wait-for-event/)
  - [Rendered HTML](https://zshot-cli.com/examples/html-output/)
  - [Tablet screenshot](https://zshot-cli.com/examples/tablet-screenshot/)
  - [Accessible PDF](https://zshot-cli.com/examples/accessible-pdf/)
  - [WebM video](https://zshot-cli.com/examples/webm-video/)
  - [Animated GIF](https://zshot-cli.com/examples/animated-gif/)
  - [Dark mode](https://zshot-cli.com/examples/dark-mode/)
  - [Emulate geolocation](https://zshot-cli.com/examples/geolocation/)
  - [Log in, then capture](https://zshot-cli.com/examples/navigate-login/)
  - [Log in, then extract JSON](https://zshot-cli.com/examples/sales-report-json/)
  - [Upload a file, download the result](https://zshot-cli.com/examples/enhance-leads/)
  - [Crawl a site into a WACZ](https://zshot-cli.com/examples/crawl-links/)
  - [Archive a sitemap into a WACZ](https://zshot-cli.com/examples/wacz-sitemap/)
  - **Run an API server**
  - [Signed URL support](https://zshot-cli.com/examples/menu-board/)
  - [Browser as a CDN](https://zshot-cli.com/examples/browser-as-a-cdn/)
- [Download](https://zshot-cli.com/download/)
- [Purchase](https://zshot-cli.com/purchase/)
- [Reference](https://zshot-cli.com/reference/)
- [Support](https://zshot-cli.com/support/)
- [Changelog](https://zshot-cli.com/changelog/)

Site index: https://zshot-cli.com/llms.txt