# PDFCrowd API Guide for Coding Agents

Canonical URL: `https://pdfcrowd.com/api/coding-agent-guide.md`

Use this guide to implement, modify, evaluate, or troubleshoot a PDFCrowd API integration. Apply
only the sections relevant to the user's goal. Treat the selected API documentation as authoritative
for current methods, parameters, defaults, and limits.

## Credentials

Use public username `demo` and API key `demo` by default so work can start without account setup.
Demo output is watermarked. If the project already has working personal credentials, keep using
them.

Tell the user that personal credentials are optional and can be supplied through the environment or
a user-identified project configuration:

```text
PDFCROWD_USERNAME
PDFCROWD_API_KEY
```

Do not require personal credentials or ask the user to put their values in a prompt, print them, or
commit them.

## Select the API

Open the selected converter page, then its documentation for the project's language or HTTP. Do not
guess option or method names.

| Input | Output | Documentation |
| --- | --- | --- |
| Web page or HTML | PDF | [HTML to PDF](https://pdfcrowd.com/api/html-to-pdf-api/) |
| Web page or HTML | Image | [HTML to Image](https://pdfcrowd.com/api/html-to-image-api/) |
| PDF | Modified PDF | [PDF to PDF](https://pdfcrowd.com/api/pdf-to-pdf-api/) |
| PDF | HTML | [PDF to HTML](https://pdfcrowd.com/api/pdf-to-html-api/) |
| PDF | Text | [PDF to Text](https://pdfcrowd.com/api/pdf-to-text-api/) |
| PDF | Image | [PDF to Image](https://pdfcrowd.com/api/pdf-to-image-api/) |
| Image | PDF | [Image to PDF](https://pdfcrowd.com/api/image-to-pdf-api/) |
| Image | Another image format | [Image to Image](https://pdfcrowd.com/api/image-to-image-api/) |
| Invoice, receipt, or quote data | PDF | [Invoice PDF](https://pdfcrowd.com/invoice-pdf-api/) |

The [API overview](https://pdfcrowd.com/api/) is the canonical converter catalog. Use the
[client-library index](https://pdfcrowd.com/api/client-library/) for supported languages, the
[method index](https://pdfcrowd.com/api/method-index/) to locate SDK methods, and the
[status-code reference](https://pdfcrowd.com/api/status-codes/) for failures.

For a new integration, implement the selected converter directly in the target project. For an
existing integration, reproduce its current behavior and make the smallest compatible change. Use
an isolated request only when evaluating without a project or separating PDFCrowd behavior from
application behavior.

## HTML to PDF and HTML to Image

These converters share the same browser-rendering concerns and URL, file/archive, and HTML-string
input modes. Use the output-specific reference before setting options:

- [HTML to PDF HTTP reference](https://pdfcrowd.com/api/html-to-pdf-http/ref/)
- [HTML to Image HTTP reference](https://pdfcrowd.com/api/html-to-image-http/ref/)

### Minimal HTTP isolation

PDF from a URL:

```bash
curl -f -u "demo:demo" \
  -F "url=https://example.com" \
  -o "output.pdf" \
  https://api.pdfcrowd.com/convert/24.04/
```

PNG from a URL:

```bash
curl -f -u "demo:demo" \
  -F "url=https://example.com" \
  -F "output_format=png" \
  -F "screenshot_width=1280" \
  -o "output.png" \
  https://api.pdfcrowd.com/convert/24.04/
```

For file input, replace `url` with `file=@input.html`. For an HTML string, cURL interprets a
multipart value beginning with `<` as a filename; stream the value through stdin:

```bash
printf '%s' '<h1>Hello</h1>' | curl -f -u "demo:demo" \
  -F "text=<-" -o "output.pdf" \
  https://api.pdfcrowd.com/convert/24.04/
```

### Source access and assets

PDFCrowd fetches URL inputs from its servers, not the user's browser or local network. API
credentials authenticate the conversion request, not the source page. For a protected source, use
`setHttpAuth`, `setCookies`, `setCustomHttpHeader`, or the corresponding HTTP parameters. For local
or private content, use a reachable staging or short-lived signed URL, or submit a file, string, or
archive. When the application can render authorized HTML itself, string conversion avoids
transferring a browser session.

For local HTML with relative assets, submit a ZIP, TAR.GZ, or TAR.BZ2 containing the document and
assets. Select the entry document with `setZipMainFilename("index.html")` or
`zip_main_filename=index.html` when the archive contains several HTML files. For string input, use
reachable absolute URLs, a `<base>` URL, or inline suitable assets. Confirm missing-resource
responses in the debug log.

### Dynamic content

Prefer `setWaitForElement("#conversion-ready")` / `wait_for_element=#conversion-ready` when an
element reliably indicates readiness. It searches the main document and iframes and fails if the
selector never appears. Use a fixed JavaScript delay only when no reliable readiness signal exists.

If the user controls the page, add the marker after required asynchronous work finishes. Otherwise,
inspect the live DOM for a stable selector such as `.chart-rendered`, `.results-table`, or
`[data-testid="loaded"]`.

### Debug evidence

For an API error or unexpected conversion, enable `setDebugLog(True)` or `debug_log=true`. Client
libraries expose the log URL through `getDebugLogUrl`; HTTP returns it in the
`x-pdfcrowd-debug-log` response header. Fetch the returned log URL without API authentication. Read
the log for main-page and asset HTTP failures, JavaScript exceptions, rejected promises, blocked
requests, certificate or font problems, timeouts, and `[FATAL]`, `[ERROR]`, or `[WARN]` lines.
Disable logging after diagnosis.

Inspect the source page when its DOM, computed styles, runtime state, console, or network activity
would resolve the issue. Derive exact selectors and changes instead of guessing. Inspect generated
output directly when tools permit; ask the user only for unavailable access or subjective judgment.

### DOM and layout changes

Use `custom_css`, `custom_javascript`, or `element_to_convert` only as evidence requires. A converter
has one custom CSS value and one custom JavaScript value; calling either setter again replaces its
previous value, so combine changes.

For a known overlay:

```python
client.setCustomCss("#cookie-consent { display: none !important; }")
client.setCustomJavascript("document.querySelector('#cookie-consent')?.remove()")
```

If no stable overlay selector exists, `libPdfcrowd.removeZIndexHigherThan({zlimit: 50})` can remove
high-z-index page chrome. Choose the threshold from the page; a broad threshold can remove legitimate
content.

Reveal content already present but hidden with targeted CSS. Trigger interaction only when content
is created or revealed by behavior:

```python
client.setCustomCss(
    ".collapse, .tab-pane { display: block !important; opacity: 1 !important; } "
    "[hidden] { display: revert !important; }"
)
client.setCustomJavascript(
    "document.querySelectorAll('.accordion-button.collapsed')"
    ".forEach(element => element.click())"
)
```

Hide known chrome with exact selectors, or use `setElementToConvert("article")` when one stable
element is the desired output. Inspect framework-specific DOM and events rather than applying these
examples blindly. With `element_to_convert`, the default `cut-out` mode moves the element and can
break selector-dependent styling. Use `remove-siblings` to keep its DOM position or `hide-siblings`
to preserve the full CSS context.

### PDF-specific controls

`content_viewport_width` / `setContentViewportWidth` determines responsive HTML layout before
printing. Use `balanced` when no breakpoint is known, or an explicit width such as `1280px` to match
the application. Presets include `small`, `medium`, `large`, and `extra-large`.

For lazy-loaded content below the fold, use `content_viewport_height=large` /
`setContentViewportHeight("large")`, or an explicit height such as `5000px`. This is not an
HTML-to-Image option.

API page settings take precedence over CSS `@page` by default. Use
`css_page_rule_mode=mode2` / `setCssPageRuleMode("mode2")` when print CSS should control page size,
margins, orientation, named pages, or first/left/right pages; avoid conflicting API page settings.

When CSS page breaks are ignored, inspect the break element and every ancestor up to `body`. The
break must be on block-level ancestry; inline, inline-block, flex, grid, or table wrappers can defeat
it. Move the rule or apply a PDF-only block layout:

```python
client.setCustomCss(
    ".chapter-wrapper { display: block !important; } "
    ".chapter { break-before: page; }"
)
```

Inspect representative PDF pages visually; also use extracted text, page count, dimensions,
orientation, and metadata when they answer the question. Compare before and after output when
changing layout.

### Image-specific controls

`output_format` selects the image format; PNG is the default. Match the filename and expected MIME
type to the selected format. `screenshot_width` controls output width and responsive layout.
`screenshot_height` crops or fixes the output height; when omitted, the actual document height is
used. `scale_factor` controls zoom. `background_color` accepts RRGGBB or RRGGBBAA; transparency such
as `00000000` requires a format that preserves alpha.

Do not pass PDF-only content viewport, page, `@page`, or page-break controls to HTML to Image. For
missing dynamic image content, inspect readiness and use `wait_for_element` or page-specific
JavaScript rather than borrowing `content_viewport_height`.

When image correctness matters and vision is available, inspect the image at original resolution.
Check dimensions, format, alpha/background, scaling, cropping, clipping, responsive layout, missing
assets or content, overlays, and artifacts; compare the source and regenerated output when useful.

### Symptom index

| Symptom | Start with |
| --- | --- |
| Login page, 401/403, or empty protected page | [Source access](#source-access-and-assets) |
| Blank page, app shell, spinner, or incomplete dynamic content | [Readiness](#dynamic-content) and [debug log](#debug-evidence) |
| Missing CSS, images, fonts, scripts, or local assets | [Assets](#source-access-and-assets) and [debug log](#debug-evidence) |
| PDF misses lazy-loaded content below the fold | [PDF viewport height](#pdf-specific-controls) |
| Mobile, cramped, tiny, or clipped layout | PDF `content_viewport_width`; image `screenshot_width` |
| Consent dialog, modal, banner, ad, navigation, or other chrome | [DOM-derived CSS/JavaScript](#dom-and-layout-changes) |
| Accordions, tabs, FAQ answers, or “read more” content hidden | [DOM-derived CSS/JavaScript](#dom-and-layout-changes) |
| Source `@page` rules ignored | PDF `css_page_rule_mode=mode2` |
| PDF page breaks ignored | [Block-level ancestry](#pdf-specific-controls) |
| Existing integration stopped working | Reproduce unchanged; inspect status and [debug log](#debug-evidence) before editing |

For a large batch, validate one representative conversion before spending credits on the full set,
then retain per-item failure reporting.

## Validate Other Converter Outputs

Use the selected API reference rather than HTML-rendering remedies. Inspect representative output
when it would catch an integration error:

- PDF: render relevant pages; check page count, order, dimensions, metadata, and intended changes.
- Image: inspect at original resolution; check format, dimensions, alpha/background, and artifacts.
- Text: check representative extraction, ordering, layout preservation, and encoding.
- HTML: open the result; check structure, text, images, styles, and linked assets.
- PDF/image transformations: verify requested format, page or frame selection/order, dimensions, and
  metadata as applicable.

Use debug logging only when the selected converter documents it and it helps the task.

## Rendering References

- [HTML to PDF HTTP reference](https://pdfcrowd.com/api/html-to-pdf-http/ref/)
- [HTML to Image HTTP reference](https://pdfcrowd.com/api/html-to-image-http/ref/)
- [`libPdfcrowd` JavaScript helpers](https://pdfcrowd.com/api/libpdfcrowd/)
- [Missing assets FAQ](https://pdfcrowd.com/faq/api/style-sheet-is-not-applied-images-are-missing-javascript-is-not-executed/)
- [Page-break FAQ](https://pdfcrowd.com/faq/api/css-page-break-rule-is-not-applied-in-pdf/)