# Templates

The AI team templates your organization owns.



{/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */}

<ApiEndpoint>
  <ApiEndpointMain>
    ## List templates [#list-templates]

    <ApiEndpointHeader method="GET" path="/v1/templates" scope="templates:read" />

    <ApiParams title="Query parameters">
      <ApiParam name="limit" type="integer">
        How many objects to return, 1 to 100. Default 20.
      </ApiParam>

      <ApiParam name="starting_after" type="string">
        Return objects older than this id (the next page).
      </ApiParam>

      <ApiParam name="ending_before" type="string">
        Return objects newer than this id (the previous page).
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a list of [Template](#template) objects.

    <ApiParams title="Responses">
      <ApiParam name="200">
        A page of templates.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/templates \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/templates', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/templates",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "list",
      "data": [
        {
          "object": "template",
          "id": "tpl_UdI5hI7JqIj0RY89wGmAGU",
          "name": "Research desk",
          "description": "A research team with a market analyst and a weekly brief.",
          "version": "1.2.0",
          "engine": "claude",
          "origin": "snapshot",
          "revision": 3,
          "created_at": "2026-08-30T17:02:45.000Z"
        }
      ],
      "has_more": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get a template [#get-a-template]

    <ApiEndpointHeader method="GET" path="/v1/templates/{template_id}" scope="templates:read" />

    <ApiParams title="Path parameters">
      <ApiParam name="template_id" type="string" required="true">
        A template id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [Template](#template) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The template.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/templates/tpl_UdI5hI7JqIj0RY89wGmAGU \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/templates/tpl_UdI5hI7JqIj0RY89wGmAGU', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/templates/tpl_UdI5hI7JqIj0RY89wGmAGU",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "template",
      "id": "tpl_UdI5hI7JqIj0RY89wGmAGU",
      "name": "Research desk",
      "description": "A research team with a market analyst and a weekly brief.",
      "version": "1.2.0",
      "engine": "claude",
      "origin": "snapshot",
      "revision": 3,
      "created_at": "2026-08-30T17:02:45.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

## Objects [#objects]

<ApiEndpoint>
  <ApiEndpointMain>
    ### Template [#template]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="id" type="string" />

      <ApiParam name="name" type="string" />

      <ApiParam name="description" type="string" />

      <ApiParam name="version" type="string" />

      <ApiParam name="engine" type="string" />

      <ApiParam name="origin" type="string" />

      <ApiParam name="revision" type="integer" />

      <ApiParam name="created_at" type="string (date-time)" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The Template object"
    {
      "object": "template",
      "id": "tpl_UdI5hI7JqIj0RY89wGmAGU",
      "name": "Research desk",
      "description": "A research team with a market analyst and a weekly brief.",
      "version": "1.2.0",
      "engine": "claude",
      "origin": "snapshot",
      "revision": 3,
      "created_at": "2026-08-30T17:02:45.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>
