PDFDesignAPI

https://pdfdesignapi.com/docs
Admin
PDFDesignAPI provides a visual template designer, embedded SDK, and REST API for generating dynamic...
Tokens:7,174
Snippets:115
Trust Score:5.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install PDFDesignAPI skill for OpenCode

Source: https://pdfdesignapi.com/docs/agents/pdfdesignapi-skill

Run from the project root to install the PDFDesignAPI skill for OpenCode. The -y flag accepts defaults, and the -a opencode flag targets the OpenCode agent client.

```bash
npx skills add https://pdfdesignapi.com/skills/pdfdesignapi/SKILL.md -a opencode -y
```

--------------------------------

### GET /api/v1/render-jobs/:uuid

Source: https://pdfdesignapi.com/docs/api/async-and-batch

Returns the current state of a render job.

```APIDOC
## GET /api/v1/render-jobs/:uuid

### Description
Returns the current state of a render job.

### Method
GET

### Endpoint
/api/v1/render-jobs/:uuid

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The UUID of the render job.

### Response
#### Success Response (200)
- **job** (object) - The current job state.

#### Response Example
(Not provided in source)

```

--------------------------------

### GET /api/v1/render-batches/:batchUuid

Source: https://pdfdesignapi.com/docs/api/async-and-batch

Reports the batch and its item states. Handle partial failures explicitly.

```APIDOC
## GET /api/v1/render-batches/:batchUuid

### Description
Reports the batch and its item states. Handle partial failures explicitly.

### Method
GET

### Endpoint
/api/v1/render-batches/:batchUuid

### Parameters
#### Path Parameters
- **batchUuid** (string) - Required - The UUID of the batch.

### Response
#### Success Response (200)
- **batch** (object) - The batch and its item states.

#### Response Example
(Not provided in source)

```

--------------------------------

### GET /api/v1/render-jobs/:uuid/result

Source: https://pdfdesignapi.com/docs/api/async-and-batch

Returns the private PDF result of a completed render job. Results expire after 24 hours, so move them to your own authorized storage if longer retention is required.

```APIDOC
## GET /api/v1/render-jobs/:uuid/result

### Description
Returns the private PDF result of a completed render job. Results expire after 24 hours, so move them to your own authorized storage if longer retention is required.

### Method
GET

### Endpoint
/api/v1/render-jobs/:uuid/result

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The UUID of the render job.

### Response
#### Success Response (200)
- **pdf** (binary) - The PDF file content.

#### Response Example
(Not provided in source)

```

--------------------------------

### Configure OpenCode MCP server in opencode.json

Source: https://pdfdesignapi.com/docs/agents/mcp-server

Add this entry to the project-level opencode.json to configure the PDFDesignAPI MCP server as a remote server. Requires setting PDFDESIGNAPI_API_KEY in the shell before launching OpenCode, then restart OpenCode to verify the pdfdesignapi tools are available.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pdfdesignapi": {
      "type": "remote",
      "url": "https://pdfdesignapi.com/api/mcp",
      "headers": {
        "Authorization": "Bearer {env:PDFDESIGNAPI_API_KEY}"
      }
    }
  }
}
```

--------------------------------

### POST /api/v1/generate/batch/:templateUuid

Source: https://pdfdesignapi.com/docs/api/async-and-batch

Accepts multiple document items and validates all of them before jobs are created.

```APIDOC
## POST /api/v1/generate/batch/:templateUuid

### Description
Accepts multiple document items and validates all of them before jobs are created.

### Method
POST

### Endpoint
/api/v1/generate/batch/:templateUuid

### Parameters
#### Path Parameters
- **templateUuid** (string) - Required - The UUID of the template to render.

#### Request Body
- **items** (array) - Required - The list of document items to render.

### Request Example
(Not provided in source)

### Response
#### Success Response (200)
- **batch** (object) - The created batch.

#### Response Example
(Not provided in source)

```

--------------------------------

### Generate a PDF with curl using the /generate/single endpoint

Source: https://pdfdesignapi.com/docs

Sends a synchronous generation request to the PDFDesignAPI endpoint. Requires a template UUID and an API token; the response is a binary PDF saved to result.pdf. Keep the token in server-side secret storage and never expose it in browser code or commit it to source control.

```bash
curl -X POST "https://pdfdesignapi.com/api/v1/generate/single/TEMPLATE_UUID" \
  -H "Authorization: Bearer API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":{"customer":{"name":"Example BV"}}}' \
  --output result.pdf
```

--------------------------------

### Create an asynchronous job via POST

Source: https://pdfdesignapi.com/docs/api/async-and-batch

Use this endpoint to queue a generation job without holding open an interactive HTTP request. Requires a template UUID and authorization token.

```http
POST https://pdfdesignapi.com/api/v1/generate/async/TEMPLATE_UUID
Authorization: Bearer API_TOKEN
Content-Type: application/json

