> Documentation index for AI agents: https://docs.pagerduty.com/llms.txt

# Create a template

`POST https://api.pagerduty.com/templates`

Create a new template

Scoped OAuth requires: `templates.write`

## Authorization

- **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=<API_KEY>`

## Request body (`application/json`) — required

| Field | Type | Required | Description |
|---|---|---|---|
| `template` | object | yes |  |
| `template.template_type` | string |  | The type of template (`status_update` is the only supported template at this time) One of: `status_update`. |
| `template.name` | string |  | The name of the template. |
| `template.description` | string \| null |  | Description of the template. |
| `template.templated_fields` | object |  |  |
| `template.templated_fields.email_subject` | string \| null |  | The subject of the e-mail. |
| `template.templated_fields.email_body` | string \| null |  | The HTML body of the e-mail message. |
| `template.templated_fields.message` | string \| null |  | The short-message of the template (SMS, Push notification, Slack, etc) |

Example: Request Example

```json
{
  "template": {
    "description": "Sample template description",
    "templated_fields": {
      "email_body": "<div> sample </div>",
      "email_subject": "Sample email Subject",
      "message": "Sample SMS message"
    },
    "name": "Sample Template",
    "template_type": "status_update"
  }
}
```

## Response 201

Template successfully created

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `template` | object | yes |  |
| `template.template_type` | string |  | The type of template (`status_update` is the only supported template at this time) One of: `status_update`. |
| `template.name` | string |  | The name of the template. |
| `template.description` | string \| null |  | Description of the template. |
| `template.templated_fields` | object |  |  |
| `template.templated_fields.email_subject` | string \| null |  | The subject of the e-mail. |
| `template.templated_fields.email_body` | string \| null |  | The HTML body of the e-mail message. |
| `template.templated_fields.message` | string \| null |  | The short-message of the template (SMS, Push notification, Slack, etc) |
| `template.id` | string |  | Read-only. |
| `template.summary` | string \| null |  | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. |
| `template.self` | string \| null (url) |  | the API show URL at which the object is accessible. Read-only. |
| `template.html_url` | string \| null (url) |  | a URL at which the entity is uniquely displayed in the Web app. Read-only. |
| `template.type` | string |  | One of: `template`. |
| `template.created_by` | one of: object \| object |  | User/Account object reference of the creator. |
| `template.created_by.id` | string | yes | (option 1) Read-only. |
| `template.created_by.summary` | string \| null |  | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. |
| `template.created_by.type` | string | yes | (option 1) One of: `user_reference`. |
| `template.created_by.self` | string \| null (url) |  | (option 1) the API show URL at which the object is accessible. Read-only. |
| `template.created_by.html_url` | string \| null (url) |  | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. |
| `template.created_by.id` | string | yes | (option 2) Read-only. |
| `template.created_by.summary` | string \| null |  | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. |
| `template.created_by.type` | string | yes | (option 2) One of: `account_reference`. |
| `template.created_by.self` | string \| null (url) |  | (option 2) the API show URL at which the object is accessible. Read-only. |
| `template.created_by.html_url` | string \| null (url) |  | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. |
| `template.updated_by` | one of: object \| object |  | User/Account object reference of the updator. |
| `template.updated_by.id` | string | yes | (option 1) Read-only. |
| `template.updated_by.summary` | string \| null |  | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. |
| `template.updated_by.type` | string | yes | (option 1) One of: `user_reference`. |
| `template.updated_by.self` | string \| null (url) |  | (option 1) the API show URL at which the object is accessible. Read-only. |
| `template.updated_by.html_url` | string \| null (url) |  | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. |
| `template.updated_by.id` | string | yes | (option 2) Read-only. |
| `template.updated_by.summary` | string \| null |  | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. |
| `template.updated_by.type` | string | yes | (option 2) One of: `account_reference`. |
| `template.updated_by.self` | string \| null (url) |  | (option 2) the API show URL at which the object is accessible. Read-only. |
| `template.updated_by.html_url` | string \| null (url) |  | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. |

Example: Response Example

```json
{
  "template": {
    "created_at": "2022-08-19T13:46:22Z",
    "created_by": {
      "id": "PF9KMXH",
      "self": "https://api.pagerduty.com/users/PF9KMXH",
      "type": "user_reference"
    },
    "description": "Sample template description",
    "templated_fields": {
      "email_body": "<div> sample </div>",
      "email_subject": "Sample email Subject",
      "message": "Sample SMS message"
    },
    "id": "PCCR863",
    "name": "Sample Template",
    "self": "https://api.pagerduty.com/templates/PCCR863",
    "template_type": "status_update",
    "type": "template",
    "updated_at": "2022-08-19T13:46:22Z",
    "updated_by": {
      "id": "PF9KMXH",
      "self": "https://api.pagerduty.com/users/PF9KMXH",
      "type": "user_reference"
    }
  }
}
```

## Response 400

Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Response 402

Account does not have the abilities to perform the action. Please review the response for the required abilities.
You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Response 403

Caller is not authorized to view the requested resource.
While your authentication is valid, the authenticated user or token does not have permission to perform this action.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Response 500

Internal Server Error the PagerDuty server experienced an error.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Developer Agreement

Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement).