---
title: "List templates"
method: GET
path: "/public-api/v1/templates"
tags: ["Templates"]
---

# List templates

`GET /public-api/v1/templates`

## Request

- Base URL: `https://app.hellobonsai.com`
- URL: `https://app.hellobonsai.com/public-api/v1/templates`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://app.hellobonsai.com/oauth/authorize`
    - Token URL: `https://app.hellobonsai.com/oauth/token`
  - HTTP bearer

Lists the templates you can start new work from, a page at a time.

`filter[type]` is required and today accepts only `Doc`, the document
templates. It is required rather than assumed so that adding a type
later cannot change what an existing call returns. Each type brings its
own extra fields — for `Doc` that is `roles` — so a response carries the
fields every template has plus the ones that type adds.

Two sources come back in one list, your own first: templates your
account has saved (`source: own`) and Bonsai's library
(`source: library`). Read `source` to prefer your own branded template
over a generic one when both match.

Only templates you could actually use appear here: published ones, in a
region that applies to your account, built in the current editor.
Unpublished drafts stay in the Templates tab in Bonsai.

## Filtering

- `filter[type]` — required. `Doc`, the kind of template to list.
- `filter[name]` — partial, case-insensitive match on the template name.
- `filter[source]` — `own`, `library` or `all`. Defaults to `all`.
- `filter[category]` — one or more category names, comma-separated.
  Your own templates are filed under `My Templates`. List the names
  `GET /public-api/v1/template_categories?filter[type]=Doc` returns
  under `kind: category`.
- `filter[industry]` — one or more industry names, comma-separated.
  List the names `GET /public-api/v1/template_categories?filter[type]=Doc`
  returns under `kind: industry`.
- `filter[region]` — `USA`, `CAN`, `GBR` or `AUS`. Defaults to your
  account's country. Templates that apply everywhere are always
  included, whichever region you ask for.

## Query parameters

- `page[number]` integer
- `page[size]` integer
- `filter[type]` 'Doc', required
- `filter[name]` string
- `filter[source]` 'own' | 'library' | 'all'
- `filter[category]` string
- `filter[industry]` string
- `filter[region]` 'USA' | 'CAN' | 'GBR' | 'AUS'

## Response `200`

A page of templates, your own first.

- object
  - `data` object[], required
    - `id` string, uuid, required: Unique identifier for the template. Stable across requests, so you can store it and recognise the same template later.
    - `name` string, nullable, required: Template name, as it appears in the gallery.
    - `region` string, nullable, required: The region whose conventions the template is written for, or `null` when it applies everywhere.
    - `updated_at` string, date-time, required: When the template was last changed.
    - `source` string, required: Where the template comes from: `own` for one your account saved, `library` for one of Bonsai's. Prefer your own when both match.
    - `categories` string[], required: Category names the template is filed under, drawn from the `category` rows of `/public-api/v1/template_categories?filter[type]=Doc`. Your own templates are filed under `My Templates`.
    - `industries` string[], required: Industry names the template is aimed at, drawn from the `industry` rows of `/public-api/v1/template_categories?filter[type]=Doc`.
    - `url` string, nullable, required: Absolute link to open the template in the Bonsai app, or `null` when your account cannot edit it. Library templates are edited by Bonsai, so theirs is `null` unless your account curates the library; your own is `null` when your role cannot edit documents.
    - `roles` DocRole[], required: The parts a document made from this template expects somebody to fill.
      - `name` string, nullable, required: Role name as the document author wrote it.
      - `kind` 'sender' | 'receiver' | 'cc', required: What the role does: `sender` issues the document, `receiver` signs it, `cc` is copied in.
  - `meta` PaginatedMeta, required: Metadata returned alongside every list response.
    - `request_id` string, required: Identifier for this request. Quote it when contacting support about a specific call.
    - `pagination` Pagination, required: Where the returned page sits in the full result set.
      - `page` integer, required: The page that was returned.
      - `page_size` integer, required: How many records this page can hold.
      - `has_more` boolean, required: Whether at least one more page follows this one. Keep incrementing `page[number]` while this is `true`.

## Other responses

- `400`: `filter[type]` is missing or unsupported, a filter key is unknown, or `filter[source]` / `filter[region]` is not one of the listed values.
- `401`: The access token is missing, expired or invalid.
- `403`: The account cannot see documents, either through its plan or its role permissions.
- `429`: Rate limit exceeded. Wait at least `Retry-After` seconds before trying again.

---

[API](https://skmtc.dev/hellobonsai/apis/bonsai-api.md) - [All operations](https://skmtc.dev/hellobonsai/apis/bonsai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hellobonsai/apis/bonsai-api/revisions/abf12ed6a8d3?raw)