> This page is optimized for agents. Use the linked Markdown pages and llms.txt indexes for related API content.

# Generate a document from a template

> Generate a document from a template

- Product: Document
- Section: document
- Snapshot: v0.1.0+8bf142be
- Method: `POST`
- Path: `/v1/abilities/document.generate`

## Request body

Required: yes  
Content types: `application/json`  

### `input`

Type: `DocumentGenerateInput`  
Required: yes  

#### `template`

Type: `string`  
Required: yes  

#### `data`

Type: `object`  
Required: yes  

#### `format`

Type: `string`  
Required: no  
Allowed values: `pdf`, `docx`, `md`  
Default: `pdf`  

### `context`

Type: `CallContext`  
Required: no  

Optional call context. The tenant always comes from the credential: `tenantId` is honoured only by a credential allowed to address sub-tenants, and then nests under the credential's own tenant.

#### `tenantId`

Type: `string`  
Required: no  

Sub-tenant to act for (sub-tenant credentials only).

#### `runId`

Type: `string`  
Required: no  

The trust run (from trust.preflight) this call executes under.

#### `verticalId`

Type: `string`  
Required: no  

Vertical to attribute created records to.

## Execute with curl

```bash
curl -X POST https://substrate.sloelabs.com/v1/abilities/document.generate \
    -H "Authorization: Bearer $SLOE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{"input":{"template":"<template>","data":{}}}'
```

## Execute with JavaScript

```js
const response = await fetch("https://substrate.sloelabs.com/v1/abilities/document.generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SLOE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "input": {
      "template": "<template>",
      "data": {}
    }
  }),
});
const { ok, result, error } = await response.json();
```

## Execute with Python

```python
import os
import requests

response = requests.post(
    "https://substrate.sloelabs.com/v1/abilities/document.generate",
    headers={"Authorization": f"Bearer {os.environ['SLOE_API_KEY']}"},
    json={
        "input": {
            "template": "<template>",
            "data": {},
        },
    },
)
print(response.json())
```

## Responses

### Response `200`

Category: success  

The ability ran.

#### `application/json`

Documentation payload key: `result`  

##### Generated example

```json
{
  "ok": true,
  "ability": "ability",
  "duration": 0
}
```

##### Schema

###### AbilityResult

Type: `AbilityResult`  

###### `ok`

Type: `boolean`  
Required: yes  

###### `ability`

Type: `string`  
Required: yes  

The ability that ran.

###### `result`

Type: `unknown`  
Required: yes  

The ability's return value. Its shape depends on the ability.

###### `duration`

Type: `number`  
Required: yes  

Server-side execution time, in milliseconds.

### Response `400`

Category: client-error  

The body is missing `input`, or `input` fails the ability's schema (`details` holds the validation errors).

#### `application/json`

##### Generated example

```json
{
  "ok": true,
  "error": "error",
  "ability": "ability",
  "reason": "reason",
  "details": [
    {}
  ],
  "retryAfterMs": 0
}
```

##### Schema

###### ErrorResponse

Type: `ErrorResponse`  

###### `ok`

Type: `boolean`  
Required: yes  

###### `error`

Type: `string`  
Required: yes  

###### `ability`

Type: `string`  
Required: no  

###### `reason`

Type: `string`  
Required: no  

###### `details`

Type: `object[]`  
Required: no  

JSON Schema validation errors.

###### object

Type: `object`  

###### `code`

Type: `unknown`  
Required: no  

A machine-readable error code, when the ability sets one.

###### `retryAfterMs`

Type: `number`  
Required: no  

### Response `401`

Category: client-error  

No bearer credential, or one the substrate does not recognise.

#### `application/json`

##### Generated example

```json
{
  "ok": true,
  "error": "error",
  "ability": "ability",
  "reason": "reason",
  "details": [
    {}
  ],
  "retryAfterMs": 0
}
```

##### Schema

###### ErrorResponse

Type: `ErrorResponse`  

###### `ok`

Type: `boolean`  
Required: yes  

###### `error`

Type: `string`  
Required: yes  

###### `ability`

Type: `string`  
Required: no  

###### `reason`

Type: `string`  
Required: no  

###### `details`

Type: `object[]`  
Required: no  

JSON Schema validation errors.

###### object

Type: `object`  

###### `code`

Type: `unknown`  
Required: no  

A machine-readable error code, when the ability sets one.

###### `retryAfterMs`

Type: `number`  
Required: no  

### Response `403`

Category: client-error  

The credential is valid, but its scope does not include this ability.

#### `application/json`

##### Generated example

```json
{
  "ok": true,
  "error": "error",
  "ability": "ability",
  "reason": "reason",
  "details": [
    {}
  ],
  "retryAfterMs": 0
}
```

