Skip to main content

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

Last updated 3 min read

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:

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.

{
  "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 articles