> ## Documentation Index > Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt > Use this file to discover all available pages before exploring further. # Validate Response-Agent-as-Code YAML > 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. ## OpenAPI ````yaml https://app.cotool.ai/api/docs/openapi.json post /api/agent-sync/validate openapi: 3.1.0 info: title: Cotool API version: 1.0.0 description: >- # Cotool API Documentation The Cotool API allows you to interact with the Cotool platform programmatically, enabling you to build powerful integrations and automate your workflows. ## Getting an API Key Follow these steps to generate your API key: 1. **Log in** to the Cotool web interface 2. **Navigate** to `/settings/api-keys` 3. **Click** "Generate Key" 4. **Copy and store** your API key securely ⚠️ *It won't be shown again* ## API Key Authentication For programmatic access and integrations, use your API key with the Authorization header: ```http Authorization: Bearer your_api_key_here ``` ```bash curl -X GET "https://app.cotool.ai/api/endpoint" \ -H "Authorization: Bearer your_api_key_here" \ -H "Content-Type: application/json" ``` servers: - url: https://app.cotool.ai description: Production server security: - ApiKeyAuth: [] paths: /api/agent-sync/validate: post: tags: - AgentSync summary: Validate Response-Agent-as-Code YAML description: >- 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. requestBody: content: application/json: schema: type: object properties: files: type: array items: type: object properties: path: type: string minLength: 1 description: >- 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. example: agents/triage-suspicious-login.yaml content: type: string description: >- The full raw text of the file. The validator has no repo access, so you send the file contents yourself. example: | apiVersion: cotool.ai/v1 kind: ResponseAgent metadata: sync_key: triage-suspicious-login name: Triage Suspicious Login spec: modelAlias: anthropic:chat:sonnet-4.6 toolNames: [slack] required: - path - content minItems: 1 description: >- 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. skillsPath: type: string minLength: 1 description: >- 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. required: - files responses: '200': description: Successful response content: application/json: schema: type: object properties: valid: type: boolean description: True when every returned result validated with no errors. fileCount: type: number description: Number of validation result rows returned. agentCount: type: number description: Number of schema-valid, graph-clean agents found. results: type: array items: type: object properties: path: type: string valid: type: boolean description: >- True when this file has no error-severity diagnostics. errors: type: array items: type: object properties: code: type: string enum: - yaml_error - schema_error - fetch_error description: Kind of issue. message: type: string description: >- Human-readable explanation (includes the field path for schema errors). required: - code - message description: Issues that would make this file fail to sync. warnings: type: array items: type: object properties: code: type: string enum: - yaml_error - schema_error - fetch_error description: Kind of issue. message: type: string description: >- Human-readable explanation (includes the field path for schema errors). required: - code - message description: >- 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. required: - path - valid - errors - warnings required: - valid - fileCount - agentCount - results '400': description: Bad request — input validation failed or the request was malformed content: application/json: schema: $ref: '#/components/schemas/ValidationError' '401': description: Unauthorized — missing or invalid API key / session content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden — the authenticated user lacks the required permissions content: application/json: schema: $ref: '#/components/schemas/PermissionError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: shell label: cURL source: |- curl -X POST "https://app.cotool.ai/api/agent-sync/validate" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"files":[{"path":"agents/triage-suspicious-login.yaml","content":"apiVersion: cotool.ai/v1\nkind: ResponseAgent\nmetadata:\n sync_key: triage-suspicious-login\n name: Triage Suspicious Login\nspec:\n modelAlias: anthropic:chat:sonnet-4.6\n toolNames: [slack]\n"}],"skillsPath":"string"}' components: schemas: ValidationError: type: object properties: error: type: string description: Error message describing what went wrong issues: type: array description: >- Detailed validation issues, present when request or response schema validation fails items: type: object additionalProperties: true required: - error Error: type: object properties: error: type: string description: Error message describing what went wrong required: - error PermissionError: type: object properties: error: type: string description: Error message describing what went wrong missingPerms: type: array description: Permissions the authenticated user is missing for this operation items: type: string required: - error securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API Key description: >- API Key authentication for programmatic access. Include your API key in the Authorization header as: `Bearer your_api_key_here` ````