---
title: "How do I create or update a template using an external key?"
answer: "Create and manage templates programmatically using the `PUT /api/v2/llm_request_templates/by_key/{external_key}` endpoint. This allows you to assign a stable, user-defined external key to a template. Templates created this way are 'declared' and bypass regex matching. Instead, you associate logs with them by providing the external key in your log requests."
category: "Logs \u0026 API"
tags: []
published: 2026-10-23T17:23:11Z
updated: 2026-10-23T17:22:23Z
canonical_url: https://coolhandlabs.com/help/create-update-template-with-external-key
index_url: https://coolhandlabs.com/help.md
---

# How do I create or update a template using an external key?

Create and manage templates programmatically using the `PUT /api/v2/llm_request_templates/by_key/{external_key}` endpoint. This allows you to assign a stable, user-defined external key to a template. Templates created this way are 'declared' and bypass regex matching. Instead, you associate logs with them by providing the external key in your log requests.


Most Coolhand templates are defined by their prompt patterns, which Coolhand uses to match incoming logs. However, if you already know which template a log belongs to, you can use a **declared template** to skip regex matching entirely.

Declared templates are templates that do not have prompt patterns. Instead, they are identified by a stable, user-defined `external_key`. You can create and manage these templates programmatically, making them ideal for use in your CI/CD pipeline or for any situation where you want to manage your templates as code.

## Creating and Updating Declared Templates

To create or update a declared template, send a `PUT` request to the `/api/v2/llm_request_templates/by_key/{external_key}` endpoint. The `external_key` can be any string you choose, up to 255 characters.

If the `external_key` is new, a new template will be created. If the key already exists, the existing template will be updated.

Here's an example of how to create a new template with the external key `my-app:parser`:

```bash
curl -X PUT \
  https://app.coolhand.io/api/v2/llm_request_templates/by_key/my-app:parser \
  -H "X-API-Key: <YOUR_PRIVATE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "My App: Parser",
        "workload_key": "my-app"
      }'
```

**Parameters:**

*   `name` (optional): The display name of the template. If not provided, the name will default to the `external_key`.
*   `workload_key` (required on creation): The key of the workload this template belongs to. If the workload doesn't exist, it will be created.
*   `workload_id` (required on creation): The ID of the workload this template belongs to. You can use this instead of `workload_key`.

## Associating Logs with a Declared Template

To associate a log with a declared template, include a `declared` object in your `POST /api/v2/llm_request_logs` request. In the `declared` object, specify the template's `external_key` or `id`.

```json
{
  "llm_request_log": {
    "provider": "openai",
    "model": "gpt-4",
    "prompt": "...",
    "response": "...",
    "declared": {
      "template": {
        "key": "my-app:parser"
      }
    }
  }
}
```

When Coolhand receives a log with a `declared` template, it will immediately associate the log with that template, skipping the regex matching process entirely.

## Benefits of Using Declared Templates

*   **Guaranteed Matching:** Avoids the ambiguity and potential errors of regex matching.
*   **Manage Templates as Code:** Programmatically create, update, and manage your templates.
*   **Improved Performance:** Skips the overhead of regex matching.


---

Related:
- [What every field on an LLM request log means](https://coolhandlabs.com/help/llm-request-log-fields.md)
- [When should I use batch requests?](https://coolhandlabs.com/help/how-to-use-batch-requests.md)
- [LLMs and System One models: what's different, and when to use which](https://coolhandlabs.com/help/llms-vs-system-one-models.md)
- [How do I list and analyze my workloads using the API?](https://coolhandlabs.com/help/list-and-analyze-workloads-api.md)

[← All help articles](https://coolhandlabs.com/help.md) · [Logs & API](https://coolhandlabs.com/help/category/logs-and-api.md)