{"data":{"report":{"title":"Monthly report"}}}
```

--------------------------------

### Generate a PDF with the same pair using curl

Source: https://pdfdesignapi.com/docs/embedded/sdk-quickstart

Generate a PDF using the same base template UUID and external UUID that created the editor session. The payload is validated against the locked template contract and rendered with the customer-specific layout.

```bash
curl -X POST "https://pdfdesignapi.com/api/v1/generate/single/BASE_TEMPLATE_UUID/EXTERNAL_UUID"   -H "Authorization: Bearer API_TOKEN"   -H "Content-Type: application/json"   -d '{"data":{"customer":{"name":"Example BV"}}}'   --output document.pdf
```

--------------------------------

### POST /api/v1/generate/single/:templateUuid

Source: https://pdfdesignapi.com/docs/api/synchronous-generation

Generates a PDF synchronously by sending JSON data to the API. Returns a binary PDF when rendering succeeds.

```APIDOC
## POST /api/v1/generate/single/:templateUuid

### Description
Generates a PDF synchronously by sending JSON data to the API. The endpoint returns a binary PDF when rendering succeeds. The request body must contain a data object matching the selected template contract.

### Method
POST

### Endpoint
/api/v1/generate/single/:templateUuid
(e.g., https://pdfdesignapi.com/api/v1/generate/single/TEMPLATE_UUID)

### Parameters
#### Path Parameters
- **templateUuid** (string) - Required - The UUID of the template to use for PDF generation.

#### Request Body
- **data** (object) - Required - An object matching the selected template contract.
  Example: {"customer":{"name":"Example BV"}}

### Request Example
```
POST https://pdfdesignapi.com/api/v1/generate/single/TEMPLATE_UUID
Authorization: Bearer API_TOKEN
Content-Type: application/json

{"data":{"customer":{"name":"Example BV"}}}
```

### Response
#### Success Response (200)
- Returns a binary PDF (application/pdf).
- Do not parse the PDF body as JSON.
- Error responses use the documented structured error format.

#### Response Example
Binary PDF content
```

--------------------------------

### Mount the embedded editor with PDFDesignAPIEmbed

Source: https://pdfdesignapi.com/docs/embedded/sdk-quickstart

Mount the embedded editor in your frontend using the browser helper. The editor can add, remove, position, style, and bind document components; the base dataSchema and exampleData are read-only in both the UI and save API. It emits ready, saved, and error events, and the helper should be destroyed when the editor view is removed.

```html
<div id="template-editor" style="height: 800px"></div>
<script type="module">
  import { PDFDesignAPIEmbed } from 'https://pdfdesignapi.com/sdk/pdfdesignapi-embed.js'

  const editor = new PDFDesignAPIEmbed({
    container: '#template-editor',
    embedUrl: session.embedUrl,
  }).mount()

  editor.on('saved', ({ version }) => console.log('Saved version', version))
  editor.on('error', ({ message }) => console.error(message))
</script>
```

--------------------------------

### Set PDFDESIGNAPI_API_KEY environment variable

Source: https://pdfdesignapi.com/docs/agents/mcp-server

Set the team API key as an environment variable for the MCP server. Store it in a protected environment variable and never commit it to source control or paste it into prompts.

```bash
export PDFDESIGNAPI_API_KEY="YOUR_API_KEY"
```

--------------------------------

### POST /api/v1/generate/single/:templateUuid

Source: https://pdfdesignapi.com/docs/api/synchronous-generation

Send a synchronous PDF generation request to the /api/v1/generate/single/:templateUuid endpoint. The body must contain a data object matching the selected template contract. A successful response is a binary PDF; error responses use the documented structured error format.

```http
POST https://pdfdesignapi.com/api/v1/generate/single/TEMPLATE_UUID
Authorization: Bearer API_TOKEN
Content-Type: application/json

{"data":{"customer":{"name":"Example BV"}}}
```

--------------------------------

### POST /api/v1/generate/async/:templateUuid

Source: https://pdfdesignapi.com/docs/api/async-and-batch

Creates an asynchronous render job for a template. Validates the request and returns a render job without holding open an interactive HTTP request.

```APIDOC
## POST /api/v1/generate/async/:templateUuid

### Description
Creates an asynchronous render job for a template. Validates the request and returns a render job without holding open an interactive HTTP request.

### Method
POST

### Endpoint
/api/v1/generate/async/:templateUuid

### Parameters
#### Path Parameters
- **templateUuid** (string) - Required - The UUID of the template to render.

#### Request Body
- **data** (object) - Required - The data to render the template with.

### Request Example
```
POST https://pdfdesignapi.com/api/v1/generate/async/TEMPLATE_UUID
Authorization: Bearer API_TOKEN
Content-Type: application/json

{"data":{"report":{"title":"Monthly report"}}}
```

### Response
#### Success Response (200)
- **job** (object) - The render job created.

#### Response Example
(Not provided in source)

```

--------------------------------

### POST /api/v1/generate/single/:baseTemplateUuid/:externalUuid

Source: https://pdfdesignapi.com/docs/embedded/api-reference

Generates a PDF for the given base template and external application identifier. Requires a team API token.

```APIDOC
## POST /api/v1/generate/single/:baseTemplateUuid/:externalUuid

### Description
Generates a PDF for the given base template and external application identifier. Requires a team API token.

### Method
POST

### Endpoint
/api/v1/generate/single/:baseTemplateUuid/:externalUuid

### Parameters
#### Path Parameters
- **baseTemplateUuid** (string) - Required - The UUID of the base template.
- **externalUuid** (string) - Required - The external application identifier (not a secret).

### Response
#### Success Response (200)
- **body** (binary) - The generated PDF bytes.

#### Response Example
[PDF binary data]

```

--------------------------------

### POST /api/v1/templates/:templateUuid/validate

Source: https://pdfdesignapi.com/docs/api/validation

Applies the same schema checks without producing a PDF. Use it to validate fixtures in CI, preflight user-entered data, and check integration compatibility before a template promotion.

```APIDOC
## POST /api/v1/templates/:templateUuid/validate

### Description
Applies the same schema checks without producing a PDF. Use it to validate fixtures in CI, preflight user-entered data, and check integration compatibility before a template promotion.

### Method
POST

### Endpoint
/api/v1/templates/:templateUuid/validate

### Parameters
#### Path Parameters
- **templateUuid** (string) - Required - The UUID of the template to validate against.

#### Request Body
- **data** (object) - Required - The payload to validate against the template contract.

### Request Example

curl -X POST "https://pdfdesignapi.com/api/v1/templates/TEMPLATE_UUID/validate" \
  -H "Authorization: Bearer API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":{"customer":{"name":"Example BV"}}}'


