## List task templates

`GET /v1/task-templates`

Returns one page of task templates. The filter and the field set are specified with Bitrix24 parameters in `params`.

## Parameters

| Parameter | Type | Required | Default | Description |
|----------|-----|:-----:|-----------|----------|
| `params` (query) | string | no | — | URL-encoded JSON object of Bitrix24 parameters: `filter` — selection conditions, `select` — the field set. Field names are not converted. Example before encoding: `{"filter":{"ID":75},"select":["ID","TITLE"]}` |
| `start` (query) | number | no | `0` | Page offset. For the next page, pass `meta.next` from the previous response |

The method accepts no other query parameters.

**Pagination.** The response is one page. While the response contains `meta.next`, request the next page with `start` equal to `meta.next`. Pages are not loaded automatically.

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/task-templates" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/task-templates" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/task-templates', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
const templates = Object.values(data.task_templates)
console.log('Templates:', templates.map((t) => `${t.ID}: ${t.TITLE}`))
console.log('Next page:', meta.next ?? 'none')
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/task-templates', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` on success |
| `data.task_templates` | object | Templates on the page: the key is the template ID, the value is the template. If there are no templates, the field is an empty array `[]` |
| `data.task_templates.<id>.ID` | number | Template ID |
| `data.task_templates.<id>.TITLE` | string | Template title |
| `data.task_templates.<id>.DESCRIPTION` | string \| null | Task description |
| `data.task_templates.<id>.PRIORITY` | string | Priority: `0` — low, `1` — normal, `2` — high |
| `data.task_templates.<id>.CREATED_BY` | string | Creator ID. Get: [`GET /v1/users/:id`](/docs/entities/users/get) |
| `data.task_templates.<id>.RESPONSIBLE_ID` | number | Responsible person ID. If `RESPONSIBLE_ID` is passed in `select`, it comes as a string. Get: [`GET /v1/users/:id`](/docs/entities/users/get) |
| `data.task_templates.<id>.RESPONSIBLES` | array | Responsible person IDs. List: [`GET /v1/users`](/docs/entities/users/list) |
| `data.task_templates.<id>.ACCOMPLICES` | array | Participant IDs. List: [`GET /v1/users`](/docs/entities/users/list) |
| `data.task_templates.<id>.AUDITORS` | array | Observer IDs. List: [`GET /v1/users`](/docs/entities/users/list) |
| `data.task_templates.<id>.DEPENDS_ON` | array | IDs of the tasks the future task depends on. Get: [`GET /v1/tasks/:id`](/docs/entities/tasks/get) |
| `data.task_templates.<id>.*` | — | Other template fields, including user fields `UF_*`. See [Get a task template](/docs/entities/tasks/templates-get) |
| `meta.total` | number | Number of templates matching the filter |
| `meta.next` | number | `start` of the next page. Absent on the last page |

When a single template is retrieved, `ID`, `RESPONSIBLE_ID` and the member lists come as strings.

## Response example

The main template fields are shown:

```json
{
  "success": true,
  "data": {
    "task_templates": {
      "75": {
        "ID": 75,
        "TITLE": "Weekly status report",
        "DESCRIPTION": null,
        "PRIORITY": "1",
        "CREATED_BY": "1295",
        "GROUP_ID": null,
        "RESPONSIBLE_ID": 1295,
        "ACCOMPLICES": [],
        "AUDITORS": [],
        "RESPONSIBLES": [
          1295
        ],
        "DEPENDS_ON": []
      }
    }
  },
  "meta": {
    "total": 1
  }
}
```

## Error response example

400 — a query parameter other than `params` and `start` was passed:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Only params and start are supported"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | A query parameter other than `params` and `start` was passed. Message `Only params and start are supported` |
| 400 | `INVALID_PARAMS` | `params` is not a JSON object. Message `params must be a JSON object` |
| 400 | `INVALID_PARAMS` | `start` is not a non-negative integer. Message `start must be a non-negative integer` |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens |
| 403 | `SCOPE_DENIED` | The key does not have the `task` scope |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the call. The text is in `error.message` |
| 429 | `RATE_LIMITED` | Request rate exceeded. The effective cap is in the `x-ratelimit-limit` header |

Full list of common API errors — [Errors](/docs/errors).

## See also

- [Task templates](/docs/entities/tasks/templates)
- [Create a task template](/docs/entities/tasks/templates-create)
- [Get a task template](/docs/entities/tasks/templates-get)
- [Update a task template](/docs/entities/tasks/templates-update)