---
title: "Validate Template"
method: POST
path: "/agent-templates/validate"
tags: ["Workflows"]
---

# Validate Template

`POST /agent-templates/validate`

## Request

- Base URL: `/api` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/agent-templates/validate`
- Auth: API key in header `Authorization`

## Query parameters

- `project_id` string, uuid, nullable

## Request body

- TemplateValidateRequest
  - `source` union, required
    - InternalTemplateSource
      - `kind` 'internal'
      - `key` string, required
    - UploadTemplateSource: A zip the user uploaded as a staged session attachment. Attachments are immutable once ready (the row keeps a content digest), so the reference itself pins the bytes.
      - `kind` 'upload'
      - `staging_session_id` string, required
      - `attachment_id` string, uuid, required
    - SessionFileTemplateSource: A zip in a session's working directory, such as one an agent wrote in chat. The file is mutable, so load requires the pin that validation returned and rejects bytes that no longer match it.
      - `kind` 'session_file'
      - `session_id` string, required
      - `path` string, required
      - `pin` TemplateSourcePin
        - `version` string, required
        - `digest` string, required
    - GitHubTemplateSource: A package directory in a public GitHub repository at one exact commit. Branches, tags and abbreviated SHAs are rejected, never resolved: the caller resolves a mutable revision before loading, so the backend fetches only immutable content.
      - `kind` 'github'
      - `repo_url` string, required
      - `commit` string, required
      - `path` string, required
  - `pin` TemplateSourcePin
    - `version` string, required
    - `digest` string, required

## Response `200`

Successful Response

- TemplateValidationResult
  - `valid` boolean, required
  - `version` string, nullable
  - `digest` string, nullable
  - `supported_schema_versions` string[], required
  - `issues` TemplateValidationIssue[]
    - `code` string, required
    - `path` string, nullable
    - `field` string, nullable
    - `message` string, required
    - `next_step` string, nullable

## Other responses

- `403`: Forbidden
- `404`: Template source not found
- `422`: Invalid request

## Changes

- **2026-10-04** `c3a5d853c4a2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agenta-ai/apis/agenta-api/changes/agent-templates/validate/post.md)

---

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