---
title: "Validate Response-Agent-as-Code YAML"
method: POST
path: "/api/agent-sync/validate"
tags: ["Agents as Code"]
---

# Validate Response-Agent-as-Code YAML

`POST /api/agent-sync/validate`

## Request

- Base URL: `https://app.cotool.ai`
- URL: `https://app.cotool.ai/api/agent-sync/validate`
- Auth: HTTP bearer

Validate Response-Agents-as-Code YAML without syncing it. Runs the same parse, schema, and cross-file checks as the GitOps sync engine, so a CI check stays in step with real sync behavior. Typically used to validate agent files in a pull request before they merge.

**Request.** Post each file as a `{ path, content }` pair. The validator has no access to your repo, so you send the raw file text. Post one file to check it on its own, or a whole directory to also catch cross-file issues like duplicate `sync_key` values and dependency cycles. Include any prompt `.md` files referenced by `systemPrompt.file` so those references resolve.

**Response.** An overall `valid` flag, plus per file an `errors` list (these would block a sync) and a `warnings` list (non-blocking). Warnings are checks that need live workspace state the request cannot see, such as an unprovided `systemPrompt.file` or a reference to an agent that is not in the request.

**Authentication.** Send a bearer token. **GitHub OIDC is the recommended method:** in GitHub Actions, use the [`cotool/validate-agents` Action](/agents/response-agents-as-code#validate-in-ci), which mints a short-lived, repo-scoped token (no stored secret; the repository must be connected for GitOps sync) that grants validate-only access. A Cotool API key with the `tool.manage` permission also works for non-GitHub or self-hosted CI, but it is long-lived and inherits the full permissions of the user who created it, so prefer OIDC and treat any API key as a sensitive, least-privilege secret.

## Request body

- object
  - `files` object[], required: The files to validate. Post one to check it on its own, or a whole directory to also catch cross-file issues. Include any SKILL.md files (under skillsPath) that agents reference, and any prompt .md files referenced by systemPrompt.file; a skill reference whose SKILL.md is not in the request is a warning, not a failure.
    - `path` string, required: Repo-relative file path, e.g. "agents/triage.yaml". A .yaml/.yml file is validated as an agent; any other file (such as a .md) is treated as a referenced systemPrompt.file. Also used to identify files in cross-file checks.
    - `content` string, required: The full raw text of the file. The validator has no repo access, so you send the file contents yourself.
  - `skillsPath` string: Directory holding standalone SKILL.md skill definitions (default "cotool/skills"). Must match your sync config's skills path so skill files in the request are discovered.

## Response `200`

Successful response

- object
  - `valid` boolean, required: True when every returned result validated with no errors.
  - `fileCount` number, required: Number of validation result rows returned.
  - `agentCount` number, required: Number of schema-valid, graph-clean agents found.
  - `results` object[], required
    - `path` string, required
    - `valid` boolean, required: True when this file has no error-severity diagnostics.
    - `errors` object[], required: Issues that would make this file fail to sync.
      - `code` 'yaml_error' | 'schema_error' | 'fetch_error', required: Kind of issue.
      - `message` string, required: Human-readable explanation (includes the field path for schema errors).
    - `warnings` object[], required: Non-blocking issues that depend on live workspace state the validator cannot see, such as an unresolved systemPrompt.file or a reference to an agent not in the request.
      - `code` 'yaml_error' | 'schema_error' | 'fetch_error', required: Kind of issue.
      - `message` string, required: Human-readable explanation (includes the field path for schema errors).

## Other responses

- `400`: Bad request — input validation failed or the request was malformed
- `401`: Unauthorized — missing or invalid API key / session
- `403`: Forbidden — the authenticated user lacks the required permissions
- `500`: Internal server error

---

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