Skip to main content
POST
/
api
/
v1
/
agents
/
{id}
/
validate
Validate Agent
curl --request POST \
  --url https://api.example.com/api/v1/agents/{id}/validate
Test that your agent’s credentials and connectivity are working before running tests.

​
Request

POST /api/v1/agents/{id}/validate
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

ParameterTypeRequiredDescription
idstringYesUUID of the agent to validate

​
Response

FieldTypeDescription
validbooleanWhether the agent is reachable and credentials are valid
messagestringHuman-readable validation result
detailsobjectAdditional validation details (provider-specific)
This endpoint always returns 200 OK. Check the valid field to determine if validation passed.

​
Examples

curl -X POST "https://app.preclinical.dev/api/v1/agents/uuid/validate" \
  -H "Authorization: Bearer $API_KEY"

​
Success Response (Valid)

{
  "valid": true,
  "message": "Agent connectivity verified successfully"
}

​
Success Response (Invalid)

{
  "valid": false,
  "message": "Failed to connect to agent: Invalid API key",
  "details": {
    "error_code": "AUTH_FAILED"
  }
}

​
Errors

CodeDescription
AGENT_NOT_FOUNDAgent not found or doesn’t belong to your organization

​
Use Cases

​
Pre-flight Check Before Testing

async function runTestWithValidation(agentId) {
  // Validate agent first
  const validateResponse = await fetch(
    `https://app.preclinical.dev/api/v1/agents/${agentId}/validate`,
    {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const validation = await validateResponse.json();

  if (!validation.valid) {
    throw new Error(`Agent validation failed: ${validation.message}`);
  }

  // Agent is valid, start the test run
  const runResponse = await fetch(
    'https://app.preclinical.dev/api/v1/runs',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ agent_id: agentId }),
    }
  );

  return runResponse.json();
}