# API

Source: https://zshot-cli.com/reference/server/api/
Markdown: https://zshot-cli.com/reference/server/api/index.md
Section: [Reference](https://zshot-cli.com/reference/) › [Server](https://zshot-cli.com/reference/server/)

The API serves captures to other clients over HTTP from a [server](/reference/server) that keeps a browser warm between requests. Server mode is a [Pro](/support/licenses) feature; [signed-URL](/reference/flags/server/server-signed-url) authentication requires [Enterprise](/support/licenses).

Run ZShot inside your own infrastructure and reach it from your own services. It is not built to sit on the public internet.

`GET /` takes a render request as query parameters and `POST /` as a JSON body. The [request schema](/reference/server/api/schema) lists every key either one takes.

## Security

The server offers Basic, token and signed-URL [authentication](/reference/server/authentication), and [`--block-private-ips`](/reference/flags/security/block-private-ips) keeps a rendered page from reaching internal hosts. These controls protect a service running among trusted callers; they are not a hardening layer against wide public exposure. Put ZShot behind your own network boundary and front it with a gateway that handles public traffic.

## PDF pages

A page that is a PDF renders only as `download`, `warc`, `wacz` or `har`. Any other
`output_type` answers `422` with `Unsupported content: <url> is a PDF (application/pdf)`,
and so does a navigation that reaches a PDF.

## Navigator credentials and files

A request supplies literal credentials as `navigator_credential`, a name→value
map, and may scope them to other pages with `navigator_credential_origin`, a map
from a name or a name pattern such as `*` to globs. `navigator_file` maps names to base64 data URLs or to
`http(s)` URLs the server fetches through its IP filter the first time the
navigator attaches the file; a fetch that fails answers `502` with
`Navigator file 'NAME' failed: <reason>`, the failure class only. A navigation
that does not reach its goal answers `502` with `Navigation failed: <reason>`
and produces no output. Credentials configured when the server started with
[`--navigator-credential-helper`](/reference/flags/navigator/navigator-credential-helper)
are offered to every request under their startup origins; a request that restates
one of those names in either map is rejected with `400`. A helper that fails during
a request answers `502` with `Credential helper 'NAME' failed: <reason>`, where the
reason is the failure class only; the detail is in the server log.

## Navigation

- [Examples](https://zshot-cli.com/examples/)
- [Download](https://zshot-cli.com/download/)
- [Purchase](https://zshot-cli.com/purchase/)
- [Reference](https://zshot-cli.com/reference/)
  - [Formats](https://zshot-cli.com/reference/formats/)
  - [Flags](https://zshot-cli.com/reference/flags/)
  - [Agents](https://zshot-cli.com/reference/agents/)
  - [Configuration](https://zshot-cli.com/reference/configuration/)
  - [Crawling](https://zshot-cli.com/reference/crawling/)
  - [Docker](https://zshot-cli.com/reference/docker/)
  - [Exit Codes](https://zshot-cli.com/reference/exit_codes/)
  - [Linux](https://zshot-cli.com/reference/linux/)
  - [LLM Connections](https://zshot-cli.com/reference/llm_connections/)
  - [LLM Formatting](https://zshot-cli.com/reference/llm_formatting/)
  - [Local Inputs](https://zshot-cli.com/reference/inputs/)
  - [Navigator](https://zshot-cli.com/reference/navigator/)
  - [Security](https://zshot-cli.com/reference/security/)
  - [Server](https://zshot-cli.com/reference/server/)
    - **API**
      - [Request schema](https://zshot-cli.com/reference/server/api/schema/)
    - [Endpoints](https://zshot-cli.com/reference/server/endpoints/)
    - [Metrics](https://zshot-cli.com/reference/server/metrics/)
    - [Additional Assets](https://zshot-cli.com/reference/server/additional-assets/)
    - [Authentication](https://zshot-cli.com/reference/server/authentication/)
    - [Caching](https://zshot-cli.com/reference/server/caching/)
  - [Shell completions](https://zshot-cli.com/reference/shell_completions/)
  - [Storage](https://zshot-cli.com/reference/storage/)
  - [Timeouts](https://zshot-cli.com/reference/timeouts/)
  - [Web Bot Auth](https://zshot-cli.com/reference/web_bot_auth/)
- [Support](https://zshot-cli.com/support/)
- [Changelog](https://zshot-cli.com/changelog/)

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