Validate a payload

POST

/v2/validate

Reports syntax and semantic problems in a payload without rendering it. A 200 response does not mean the payload is valid — read valid. Takes the same body and content types as POST /v2/pdf.

Authorizations

ApiKeyHeader

Your Papermill API key, sent as an x-api-key header.

Type

API Key (header: x-api-key)

or

BearerAuth

Your Papermill API key, sent as Authorization: Bearer <key>. Equivalent to the x-api-key form.

Type

HTTP (bearer)

Parameters

Query Parameters

template

The template to render or validate against. Required when the body is JSON, CSV, or Markdown; optional when the body is a complete Press document.

Add an @ suffix to pin the content: report@3 for a published version, report@latest for the newest, report@<tag> for the version a tag names, or report@live for the current content, which is also what a bare identifier renders.

Type

string

Examples

"papermill-invoice""papermill-modern-invoice""papermill-modern-letter""papermill-modern-report""papermill-simple-report"

template_id

The former name for template, which accepts exactly the same values. Still honoured, with no removal planned, so existing integrations need no change. Sending both names with different values is rejected rather than resolved.

Type

string

flow

With Content-Type: text/markdown, the template flow the body replaces. Defaults to body. Supplying it with any other content type is rejected rather than silently ignored.

Type

string

Request Body

Responses

Validation findings, split by severity.

Content-Type

application/json

{

  

"valid": true,

  

"errors": [

  

  

{

  

  

  

"message": "string",

  

  

  

"source": {

  

  

  

  

"tagName": "string",

  

  

  

  

"origin": "string",

  

  

  

  

"lineStart": 0,

  

  

  

  

"lineEnd": 0,

  

  

  

  

"columnStart": 0,

  

  

  

  

"columnEnd": 0

  

  

  

}

  

  

}

  

],

  

"warnings": [

  

  

{

  

  

  

"message": "string",

  

  

  

"source": {

  

  

  

  

"tagName": "string",

  

  

  

  

"origin": "string",

  

  

  

  

"lineStart": 0,

  

  

  

  

"lineEnd": 0,

  

  

  

  

"columnStart": 0,

  

  

  

  

"columnEnd": 0

  

  

  

}

  

  

}

  

]

}

POST

/v2/validate

Playground

Authorization

ApiKeyHeader

Variables

Key

Value

template

template_id

flow

Body

Samples

Example

A 200 does not mean the payload is valid — read valid, and branch on the findings.

shell

curl -X POST https://api.papermill.io/v2/validate \
  -H "Authorization: Bearer $PAPERMILL_API_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @template.press

python

import os
import requests

with open("template.press", "rb") as f:
    response = requests.post(
        "https://api.papermill.io/v2/validate",
        headers={
            "Authorization": f"Bearer {os.environ['PAPERMILL_API_KEY']}",
            "Content-Type": "application/xml",
        },
        data=f.read(),
    )

findings = response.json()
if not findings["valid"]:
    for error in findings["errors"]:
        print(error["message"])

javascript

import fs from 'node:fs/promises'

const response = await fetch('https://api.papermill.io/v2/validate', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PAPERMILL_API_KEY}`,
    'Content-Type': 'application/xml',
  },
  body: await fs.readFile('template.press'),
})

const findings = await response.json()
if (!findings.valid) findings.errors.forEach((e) => console.error(e.message))