##### Schema

###### ErrorResponse

Type: `ErrorResponse`  

###### `ok`

Type: `boolean`  
Required: yes  

###### `error`

Type: `string`  
Required: yes  

###### `ability`

Type: `string`  
Required: no  

###### `reason`

Type: `string`  
Required: no  

###### `details`

Type: `object[]`  
Required: no  

JSON Schema validation errors.

###### object

Type: `object`  

###### `code`

Type: `unknown`  
Required: no  

A machine-readable error code, when the ability sets one.

###### `retryAfterMs`

Type: `number`  
Required: no  

### Response `404`

Category: client-error  

No ability has this id.

#### `application/json`

##### Generated example

```json
{
  "ok": true,
  "error": "error",
  "ability": "ability",
  "reason": "reason",
  "details": [
    {}
  ],
  "retryAfterMs": 0
}
```

##### Schema

###### ErrorResponse

Type: `ErrorResponse`  

###### `ok`

Type: `boolean`  
Required: yes  

###### `error`

Type: `string`  
Required: yes  

###### `ability`

Type: `string`  
Required: no  

###### `reason`

Type: `string`  
Required: no  

###### `details`

Type: `object[]`  
Required: no  

JSON Schema validation errors.

###### object

Type: `object`  

###### `code`

Type: `unknown`  
Required: no  

A machine-readable error code, when the ability sets one.

###### `retryAfterMs`

Type: `number`  
Required: no  

### Response `429`

Category: client-error  

Too many requests for this credential. `retryAfterMs` says when to retry.

#### `application/json`

##### Generated example

```json
{
  "ok": true,
  "error": "error",
  "ability": "ability",
  "reason": "reason",
  "details": [
    {}
  ],
  "retryAfterMs": 0
}
```

##### Schema

###### ErrorResponse

Type: `ErrorResponse`  

###### `ok`

Type: `boolean`  
Required: yes  

###### `error`

Type: `string`  
Required: yes  

###### `ability`

Type: `string`  
Required: no  

###### `reason`

Type: `string`  
Required: no  

###### `details`

Type: `object[]`  
Required: no  

JSON Schema validation errors.

###### object

Type: `object`  

###### `code`

Type: `unknown`  
Required: no  

A machine-readable error code, when the ability sets one.

###### `retryAfterMs`

Type: `number`  
Required: no  

### Response `501`

Category: server-error  

The ability is declared but no handler is wired.

#### `application/json`

##### Generated example

```json
{
  "ok": true,
  "error": "error",
  "ability": "ability",
  "reason": "reason",
  "details": [
    {}
  ],
  "retryAfterMs": 0
}
```

##### Schema

###### ErrorResponse

Type: `ErrorResponse`  

###### `ok`

Type: `boolean`  
Required: yes  

###### `error`

Type: `string`  
Required: yes  

###### `ability`

Type: `string`  
Required: no  

###### `reason`

Type: `string`  
Required: no  

###### `details`

Type: `object[]`  
Required: no  

JSON Schema validation errors.

###### object

Type: `object`  

###### `code`

Type: `unknown`  
Required: no  

A machine-readable error code, when the ability sets one.

###### `retryAfterMs`

Type: `number`  
Required: no  

### Response `default`

Category: default  

The ability failed. The message is sanitized; a 5xx may be a transient upstream failure.

#### `application/json`

##### Generated example

```json
{
  "ok": true,
  "error": "error",
  "ability": "ability",
  "reason": "reason",
  "details": [
    {}
  ],
  "retryAfterMs": 0
}
```

##### Schema

###### ErrorResponse

Type: `ErrorResponse`  

###### `ok`

Type: `boolean`  
Required: yes  

###### `error`

Type: `string`  
Required: yes  

###### `ability`

Type: `string`  
Required: no  

###### `reason`

Type: `string`  
Required: no  

###### `details`

Type: `object[]`  
Required: no  

JSON Schema validation errors.

###### object

Type: `object`  

###### `code`

Type: `unknown`  
Required: no  

A machine-readable error code, when the ability sets one.

###### `retryAfterMs`

Type: `number`  
Required: no  

## Related representations

- [Human documentation](/api/document/methods/generate/)
- [curl Markdown](/api/document/methods/generate.md?lang=curl)
- [JavaScript Markdown](/api/document/methods/generate.md?lang=fetch)
- [Python Markdown](/api/document/methods/generate.md?lang=python)
- [site llms.txt](/api/llms.txt)
- [product llms.txt](/api/document/llms.txt)
- [snapshot llms.txt](/api/document/llms.txt)