### Response
#### Success Response (200)
- **field paths and rules** - Description: Returned field paths and rules to correct the payload or update the template schema.

#### Response Example
(No explicit response example provided in the source.)

```

--------------------------------

### POST /api/v1/templates/:baseTemplateUuid/:externalUuid/validate

Source: https://pdfdesignapi.com/docs/embedded/api-reference

Runs the same data-contract validation as generation without rendering the PDF. Requires a team API token.

```APIDOC
## POST /api/v1/templates/:baseTemplateUuid/:externalUuid/validate

### Description
Runs the same data-contract validation as generation without rendering the PDF. Requires a team API token.

### Method
POST

### Endpoint
/api/v1/templates/:baseTemplateUuid/:externalUuid/validate

### Parameters
#### Path Parameters
- **baseTemplateUuid** (string) - Required - The UUID of the base template.
- **externalUuid** (string) - Required - The external application identifier (not a secret).

### Response
#### Success Response (200)
- **valid** (boolean) - Indicates whether the data contract is valid.

#### Response Example
{
  "valid": true
}

```

--------------------------------

### Create an editor session with the embedded-templates session endpoint

Source: https://pdfdesignapi.com/docs/embedded/sdk-quickstart

Call the session endpoint from trusted server code with a team API token to create an editor session. The response contains a short-lived embed_url whose encrypted capability is stored in the URL fragment and removed by the editor after loading. Never put the team token in browser JavaScript.

```javascript
const endpoint = 'https://pdfdesignapi.com/api/v1/embedded-templates/'
  + baseTemplateUuid + '/' + externalUuid + '/session'
const response = await fetch(
  endpoint,
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.PDFDESIGNAPI_TOKEN,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ expiresInMinutes: 60 }),
  },
)
const { embed_url: embedUrl } = await response.json()
```

--------------------------------

### POST /api/v1/embedded-templates/:baseTemplateUuid/:externalUuid/session

Source: https://pdfdesignapi.com/docs/embedded/api-reference

Creates an embedded editor session for a given base template and external application identifier. Authenticates with a team API token and is idempotent for the template pair.

```APIDOC
## POST /api/v1/embedded-templates/:baseTemplateUuid/:externalUuid/session

### Description
Creates an embedded editor session for a given base template and external application identifier. Authenticates with a team API token and is idempotent for the template pair.

### Method
POST

### Endpoint
/api/v1/embedded-templates/:baseTemplateUuid/:externalUuid/session

### Parameters
#### Path Parameters
- **baseTemplateUuid** (string) - Required - The UUID of the base template.
- **externalUuid** (string) - Required - The external application identifier (not a secret).

#### Request Body
- **expiresInMinutes** (integer) - Optional - Session lifetime in minutes. Accepts 5 through 1440. Defaults to 60.

### Request Example
{
  "expiresInMinutes": 60
}

### Response
#### Success Response (200)
- **capability** (string) - The short-lived encrypted capability required for editor access.

#### Response Example
{
  "capability": "encrypted-capability-string"
}

```

--------------------------------

### curl POST to validation endpoint

Source: https://pdfdesignapi.com/docs/api/validation

Sends a JSON payload to the validation endpoint to check it against the template contract without rendering a PDF. Requires a valid template UUID and API token.

```bash
curl -X POST "https://pdfdesignapi.com/api/v1/templates/TEMPLATE_UUID/validate" \
  -H "Authorization: Bearer API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":{"customer":{"name":"Example BV"}}}'
```
Tokens:
Raw