openapi: 3.2.0
info:
  title: Sahifa PDF API
  version: 1.0.0
  summary: HTML to PDF and screenshot API hosted in Saudi Arabia
  description: HTML to PDF and screenshot API hosted in Jeddah, Saudi Arabia.
  termsOfService: https://sahifa.dev/en/terms
  contact:
    name: Sahifa support
    email: support@sahifa.dev
    url: https://sahifa.dev/en/contact
  license:
    name: Proprietary
    url: https://sahifa.dev/en/terms
  x-provider: Yimello LLC (United Arab Emirates)
  x-data-residency:
    country: SA
    region: me-jeddah-1
    storage: none
    frameworks:
    - SAMA Cyber Security Framework
    - Saudi PDPL
    dpa: https://sahifa.dev/en/dpa
    details: https://sahifa.dev/en/data-residency
  x-pricing: https://sahifa.dev/en/pricing
  x-changelog: https://sahifa.dev/en/docs/changelog
  x-status: https://stats.uptimerobot.com/5fFpK4UvT9
servers:
- url: https://api.sahifa.dev
  description: Production, Jeddah, Saudi Arabia (me-jeddah-1)
security:
- apiKeyHeader: []
tags:
- name: PDF
  description: HTML or a URL to PDF, PDFShift v3 compatible
  externalDocs:
    url: https://sahifa.dev/en/docs/pdf
paths:
  /v3/convert/pdf:
    post:
      operationId: convertPdf
      tags:
      - PDF
      summary: Convert HTML or a URL to PDF (PDFShift v3 compatible)
      description: 'Renders the HTML document or public URL in `source` with Chromium and returns the PDF. Nothing is stored. Retrying is safe: a render has no side effects and nothing is stored, so a repeated request never creates a duplicate. Retry 408, 429 and 503 with an increasing wait (for example 2, 4 and 8 seconds); do not retry other 4xx errors.'
      security:
      - apiKeyHeader: []
      - basicAuth: []
      x-idempotent: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - source
              properties:
                source:
                  type: string
                  description: http(s) URL or HTML document.
                format:
                  type: string
                  default: A4
                  description: A0-A6, Letter, Legal, Tabloid, Ledger, or {width}x{height} such as 210mmx297mm.
                landscape:
                  type: boolean
                  default: false
                margin:
                  oneOf:
                  - type: string
                  - type: object
                    properties:
                      top:
                        type: string
                      right:
                        type: string
                      bottom:
                        type: string
                      left:
                        type: string
                header:
                  type: object
                  required:
                  - source
                  properties:
                    source:
                      type: string
                      description: HTML; variables {{page}}, {{total}}, {{date}}, {{title}}, {{url}}.
                    height:
                      type: string
                      description: Accepted; the space comes from margin.
                footer:
                  type: object
                  required:
                  - source
                  properties:
                    source:
                      type: string
                      description: HTML; variables {{page}}, {{total}}, {{date}}, {{title}}, {{url}}.
                    height:
                      type: string
                      description: Accepted; the space comes from margin.
                pages:
                  type: string
                  examples:
                  - 1,3-5
                zoom:
                  type: number
                  minimum: 0.1
                  maximum: 2
                use_print:
                  type: boolean
                  default: false
                disable_backgrounds:
                  type: boolean
                  default: false
                disable_javascript:
                  type: boolean
                  default: false
                delay:
                  type: integer
                  minimum: 0
                  maximum: 10000
                  description: Milliseconds.
                wait_for:
                  type: string
                  description: Name of a global function that returns truthy when the page is ready.
                timeout:
                  type: integer
                  minimum: 1
                  maximum: 100
                  description: Seconds; capped at 30.
                raise_for_status:
                  type: boolean
                  default: false
                css:
                  type: string
                javascript:
                  type: string
                auth:
                  type: object
                  required:
                  - username
                  - password
                  properties:
                    username:
                      type: string
                    password:
                      type: string
                http_headers:
                  type: object
                  additionalProperties:
                    type: string
                cookies:
                  type: array
                  items:
                    type: object
                    required:
                    - name
                    - value
                    properties:
                      name:
                        type: string
                      value:
                        type: string
                      domain:
                        type: string
                      path:
                        type: string
                      secure:
                        type: boolean
                      http_only:
                        type: boolean
                encode:
                  type: boolean
                  default: false
                  description: Return JSON with base64 data.
                sandbox:
                  type: boolean
                  description: Accepted and ignored.
            examples:
              arabicInvoice:
                summary: Arabic invoice from HTML, with page numbers
                value:
                  source: <html dir="rtl" lang="ar"><body><h1>فاتورة ضريبية</h1><p>Invoice INV-1001</p></body></html>
                  format: A4
                  margin: 15mm
                  footer:
                    source: <div style="font-size:9px;text-align:center">{{page}} / {{total}}</div>
              url:
                summary: A public web page to PDF, landscape
                value:
                  source: https://example.com
                  landscape: true
              base64:
                summary: JSON response with base64 data
                value:
                  source: <h1>Hello</h1>
                  encode: true
      responses:
        '200':
          description: The PDF, or JSON when encode is true
          headers:
            X-Response-Duration:
              schema:
                type: integer
              description: Render time in milliseconds
            X-Quota-Limit:
              schema:
                type: integer
              description: Monthly render allowance of the key
            X-Quota-Remaining:
              schema:
                type: integer
              description: Renders left this month before this request
            X-Quota-Daily-Limit:
              schema:
                type: integer
              description: 'Sandbox keys only: daily render allowance'
            X-Quota-Daily-Remaining:
              schema:
                type: integer
              description: 'Sandbox keys only: renders left today'
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: string
                    contentEncoding: base64
                  filesize:
                    type: integer
                  duration:
                    type: integer
              example:
                success: true
                data: JVBERi0xLjcKJcfsj6IK...
                filesize: 18734
                duration: 412
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                error: source is required
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                error: Invalid or missing API key
        '402':
          description: Monthly render allowance used up
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                error: Monthly render allowance used up
        '408':
          description: 'Rendering timed out. Retrying is safe: a render has no side effects and nothing is stored, so a repeated request never creates a duplicate. Retry 408, 429 and 503 with an increasing wait (for example 2, 4 and 8 seconds); do not retry other 4xx errors.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                error: Rendering timed out
        '413':
          description: Request body over 10 MB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                error: Request body too large
        '429':
          description: 'Render queue full. Retrying is safe: a render has no side effects and nothing is stored, so a repeated request never creates a duplicate. Retry 408, 429 and 503 with an increasing wait (for example 2, 4 and 8 seconds); do not retry other 4xx errors.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                error: Render queue full, retry shortly
        '500':
          description: Rendering error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                error: Rendering failed
        '503':
          description: 'Temporarily unavailable. Retrying is safe: a render has no side effects and nothing is stored, so a repeated request never creates a duplicate. Retry 408, 429 and 503 with an increasing wait (for example 2, 4 and 8 seconds); do not retry other 4xx errors.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                error: Service temporarily unavailable
components:
  schemas:
    Error:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          const: false
        error:
          type: string
          description: Human-readable reason
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your API key, from https://sahifa.dev/en/account. Works on every endpoint.
    basicAuth:
      type: http
      scheme: basic
      description: 'PDFShift compatibility, /v3/convert/pdf only: user ''api'', password = your API key.'
    accessKey:
      type: apiKey
      in: query
      name: access_key
      description: ScreenshotOne compatibility, /take only.
externalDocs:
  description: Documentation
  url: https://sahifa.dev/en/docs
x-provenance:
  method: harvested
  publisher: Sahifa
  source: https://sahifa.dev/docs/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)