# render

Render a Paradoc form, document, or checklist through one of its layers

Canonical URL: https://docs.paradoc.dev/ai-tools/render/

Renders a form, document, or checklist through one of its layers. The tool validates the artifact, fills forms and checklists with `data`, and renders with the layer's renderer: text layers (`text/plain`, `text/markdown`, `text/html`), PDF, and DOCX. Output is always inline: text as UTF-8, binary as base64.

A form or checklist draft does not need to be complete to render, but it needs at least one value. With `data` missing, null, or holding no values, the render is refused with `missing_data`, so data lost on the way never becomes a blank file reported as success. Set `blank: true` to render a blank copy. Bundles are not supported.

## Input

Takes a [source](/ai-tools#sources) plus:

| Field                          | Type      | Required | Description                                                                                                                                                                                                    |
| ------------------------------ | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`                         | `object`  | No       | Form or checklist payload, usually `data` from [`fill`](/ai-tools/fill) or [`update_fill`](/ai-tools/update-fill). Documents need none. A form or checklist needs at least one value unless `blank` is `true`. |
| `blank`                        | `boolean` | No       | Render a form or checklist with no values, as a blank copy. Default `false`.                                                                                                                                   |
| `evaluation_context`           | `object`  | No       | The draft's `evaluation_context`                                                                                                                                                                               |
| `layer`                        | `string`  | No       | Layer key. Default: the artifact's `defaultLayer`, then its first layer.                                                                                                                                       |
| `presentation.max_bytes`       | `integer` | No       | Cut `content` to this many bytes. Base64 is cut at a whole 4-character group so it still decodes.                                                                                                              |
| `presentation.include_content` | `boolean` | No       | Set `false` to return only metadata, with no `content`. Default `true`.                                                                                                                                        |

`presentation` controls the application-facing result. The separate `maxOutputBytes` [config](/ai-tools/api#configuration) value controls the copy sent to the model. File-backed layers load relative to the source's base URL; with an [artifact source](/ai-tools#sources), set `base_url`.

## Output

| Field               | Type                              | Description                                                                                                   |
| ------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `success`           | `boolean`                         | Whether the render completed                                                                                  |
| `artifact_kind`     | `string`                          | `form`, `document`, or `checklist`                                                                            |
| `content`           | `string`                          | The rendered output                                                                                           |
| `encoding`          | `"utf-8" \| "base64"`             | `utf-8` for text, `base64` for PDF and DOCX                                                                   |
| `mime_type`         | `string`                          | The layer's MIME type                                                                                         |
| `byte_length`       | `number`                          | Full size of the rendered output, before any cut                                                              |
| `truncated`         | `boolean`                         | `true` when `content` was cut or left out                                                                     |
| `validation_issues` | `{ message, path? }[]`            | Schema issues when the artifact is invalid                                                                    |
| `errors`            | [`ToolError[]`](/ai-tools#errors) | Rejected `data` values                                                                                        |
| `error`             | [`ToolError`](/ai-tools#errors)   | Why the render failed, such as `invalid_artifact`, `missing_layer`, `missing_data`, or `unsupported_artifact` |

## Direct usage

```typescript
import { executeRender } from "@paradoc/ai-tools"

const result = await executeRender({
  source: "artifact",
  artifact: {
    kind: "form",
    name: "note",
    version: "1.0.0",
    title: "Note",
    fields: { name: { type: "text", label: "Name", required: true } },
    layers: {
      markdown: { kind: "inline", mimeType: "text/markdown", text: "# Note for {{fields.name}}" },
    },
    defaultLayer: "markdown",
  },
  data: { fields: { name: "Jane Doe" } },
})
```

From a registry, to PDF, with a limit on what goes back to the model:

```typescript
const result = await executeRender({
  source: "registry",
  registry_url: "https://public.paradoc.dev",
  artifact_name: "pet-addendum",
  data: draft.data,
  evaluation_context: draft.evaluation_context,
  layer: "pdf",
  presentation: { max_bytes: 20_000 },
})
// result.encoding === "base64", result.mime_type === "application/pdf"
```

## Example responses

### Text render

```json
{
  "success": true,
  "artifact_kind": "form",
  "encoding": "utf-8",
  "mime_type": "text/markdown",
  "byte_length": 19,
  "content": "# Note for Jane Doe"
}
```

### Content left out

With `presentation: { include_content: false }`:

```json
{
  "success": true,
  "artifact_kind": "form",
  "encoding": "utf-8",
  "mime_type": "text/markdown",
  "byte_length": 19,
  "truncated": true
}
```

### Rejected data

```json
{
  "success": false,
  "artifact_kind": "form",
  "errors": [
    {
      "code": "validation_error",
      "message": "Invalid input: expected string, received number",
      "path": ["fields", "name"]
    }
  ],
  "error": {
    "code": "validation_error",
    "message": "Form data validation failed: Invalid input: expected string, received number"
  }
}
```