cURL

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"}'

import requests

url = "https://app.cotool.ai/api/agent-sync/validate"

payload = {
    "files": [
        {
            "path": "agents/triage-suspicious-login.yaml",
            "content": "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]
"
        }
    ],
    "skillsPath": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>'
  })
};

fetch('https://app.cotool.ai/api/agent-sync/validate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

HttpResponse<String> response = Unirest.post("https://app.cotool.ai/api/agent-sync/validate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"files\": [\n    {\n      \"path\": \"agents/triage-suspicious-login.yaml\",\n      \"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\"\n    }\n  ],\n  \"skillsPath\": \"<string>\"\n}")
  .asString();

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.cotool.ai/api/agent-sync/validate"

	payload := strings.NewReader("{\n  \"files\": [\n    {\n      \"path\": \"agents/triage-suspicious-login.yaml\",\n      \"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\"\n    }\n  ],\n  \"skillsPath\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "valid": true,
  "fileCount": 123,
  "agentCount": 123,
  "results": [
    {
      "path": "<string>",
      "valid": true,
      "errors": [
        {
          "message": "<string>"
        }
      ],
      "warnings": [
        {
          "message": "<string>"
        }
      ]
    }
  ]
}

{
  "error": "<string>",
  "issues": [
    {}
  ]
}

{
  "error": "<string>"
}

{
  "error": "<string>",
  "missingPerms": [
    "<string>"
  ]
}

{
  "error": "<string>"
}

AgentSync

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, 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.

POST

api

agent-sync

validate

cURL

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"}'

import requests

url = "https://app.cotool.ai/api/agent-sync/validate"

payload = {
    "files": [
        {
            "path": "agents/triage-suspicious-login.yaml",
            "content": "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]
"
        }
    ],
    "skillsPath": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>'
  })
};

fetch('https://app.cotool.ai/api/agent-sync/validate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

HttpResponse<String> response = Unirest.post("https://app.cotool.ai/api/agent-sync/validate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"files\": [\n    {\n      \"path\": \"agents/triage-suspicious-login.yaml\",\n      \"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\"\n    }\n  ],\n  \"skillsPath\": \"<string>\"\n}")
  .asString();

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.cotool.ai/api/agent-sync/validate"

	payload := strings.NewReader("{\n  \"files\": [\n    {\n      \"path\": \"agents/triage-suspicious-login.yaml\",\n      \"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\"\n    }\n  ],\n  \"skillsPath\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "valid": true,
  "fileCount": 123,
  "agentCount": 123,
  "results": [
    {
      "path": "<string>",
      "valid": true,
      "errors": [
        {
          "message": "<string>"
        }
      ],
      "warnings": [
        {
          "message": "<string>"
        }
      ]
    }
  ]
}

{
  "error": "<string>",
  "issues": [
    {}
  ]
}

{
  "error": "<string>"
}

{
  "error": "<string>",
  "missingPerms": [
    "<string>"
  ]
}

{
  "error": "<string>"
}

Authorizations

Authorization

string

header

required

API Key authentication for programmatic access. Include your API key in the Authorization header as: Bearer your_api_key_here

Body

application/json

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.

Minimum array length: 1

Show child attributes

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.

Minimum string length: 1

Response

Successful response

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

Show child attributes

Start alert triage run

Get artifact

⌘I