canonical: https://jentic.com/apis/sahifa.dev/sahifa

# Sahifa API

The Sahifa API converts HTML or a web page URL into a PDF and captures screenshots of a URL or raw HTML, with every render processed on servers in Jeddah, Saudi Arabia. Its PDF endpoint follows the PDFShift v3 request shape and its screenshot endpoint follows the ScreenshotOne shape, so existing integrations can switch hosts with few changes. PDF options cover page format, margins, headers and footers, page ranges, and custom CSS or JavaScript, while screenshots support full-page capture, element selectors, clipping, dark mode, and blocking of ads, trackers, and cookie banners. Rendered documents are not stored, which supports Saudi data-residency requirements under the PDPL.

## For AI agents

Render HTML or a URL to PDF, or capture a PNG or other image screenshot of a page, from servers hosted in Saudi Arabia.

## Scope

Does not store documents, fill PDF forms, or send rendered files by email. Use for rendering HTML or URLs to PDF and screenshots only.

## Capabilities

- Convert a URL or an HTML string into a PDF with page format, landscape, margin, header, and footer options
- Capture a screenshot of a web page or raw HTML, full-page or clipped to an element selector
- Inject custom CSS or JavaScript and wait for a selector before rendering a PDF
- Block ads, trackers, cookie banners, and chat widgets before taking a screenshot
- Render in Saudi Arabia for data-residency needs, with nothing stored after the response
- Swap in for PDFShift v3 or ScreenshotOne calls using their compatible request shapes

## Use cases

### AI agent report export to PDF

An AI agent that drafts a report in HTML needs to hand the user a finished PDF. Through Jentic the agent searches for 'convert HTML to PDF', loads the Sahifa convertPdf operation with its input schema, and posts the HTML as the required source field while the API key is injected at call time. The response is the rendered PDF, produced in Saudi Arabia and not stored by Sahifa.

Example prompt: POST `/v3/convert/pdf` with source set to the report HTML, format A4, and landscape false, then return the PDF to the user

### Saudi data-residency document generation

Banks and fintechs regulated in Saudi Arabia often must keep customer data in the Kingdom. Sahifa processes every request on Oracle Cloud me-jeddah-1 and does not store request content or rendered documents, which supports SAMA Cyber Security Framework and PDPL residency expectations. Statements, contracts, and receipts can be rendered without sending customer HTML abroad.

Example prompt: Render a customer statement by posting its HTML to POST `/v3/convert/pdf` with a footer showing page numbers and margin set to 20mm

### Website screenshot capture

Monitoring dashboards, link previews, and visual QA all need images of live pages. Sahifa's screenshot operation takes a url or html input with viewport_width, viewport_height, full_page, and selector options, and can block ads, trackers, and cookie banners for a clean capture. Clip coordinates and device_scale_factor control exactly what is captured and at what resolution.

Example prompt: Call GET /take with url set to a landing page, full_page true, block_cookie_banners true, and format png

### Migrating off PDFShift or ScreenshotOne

Teams already integrated with PDFShift v3 or ScreenshotOne can move rendering into Saudi Arabia without rewriting requests. POST `/v3/convert/pdf` also accepts PDFShift-style Basic auth with the API key as the password, and /take also accepts the ScreenshotOne-style access_key query parameter. Changing the host is often the main code change.

Example prompt: Point an existing PDFShift v3 convert request at https://api.sahifa.dev/v3/convert/pdf and confirm the PDF renders with the same source payload

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v3/convert/pdf` | Convert HTML or a URL to PDF |
| GET | `/take` | Screenshot a URL or HTML |
| POST | `/take` | Screenshot with a JSON body |
| GET | `/health` | Service status |

## Key resources

- **PDF** — Convert a URL or HTML to PDF with layout, header, footer, CSS, and JavaScript options
- **Screenshots** — Capture a URL or HTML as an image via query parameters or a JSON body
- **Status** — Public service health check

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 56 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 93 / 100
  - Developer Experience & Jentic Compatibility: 70 / 100
  - AI-Readiness & Agent Experience: 47 / 100
  - Agent Usability: 94 / 100
  - Security: 25 / 100
  - AI Discoverability: 72 / 100
- **View full report:** https://jentic.com/apis/sahifa.dev/sahifa/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Sahifa by hand means choosing between its X-API-Key header, PDFShift-style Basic auth, and the ScreenshotOne access_key parameter, and adding backoff for 408, 429, and 503. Through Jentic you install once, import Sahifa from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Sahifa takes the page or HTML to render in the request body or query string, so rules bound which operations your agent may call, not which pages it renders. You choose the operations it may call, so an agent meant for PDF export does not get the screenshot operations unless you add them.
- **Credential handling:** Your Sahifa API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'convert HTML to PDF' or 'take a screenshot of a page', and Jentic returns the matching Sahifa operation with its input schema so the agent sends the right fields without reading the docs.

## Related APIs

- **ApiFlash** — Website screenshot API built on Chrome
- **HTML/CSS to Image** — Render HTML and CSS into images
- **html2pdf.app** — HTML to PDF conversion service
- **Resend** — Transactional email API for sending the generated documents

## FAQ

### What authentication does the Sahifa API use?

Per its OpenAPI spec, the Sahifa API accepts an API key in the `X-API-Key` header on every render endpoint. For drop-in compatibility, POST `/v3/convert/pdf` also accepts PDFShift-style Basic auth with your key as the password, and /take also accepts the ScreenshotOne-style `access_key` query parameter. GET /health needs no credential.

### Can I screenshot a single element instead of the whole page with the Sahifa API?

Yes. The /take operation accepts a selector parameter to capture one element, or clip_x, clip_y, clip_width, and clip_height to capture a fixed region. Set full_page to true when you want the entire scrollable page instead.

### What are the rate limits for the Sahifa API?

According to the spec, each plan has a monthly render allowance (Sandbox keys also have a daily one) reported in the X-Quota-* response headers. A used-up allowance returns 402, and concurrent renders are queued, with a full queue returning 429. Plan figures are at https://sahifa.dev/en/docs/limits.

### Is there a Sahifa MCP server?

You don't need an MCP server to give your agent Sahifa. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls the PDF and screenshot operations when it needs them, without extra tool definitions sitting in its context.

### How do I convert HTML to PDF with the Sahifa API through Jentic?

Search Jentic for 'convert HTML to PDF', load the POST `/v3/convert/pdf` operation, and execute it with the required source field set to your HTML or a URL, plus options such as format or margin. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Sahifa API?

Yes. If your agent only exports PDFs, write a rule that allows POST `/v3/convert/pdf` and nothing else, so it cannot spend your allowance on screenshots. Each render it requests is logged for review.

### Is it safe to retry a failed Sahifa render?

Yes. The spec notes that a render has no side effects and nothing is stored, so repeating a request never creates a duplicate. Retry 408, 429, and 503 responses with an increasing wait, and do not retry other 4xx errors.
