Rendering

The /rendering endpoints let you render markdown into pdf or docx using async jobs.

Supported input modes:

objectId: render an existing markdown content object
content: render inline markdown (useful for workflow message exports)

Start Rendering Job

Endpoint: /rendering/jobs

Method: POST

Requirements: User must have content:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	`application/json`

Input Parameters

Parameter	Data Type	Description
`format`	`"pdf" \| "docx"`	(Required) Output format.
`objectId`	`string`	Object ID to render. Mutually exclusive with `content`.
`content`	`string`	Inline markdown content to render. Mutually exclusive with `objectId`.
`title`	`string`	Optional document title.
`templateUrl`	`string`	Optional URL for custom template/reference doc.
`templateLogoUrl`	`string`	Optional studio-hosted logo URL passed as `logo-path` to PDF templates.
`useDefaultTemplate`	`boolean`	Optional. Use Vertesia default template (PDF default is true).
`pandocOptions`	`string[]`	Optional extra pandoc options. TOC is added by default for PDF and DOCX; use `["--toc=false"]` to disable.
`artifactRunId`	`string`	Optional run ID for resolving `artifact:`/`image:` URLs.
`metadata`	`object`	Optional PDF metadata (`documentId`, `agentName`, `agentRunId`, `subtitle`, `author`, `date`).

Validation

Provide exactly one of objectId or content.
Providing neither or both returns 400.

Example Request (objectId)

{
  "objectId": "<OBJECT_ID>",
  "format": "pdf",
  "title": "Investment Memo"
}

Example Request (inline content)

{
  "content": "# Workflow Message Export\n\nRendered from inline markdown.",
  "format": "docx",
  "title": "Message Export"
}

Example Response

{
  "workflow_id": "render:acc123:prj456:inline:pdf:2d83...",
  "workflow_run_id": "f8db0a2c-...",
  "status": 1,
  "format": "pdf"
}

Status codes use WorkflowExecutionStatus:

1: RUNNING
2: COMPLETED
3: FAILED
4: CANCELED
5: TERMINATED
7: TIMED_OUT

Get Rendering Job Status

Endpoint: /rendering/jobs/status

Method: GET

Requirements: User must have content:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Query Parameters

Parameter	Data Type	Description
`workflow_id`	`string`	(Required) Workflow ID from start response.
`workflow_run_id`	`string`	(Required) Workflow run ID from start response.

Running Response

{
  "workflow_id": "render:acc123:prj456:...",
  "workflow_run_id": "f8db0a2c-...",
  "status": 1
}

Completed Response

{
  "workflow_id": "render:acc123:prj456:...",
  "workflow_run_id": "f8db0a2c-...",
  "status": 2,
  "downloadUrl": "https://storage.googleapis.com/...",
  "fileUri": "gs://bucket/path/output.pdf"
}

Failed Response

{
  "workflow_id": "render:acc123:prj456:...",
  "workflow_run_id": "f8db0a2c-...",
  "status": 3,
  "error": "Failed to render document: ..."
}

Code Examples

Rendering Jobs

# Start
START_RESPONSE=$(curl --location --request POST \
  'https://api.vertesia.io/api/v1/rendering/jobs' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "objectId": "<OBJECT_ID>",
    "format": "pdf"
  }')

WORKFLOW_ID=$(echo "$START_RESPONSE" | jq -r '.workflow_id')
RUN_ID=$(echo "$START_RESPONSE" | jq -r '.workflow_run_id')

# Poll
while true; do
  STATUS_RESPONSE=$(curl --location --request GET \
    "https://api.vertesia.io/api/v1/rendering/jobs/status?workflow_id=${WORKFLOW_ID}&workflow_run_id=${RUN_ID}" \
    --header 'Authorization: Bearer <YOUR_JWT_TOKEN>')

  STATUS=$(echo "$STATUS_RESPONSE" | jq -r '.status')
  if [ "$STATUS" = "2" ]; then
    echo "$STATUS_RESPONSE" | jq -r '.downloadUrl'
    break
  fi

  if [ "$STATUS" = "3" ] || [ "$STATUS" = "4" ] || [ "$STATUS" = "5" ] || [ "$STATUS" = "7" ]; then
    echo "Rendering failed: $(echo "$STATUS_RESPONSE" | jq -r '.error')"
    break
  fi

  sleep 1.5
done